@akash-chowdhury-24/deployhub 2.0.26 → 2.0.28

package/README.md

@@ -651,6 +651,7 @@ All JS frontends share the same install/build flow: `npm ci` → `npm run build`
 
 - **Detect:** `composer.json` with `laravel/framework` or `symfony/framework-bundle`.
 - **Install:** Composer (on CI and server).
+- **CI runtime:** Generated workflows install PHP via `shivammathur/setup-php@v2` with Composer. Default version is **8.4** (meets current Laravel platform requirements). Override with `"phpVersion": "8.3"` at the config root or under `"backend"` in `deployhub.config.json`, then run `deployhub sync-workflows`.
 - **Deploy:** SSH with PHP-FPM or `php artisan` for Laravel.
 
 > ⚠️ **PHP-FPM deployments restart the FPM service for the ENTIRE host on every deploy.** If you run multiple DeployHub-managed environments on the same server, deploying ANY of them will briefly interrupt in-flight requests for ALL of them. For production use with multiple environments, either use separate hosts per environment, or set up per-environment PHP-FPM pools manually (not yet automated by DeployHub).
@@ -695,7 +696,9 @@ git commit -m "Add DeployHub CI"
 2. Add every secret listed at the end of `deployhub init` (storage + deployment).
 3. Push to `main` or `master` — the deploy workflow triggers on push.
 
-The deploy workflow (`deployhub.yml`) installs the correct language runtime (Node, Python, Java, Go, .NET, Ruby) based on your `deployhub.config.json`, installs DeployHub, runs `deployhub build`, and uses your secrets.
+The deploy workflow (`deployhub.yml`) installs the correct language runtime (Node, Python, PHP, Java, Go, .NET, Ruby) based on your `deployhub.config.json`, installs DeployHub, runs `deployhub build`, and uses your secrets. For PHP projects, CI uses `shivammathur/setup-php` (default **8.4**; override with `phpVersion` / `backend.phpVersion`).
+
+When an environment uses Kubernetes, the workflow installs `kubectl` and writes kubeconfig from secrets — but only when that run actually needs cluster access (push with a push-triggered k8s env, or workflow_dispatch / rollback targeting a k8s env, `all`, or blank). Plain pushes that only auto-deploy non-k8s environments (e.g. EC2 development) skip those steps.
 
 To run a deploy manually: **Actions → DeployHub → Run workflow**.
 
@@ -883,13 +886,13 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 - Nginx layout detection and config test before reload (frontend)
 - Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 - OS user suggestion from AMI hint (ubuntu, ec2-user)
-- Optional public IP lookup via `EC2_INSTANCE_ID` + AWS CLI
+- Optional public IP lookup via `EC2_INSTANCE_ID` + `EC2_LOOKUP_AWS_*` (AWS CLI)
 
 **After `init`:**
 1. AWS Console → EC2 → Security Groups → Inbound rules → SSH port 22 from My IP
 2. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
-3. Copy `.env.example` → `.env`; set `SSH_KEY_PATH`, `SSH_HOST` (or `EC2_INSTANCE_ID` + AWS creds)
-4. GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, plus `AWS_*` if using instance ID lookup
+3. Copy `.env.example` → `.env`; set `SSH_KEY_PATH`, `SSH_HOST` (or `EC2_INSTANCE_ID` + `EC2_LOOKUP_AWS_*`)
+4. GitHub Secrets: `SSH_HOST`, `SSH_USER`, `SSH_KEY`, plus `EC2_LOOKUP_AWS_*` if using instance ID lookup (these are **not** the same secrets as AWS S3 storage)
 5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
@@ -898,9 +901,9 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `SSH_USER` | SSH user for AMI | `ec2-user` | AMI documentation |
 | `SSH_KEY_PATH` | Path to .pem key | `~/.ssh/ec2-key.pem` | Downloaded at instance launch |
 | `EC2_INSTANCE_ID` | Instance ID (optional) | `i-0abc123...` | EC2 Console |
-| `AWS_ACCESS_KEY_ID` | AWS key for API lookup | `AKIA...` | IAM → Users → Security credentials |
-| `AWS_SECRET_ACCESS_KEY` | AWS secret | *(secret)* | Same as above |
-| `AWS_REGION` | Instance region | `us-east-1` | EC2 Console top bar |
+| `EC2_LOOKUP_AWS_ACCESS_KEY_ID` | AWS key for EC2 IP lookup (distinct from S3) | `AKIA...` | IAM → Users → Security credentials |
+| `EC2_LOOKUP_AWS_SECRET_ACCESS_KEY` | AWS secret for EC2 IP lookup | *(secret)* | Same as above |
+| `EC2_LOOKUP_AWS_REGION` | Instance region for DescribeInstances | `us-east-1` | EC2 Console top bar |
 
 ### Azure VM
 
@@ -926,7 +929,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 1. Azure Portal → VM → Networking → allow SSH (22) from your IP
 2. Ensure your deploy directory exists and is owned by your SSH user (see prerequisite above if `deployhub doctor` reports permission denied)
 3. Copy `.env.example` → `.env`; set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH`
-4. For CI: add `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` as GitHub Secrets
+4. For CI: add `AZURE_VM_LOOKUP_TENANT_ID`, `AZURE_VM_LOOKUP_CLIENT_ID`, `AZURE_VM_LOOKUP_CLIENT_SECRET` as GitHub Secrets
 5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
@@ -934,9 +937,9 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `SSH_HOST` | VM public IP | `20.1.2.3` | Azure Portal → VM overview |
 | `SSH_USER` | SSH username | `azureuser` | Chosen at VM creation |
 | `SSH_KEY_PATH` | Private key path | `~/.ssh/azure.pem` | Your key file |
-| `AZURE_SUBSCRIPTION_ID` | Subscription (optional) | `uuid` | `az account show` |
-| `AZURE_RESOURCE_GROUP` | Resource group | `my-app-rg` | Portal → Resource groups |
-| `AZURE_VM_NAME` | VM name | `my-vm` | Portal → Virtual machines |
+| `AZURE_VM_LOOKUP_SUBSCRIPTION_ID` | Subscription (optional IP lookup) | `uuid` | `az account show` |
+| `AZURE_VM_LOOKUP_RESOURCE_GROUP` | Resource group | `my-app-rg` | Portal → Resource groups |
+| `AZURE_VM_LOOKUP_VM_NAME` | VM name | `my-vm` | Portal → Virtual machines |
 
 ### GCP VM
 
@@ -975,10 +978,10 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `SSH_APP_NAME` | PM2 process name (backend) | `my-api` | Your choice |
 | `SSH_PORT` | App listen port (backend) | `3000` | Your app config |
 | `SSH_KEY` | Private key contents (CI only) | `-----BEGIN...` | Same key as `SSH_KEY_PATH` |
-| `GCP_PROJECT_ID` | Project ID (optional) | `my-project-123` | `gcloud config get-value project` |
+| `GCP_VM_LOOKUP_PROJECT_ID` | Project ID for VM IP lookup (distinct from GCP Storage) | `my-project-123` | `gcloud config get-value project` |
 | `GCP_ZONE` | VM zone (optional) | `us-central1-a` | VM instance details |
 | `GCP_INSTANCE_NAME` | Instance name (optional) | `my-vm` | Compute Engine list |
-| `GCP_KEY_FILE` | Service account JSON (optional, CI) | `/path/to/key.json` | IAM → Service Accounts → Keys |
+| `GCP_VM_LOOKUP_KEY_FILE` | Service account JSON for VM lookup (distinct from GCP Storage) | `/path/to/key.json` | IAM → Service Accounts → Keys |
 
 ### Kubernetes
 
@@ -993,7 +996,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 **Init prompts (what `deployhub init` asks for Kubernetes):**
 1. Path to kubeconfig file (e.g. `~/.kube/config`)
 2. Kubernetes context
-3. Namespace (defaults to project name)
+3. Namespace (defaults to project name for the first env; additional envs suggest `{project}-{envName}` to avoid collisions)
 4. Container image name
 5. Registry URL (leave empty for Docker Hub)
 6. Registry username (required to push)
@@ -1002,13 +1005,15 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 
 **What DeployHub automates:**
 - Starter `k8s/deployment.yaml` and `k8s/service.yaml` when no manifests exist (skipped if you already have a `k8s/` directory or root-level Kubernetes YAML files)
-- GitHub Actions installs `kubectl` on the CI runner and writes kubeconfig from secrets (no local `kubectl` required for the automated push-to-main deploy path)
+- GitHub Actions installs `kubectl` on the CI runner and writes kubeconfig from secrets when the run targets a Kubernetes environment (skipped on push when k8s is manual-only)
 - Lists `kubectl` contexts during `init` for easy selection
 - Auto-detects `~/.kube/config`
 - Complete `.env.example` for kubeconfig, context, namespace, and registry settings
 - Cluster connectivity test during `init`
 - On deploy: registry login → reuse or build image → push (unique tag unless `DOCKER_IMAGE_TAG` is set) → ensure namespace exists (prompt locally / auto-create in CI) → `kubectl apply` → `kubectl set image` with the full resolved image ref → `kubectl rollout restart` when that ref is unchanged so pods pick up a new digest
 
+> **Limitation — interpreted backends (Node / Python / PHP / Rails) + rollback:** Kubernetes rollback forces a rebuild from the restored artifact when the exact `buildId` image is not already local. Those artifacts ship source/`composer.json` (etc.) but **not** installed deps (`vendor/`, `node_modules`, …), so DeployHub **refuses** with a clear error instead of a confusing Docker build failure. Successful rollback needs the restored image tag already present locally (or a prior `pipeline.docker` build that produced it). Same rule as standalone Docker deploy fallback.
+
 > **Limitation — multiple Kubernetes clusters:** A generated workflow writes **one** kubeconfig file per job. Multiple Kubernetes environments that target **different clusters** in the same workflow run are not yet fully supported (follow-up). Same-cluster multi-namespace / multi-env is fine.
 
 **After `init`:**
@@ -1140,7 +1145,20 @@ Run `deployhub doctor` after any config change.
 | `deployhub clean` | Remove old local artifacts |
 | `deployhub update` | Check for CLI updates |
 
-**Tests:** `npm test` — currently **320 passing** across the Jest suites.
+**Tests:** `npm test` — currently **442 passing** across the Jest suites (1 skipped).
+
+## Storage vs deployment lookup credentials
+
+Storage credentials (`AWS_*` for S3, `GCP_*` for GCP Storage, …) are **project-wide and unprefixed**. Optional cloud-API credentials used only for **dynamic VM IP lookup** on EC2 / Azure VM / GCP VM use a distinct `{METHOD}_LOOKUP_…` namespace so they never collide with storage — even on a single-environment project.
+
+| Concern | Examples |
+|---------|----------|
+| Storage | `AWS_ACCESS_KEY_ID`, `GCP_PROJECT_ID`, `GCP_KEY_FILE` |
+| EC2 instance-IP lookup | `EC2_LOOKUP_AWS_ACCESS_KEY_ID`, `EC2_LOOKUP_AWS_SECRET_ACCESS_KEY`, `EC2_LOOKUP_AWS_REGION` |
+| GCP VM IP lookup | `GCP_VM_LOOKUP_PROJECT_ID`, `GCP_VM_LOOKUP_KEY_FILE` |
+| Azure VM IP lookup | `AZURE_VM_LOOKUP_SUBSCRIPTION_ID`, `AZURE_VM_LOOKUP_RESOURCE_GROUP`, `AZURE_VM_LOOKUP_VM_NAME`, … |
+
+Multi-env secret prefixing still applies on top (e.g. `PRODUCTION_EC2_LOOKUP_AWS_ACCESS_KEY_ID`).
 
 ## GitHub Secrets
 
@@ -1164,7 +1182,7 @@ Add these secrets in your repository (Settings → Secrets and variables → Act
 | `GCP_KEY_FILE` | GCP Storage |
 | `GCP_BUCKET` | GCP Storage |
 | `DROPBOX_ACCESS_TOKEN` | Dropbox |
-| `FTP_HOST`, `FTP_USER`, `FTP_PASSWORD` | FTP storage |
+| `FTP_HOST`, `FTP_USER`, `FTP_PASSWORD`, `FTP_PORT`, `FTP_PATH` | FTP storage (`FTP_PORT` default 21, `FTP_PATH` default `/uploads` — connection tuning, not secrets) |
 
 ### Server deployment (SSH, EC2, VMs, Docker, Kubernetes)
 
@@ -1178,9 +1196,9 @@ Add these secrets in your repository (Settings → Secrets and variables → Act
 | `SSH_DEPLOY_PATH` | Remote directory (optional if set in config) |
 | `SSH_APP_NAME` | PM2 process name for backends |
 | `SSH_PORT` | App port on server (backend) |
-| `EC2_INSTANCE_ID`, `AWS_*` | Optional EC2 dynamic IP lookup |
-| `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_VM_NAME` | Optional Azure VM IP lookup |
-| `GCP_PROJECT_ID`, `GCP_ZONE`, `GCP_INSTANCE_NAME`, `GCP_KEY_FILE` | Optional GCP VM IP lookup |
+| `EC2_INSTANCE_ID`, `EC2_LOOKUP_AWS_*` | Optional EC2 dynamic IP lookup (distinct from S3 `AWS_*`) |
+| `AZURE_VM_LOOKUP_SUBSCRIPTION_ID`, `AZURE_VM_LOOKUP_RESOURCE_GROUP`, `AZURE_VM_LOOKUP_VM_NAME` | Optional Azure VM IP lookup |
+| `GCP_VM_LOOKUP_PROJECT_ID`, `GCP_ZONE`, `GCP_INSTANCE_NAME`, `GCP_VM_LOOKUP_KEY_FILE` | Optional GCP VM IP lookup (project/key distinct from GCP Storage) |
 | `DOCKER_IMAGE_NAME`, `DOCKER_REGISTRY_USERNAME`, `DOCKER_REGISTRY_TOKEN`, `DOCKER_REGISTRY_URL`, `DOCKER_HOST` | Docker deployment (`DOCKER_IMAGE_TAG` optional) |
 | `KUBECONFIG`, `KUBE_CONTEXT`, `KUBE_NAMESPACE`, `DOCKER_IMAGE_NAME`, `DOCKER_REGISTRY_USERNAME`, `DOCKER_REGISTRY_TOKEN`, `DOCKER_REGISTRY_URL`, `DOCKER_IMAGE_TAG`, `KUBE_IMAGE_PULL_SECRET` | Kubernetes — **`KUBECONFIG` in GitHub Secrets must be the kubeconfig file contents (or base64), not a filesystem path**. `DOCKER_IMAGE_TAG`, `KUBE_NAMESPACE`, `DOCKER_REGISTRY_URL`, and `KUBE_IMAGE_PULL_SECRET` are optional |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.26",
+  "version": "2.0.28",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/adapters/index.js

@@ -32,6 +32,7 @@ const ADAPTERS = {
   go: goAdapter,
   dotnet: dotnetAdapter,
   rails: railsAdapter,
+  ruby: railsAdapter,
 };
 
 /**

package/src/artifact/engine.js

@@ -241,7 +241,7 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
     await copyDirectoryIfExists(cwd, stagingDir, 'resources');
     await copyDirectoryIfExists(cwd, stagingDir, 'storage');
     await copyDirectoryIfExists(cwd, stagingDir, 'bin');
-  } else if (framework === 'spring') {
+  } else if (framework === 'spring' || framework === 'java') {
     await copyIfExists(cwd, stagingDir, 'pom.xml');
     const targetDir = path.join(cwd, 'target');
     if (await fs.pathExists(targetDir)) {
@@ -261,7 +261,7 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
       await copyIfExists(cwd, stagingDir, f);
     }
     await copyDirectoryIfExists(cwd, stagingDir, settings.buildOutput || 'publish');
-  } else if (framework === 'rails') {
+  } else if (framework === 'rails' || framework === 'ruby') {
     await copyIfExists(cwd, stagingDir, 'Gemfile');
     await copyIfExists(cwd, stagingDir, 'Gemfile.lock');
     await copyIfExists(cwd, stagingDir, 'config.ru');

package/src/commands/doctor.js

@@ -13,7 +13,7 @@ import {
 import { loadEnvArtifactHistory } from '../storage/index.js';
 import { testProvider } from '../storage/index.js';
 import { getDeploymentProvider } from '../deployment/index.js';
-import { PROVIDER_ENV_MAP, getRollbackWorkflowDoctorCheck, getWorkflowDriftDoctorChecks } from '../utils/github-actions.js';
+import { PROVIDER_ENV_MAP, STORAGE_PROVIDER_IDS, getRollbackWorkflowDoctorCheck, getWorkflowDriftDoctorChecks } from '../utils/github-actions.js';
 import { printDoctorFooter } from '../utils/author.js';
 import { createLocalProvider } from '../storage/providers/local.js';
 import {
@@ -561,9 +561,12 @@ export async function runDeploymentChecks(config, envName, envConfig) {
   if (deployType === 'ec2' && process.env.EC2_INSTANCE_ID) {
     checks.push(
       await runCheck('EC2 API', async () => {
-        const missing = ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION'].filter(
-          (k) => !process.env[k]
-        );
+        const required = [
+          'EC2_LOOKUP_AWS_ACCESS_KEY_ID',
+          'EC2_LOOKUP_AWS_SECRET_ACCESS_KEY',
+          'EC2_LOOKUP_AWS_REGION',
+        ];
+        const missing = required.filter((k) => !process.env[k]);
         if (missing.length > 0) {
           return {
             name: 'EC2 API',
@@ -969,6 +972,7 @@ export function registerDoctorCommand(program) {
           /** @type {string[]} */
           const required = [];
           for (const provider of config.storage || []) {
+            if (!STORAGE_PROVIDER_IDS.has(provider)) continue;
             const keys = PROVIDER_ENV_MAP[provider] || [];
             required.push(...keys);
           }

package/src/commands/init.js

@@ -54,15 +54,20 @@ const BACKEND_CHOICES = [
   { name: 'Node.js — NestJS', value: 'nestjs' },
   { name: 'Node.js — Fastify', value: 'fastify' },
   { name: 'Node.js — Koa', value: 'koa' },
+  { name: 'Node.js — plain', value: 'node' },
   { name: 'Python — FastAPI', value: 'fastapi' },
   { name: 'Python — Django', value: 'django' },
   { name: 'Python — Flask', value: 'flask' },
+  { name: 'Python — plain', value: 'python' },
   { name: 'PHP — Laravel', value: 'laravel' },
   { name: 'PHP — Symfony', value: 'symfony' },
+  { name: 'PHP — plain (Composer / .php)', value: 'php' },
   { name: 'Java — Spring Boot', value: 'spring' },
+  { name: 'Java — plain (Maven/Gradle)', value: 'java' },
   { name: 'Go', value: 'go' },
   { name: '.NET (ASP.NET Core)', value: 'dotnet' },
   { name: 'Ruby on Rails', value: 'rails' },
+  { name: 'Ruby — plain (Rack/Puma)', value: 'ruby' },
   { name: "Other (I'll configure manually)", value: 'other' },
 ];
 

package/src/core/config.js

@@ -20,6 +20,8 @@ import {
 const SideConfigSchema = z.object({
   framework: z.string(),
   language: z.string().optional(),
+  /** PHP runtime for CI (`shivammathur/setup-php`); e.g. `"8.4"`. */
+  phpVersion: z.string().optional(),
   buildCommand: z.string().nullable().optional(),
   startCommand: z.string().nullable().optional(),
   buildOutput: z.string().optional(),
@@ -81,6 +83,11 @@ const ConfigSchema = z.object({
   projectType: z.enum(['frontend', 'backend', 'both']).default('frontend'),
   framework: z.string().optional(),
   language: z.string().optional(),
+  /**
+   * PHP runtime for generated GitHub Actions (`shivammathur/setup-php`).
+   * Prefer `backend.phpVersion` for backend/both projects. Default when unset: `8.4`.
+   */
+  phpVersion: z.string().optional(),
   buildCommand: z.string().nullable().optional(),
   startCommand: z.string().nullable().optional(),
   buildOutput: z.string().optional(),

package/src/deployment/deployment-env.js

@@ -169,27 +169,32 @@ export const DEPLOYMENT_ENV_DEFS = {
       when: 'optional',
     },
     {
-      key: 'AWS_ACCESS_KEY_ID',
+      key: 'EC2_LOOKUP_AWS_ACCESS_KEY_ID',
       optionalReason:
         'only required if using EC2_INSTANCE_ID for dynamic IP lookup; otherwise leave blank',
       comment: [
+        'EC2 instance-IP lookup credential (NOT the same as AWS S3 storage credentials).',
         'AWS access key with ec2:DescribeInstances permission.',
         'Create in AWS Console → IAM → Users → Security credentials.',
       ],
       when: 'optional',
     },
     {
-      key: 'AWS_SECRET_ACCESS_KEY',
+      key: 'EC2_LOOKUP_AWS_SECRET_ACCESS_KEY',
       optionalReason:
         'only required if using EC2_INSTANCE_ID for dynamic IP lookup; otherwise leave blank',
-      comment: ['Secret for the AWS access key above.'],
+      comment: [
+        'Secret for EC2_LOOKUP_AWS_ACCESS_KEY_ID (distinct from AWS_SECRET_ACCESS_KEY used by S3).',
+      ],
       when: 'optional',
     },
     {
-      key: 'AWS_REGION',
+      key: 'EC2_LOOKUP_AWS_REGION',
       optionalReason:
         'only required if using EC2_INSTANCE_ID for dynamic IP lookup; otherwise leave blank',
-      comment: ['AWS region where your EC2 instance runs.'],
+      comment: [
+        'AWS region for EC2 DescribeInstances lookup (distinct from AWS_REGION used by S3).',
+      ],
       example: 'us-east-1',
       when: 'optional',
     },
@@ -199,52 +204,60 @@ export const DEPLOYMENT_ENV_DEFS = {
     ...SSH_BACKEND_ENV_VARS,
     ...SSH_CI_ENV_VARS,
     {
-      key: 'AZURE_SUBSCRIPTION_ID',
+      key: 'AZURE_VM_LOOKUP_SUBSCRIPTION_ID',
       optionalReason:
         'only required for dynamic VM IP lookup via Azure API; otherwise set SSH_HOST directly',
       comment: [
-        'Azure subscription ID. Used to look up VM public IP via Azure API.',
+        'Azure VM IP-lookup subscription ID (deployment-side; not Azure Blob storage).',
         'Find in Azure Portal → Subscriptions, or run: az account show --query id -o tsv',
       ],
       when: 'optional',
     },
     {
-      key: 'AZURE_RESOURCE_GROUP',
+      key: 'AZURE_VM_LOOKUP_RESOURCE_GROUP',
       optionalReason:
         'only required for dynamic VM IP lookup via Azure API; otherwise leave blank',
-      comment: ['Resource group containing your VM.'],
+      comment: [
+        'Resource group containing your VM (deployment lookup; not Azure Blob storage).',
+      ],
       example: 'my-app-rg',
       when: 'optional',
     },
     {
-      key: 'AZURE_VM_NAME',
+      key: 'AZURE_VM_LOOKUP_VM_NAME',
       optionalReason:
         'only required for dynamic VM IP lookup via Azure API; otherwise set SSH_HOST directly',
       comment: [
-        'Name of the Azure virtual machine.',
+        'Name of the Azure virtual machine for IP lookup.',
         'If unset, SSH_HOST must be set to the VM public IP or DNS.',
       ],
       when: 'optional',
     },
     {
-      key: 'AZURE_TENANT_ID',
+      key: 'AZURE_VM_LOOKUP_TENANT_ID',
       optionalReason:
         'only required for non-interactive CI deploys (GitHub Actions) using a service principal',
-      comment: ['Azure AD tenant ID for service principal auth in CI.'],
+      comment: [
+        'Azure AD tenant ID for service principal auth in CI (VM deploy lookup).',
+      ],
       when: 'optional',
     },
     {
-      key: 'AZURE_CLIENT_ID',
+      key: 'AZURE_VM_LOOKUP_CLIENT_ID',
       optionalReason:
         'only required for non-interactive CI deploys (GitHub Actions) using a service principal',
-      comment: ['Service principal application (client) ID for CI auth.'],
+      comment: [
+        'Service principal application (client) ID for CI auth (VM deploy lookup).',
+      ],
       when: 'optional',
     },
     {
-      key: 'AZURE_CLIENT_SECRET',
+      key: 'AZURE_VM_LOOKUP_CLIENT_SECRET',
       optionalReason:
         'only required for non-interactive CI deploys (GitHub Actions) using a service principal',
-      comment: ['Service principal client secret for CI auth.'],
+      comment: [
+        'Service principal client secret for CI auth (VM deploy lookup).',
+      ],
       when: 'optional',
     },
   ],
@@ -253,11 +266,11 @@ export const DEPLOYMENT_ENV_DEFS = {
     ...SSH_BACKEND_ENV_VARS,
     ...SSH_CI_ENV_VARS,
     {
-      key: 'GCP_PROJECT_ID',
+      key: 'GCP_VM_LOOKUP_PROJECT_ID',
       optionalReason:
         'only required for dynamic VM IP lookup via GCP API; otherwise set SSH_HOST directly',
       comment: [
-        'GCP project ID. Used to look up VM IP via Compute API.',
+        'GCP project ID for Compute Engine IP lookup (NOT the same as GCP Storage GCP_PROJECT_ID).',
         'Find in GCP Console → Dashboard, or run: gcloud config get-value project',
       ],
       when: 'optional',
@@ -282,11 +295,11 @@ export const DEPLOYMENT_ENV_DEFS = {
       when: 'optional',
     },
     {
-      key: 'GCP_KEY_FILE',
+      key: 'GCP_VM_LOOKUP_KEY_FILE',
       optionalReason:
         'only required for dynamic VM IP lookup via GCP API or non-interactive CI auth; otherwise leave blank',
       comment: [
-        'Path to a GCP service account JSON key file.',
+        'Path to a GCP service account JSON key for VM IP lookup (distinct from GCP Storage GCP_KEY_FILE).',
         'Create in GCP Console → IAM → Service Accounts → Keys.',
       ],
       when: 'optional',
@@ -381,6 +394,27 @@ export const DEPLOYMENT_ENV_KEYS = Object.fromEntries(
   ])
 );
 
+/**
+ * Deployment-side cloud-API lookup credentials — distinct from storage-provider
+ * env vars (storage stays project-wide / unprefixed).
+ *
+ * Convention: `{METHOD}_LOOKUP_…` — method-scoped, purpose-clear, layers under
+ * the existing multi-env prefixing system (e.g. PRODUCTION_EC2_LOOKUP_AWS_ACCESS_KEY_ID).
+ */
+export const DEPLOYMENT_LOOKUP_ENV_KEYS = new Set([
+  'EC2_LOOKUP_AWS_ACCESS_KEY_ID',
+  'EC2_LOOKUP_AWS_SECRET_ACCESS_KEY',
+  'EC2_LOOKUP_AWS_REGION',
+  'AZURE_VM_LOOKUP_SUBSCRIPTION_ID',
+  'AZURE_VM_LOOKUP_RESOURCE_GROUP',
+  'AZURE_VM_LOOKUP_VM_NAME',
+  'AZURE_VM_LOOKUP_TENANT_ID',
+  'AZURE_VM_LOOKUP_CLIENT_ID',
+  'AZURE_VM_LOOKUP_CLIENT_SECRET',
+  'GCP_VM_LOOKUP_PROJECT_ID',
+  'GCP_VM_LOOKUP_KEY_FILE',
+]);
+
 /**
  * Locally required env keys for doctor method-specific checks.
  * Excludes optional and CI-only vars.
@@ -482,13 +516,25 @@ export function getDeploymentSecretChecklistItems(deployType, config = null) {
 
     const key = toGithubSecretKey(d.key);
     const required = d.when !== 'optional';
-    const note =
+    let note =
       d.when === 'optional'
         ? d.optionalReason
         : d.when === 'ci'
           ? d.optionalReason || 'required for GitHub Actions CI (paste private key contents)'
           : undefined;
 
+    if (DEPLOYMENT_LOOKUP_ENV_KEYS.has(d.key)) {
+      const purpose =
+        deployType === 'ec2'
+          ? 'EC2 instance-IP lookup credential (distinct from AWS S3 storage)'
+          : deployType === 'gcp-vm'
+            ? 'GCP VM instance-IP lookup credential (distinct from GCP Storage)'
+            : deployType === 'azure-vm'
+              ? 'Azure VM IP-lookup credential (distinct from Azure Blob storage)'
+              : 'deployment cloud-API lookup credential';
+      note = note ? `${purpose}; ${note}` : purpose;
+    }
+
     const existing = byKey.get(key);
     if (existing) {
       // Prefer required if any def for this key is required
@@ -731,21 +777,48 @@ export function formatSecretChecklistLine(item) {
  * @param {string} deployType
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @param {Record<string, Record<string, unknown>>} [environments]
+ * @param {{ envName?: string }} [options]
  * @returns {string}
  */
 export function generateDeploymentEnvSection(
   deployType,
   config = null,
-  environments = {}
+  environments = {},
+  options = {}
 ) {
   const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
+  const envName = options.envName;
+  const cfg = {
+    ...(config || {}),
+    environments: environments || config?.environments || {},
+  };
+  const shouldPrefix =
+    !!envName && envUsesPrefixedSecrets(envName, /** @type {any} */ (cfg));
 
-  const title = DEPLOYMENT_SECTION_TITLES[deployType] || deployType;
+  const baseTitle = DEPLOYMENT_SECTION_TITLES[deployType] || deployType;
+  const title =
+    envName && Object.keys(environments || {}).length > 1
+      ? `${baseTitle} (${envName})`
+      : baseTitle;
   /** @type {string[]} */
   const lines = [`# ${title}`];
 
+  // Prefer defaults from this environment's config when generating per-env sections.
+  const envEntry = envName
+    ? /** @type {Record<string, unknown>} */ (
+        (environments || {})[envName] || {}
+      )
+    : /** @type {Record<string, unknown>} */ (
+        Object.values(environments || {})[0] || {}
+      );
+  // Support both new { config: {...} } shape and flat legacy env entries.
+  const settings =
+    envEntry && typeof envEntry.config === 'object' && envEntry.config
+      ? /** @type {Record<string, unknown>} */ (envEntry.config)
+      : envEntry;
+
   for (const d of defs) {
     if (d.when === 'backend' && !isBackend) continue;
 
@@ -762,8 +835,10 @@ export function generateDeploymentEnvSection(
       lines.push(`# Example: ${d.example}`);
     }
 
-    const defaultVal = d.default || getDefaultFromConfig(d.key, config, environments);
-    lines.push(defaultVal ? `${d.key}=${defaultVal}` : `${d.key}=`);
+    const key = shouldPrefix ? prefixSecretKey(envName, d.key) : d.key;
+    const defaultVal =
+      d.default || getDefaultFromConfig(d.key, config, settings);
+    lines.push(defaultVal ? `${key}=${defaultVal}` : `${key}=`);
     lines.push('');
   }
 
@@ -774,23 +849,21 @@ export function generateDeploymentEnvSection(
 /**
  * @param {string} key
  * @param {import('../core/config.js').DeployHubConfig} [config]
- * @param {Record<string, Record<string, unknown>>} [environments]
+ * @param {Record<string, unknown>} [settings]
  */
-function getDefaultFromConfig(key, config, environments) {
-  const envEntry = Object.values(environments || {})[0] || {};
-
+function getDefaultFromConfig(key, config, settings = {}) {
   const map = {
-    SSH_HOST: envEntry.host,
-    SSH_USER: envEntry.user,
-    SSH_DEPLOY_PATH: envEntry.deployPath || envEntry.path,
-    SSH_APP_NAME: envEntry.appName,
+    SSH_HOST: settings.host,
+    SSH_USER: settings.user,
+    SSH_DEPLOY_PATH: settings.deployPath || settings.path,
+    SSH_APP_NAME: settings.appName,
     SSH_PORT: config?.port || config?.backend?.port,
     SSH_SSH_PORT: '22',
-    KUBE_NAMESPACE: config?.project || 'default',
-    DOCKER_IMAGE_NAME: config?.project,
+    KUBE_NAMESPACE: settings.kubeNamespace || config?.project || 'default',
+    DOCKER_IMAGE_NAME: settings.dockerImageName || config?.project,
     DOCKER_IMAGE_TAG: '',
-    DOCKER_REGISTRY_URL: envEntry.dockerRegistryUrl,
-    AWS_REGION: 'us-east-1',
+    DOCKER_REGISTRY_URL: settings.dockerRegistryUrl,
+    EC2_LOOKUP_AWS_REGION: settings.awsRegion || 'us-east-1',
   };
 
   const val = map[key];
@@ -871,8 +944,8 @@ export const DEPLOYMENT_GUIDE = {
     after: [
       'AWS Console → EC2 → Security Groups → your instance group → Inbound rules →',
       '  Add rule: SSH, port 22, source: My IP',
-      'Copy .env.example to .env — set SSH_KEY_PATH, SSH_HOST (or EC2_INSTANCE_ID + AWS creds).',
-      'Add GitHub Secrets: SSH_HOST, SSH_USER, SSH_KEY, plus AWS_* if using instance ID lookup.',
+      'Copy .env.example to .env — set SSH_KEY_PATH, SSH_HOST (or EC2_INSTANCE_ID + EC2_LOOKUP_AWS_*).',
+      'Add GitHub Secrets: SSH_HOST, SSH_USER, SSH_KEY, plus EC2_LOOKUP_AWS_* if using instance ID lookup (distinct from S3 AWS_*).',
       'Run deployhub doctor to verify SSH and optional AWS API access.',
       'git push origin main to trigger your first deployment.',
     ],
@@ -893,7 +966,7 @@ export const DEPLOYMENT_GUIDE = {
       'Azure Portal → VM → Networking → Inbound port rules → allow SSH (22) from your IP.',
       'Or: az network nsg rule create --name AllowSSH --priority 1000 --source-address-prefix YOUR_IP ...',
       'Copy .env.example to .env and fill in SSH_HOST, SSH_USER, SSH_KEY_PATH.',
-      'For CI: add AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET as GitHub Secrets.',
+      'For CI: add AZURE_VM_LOOKUP_TENANT_ID, AZURE_VM_LOOKUP_CLIENT_ID, AZURE_VM_LOOKUP_CLIENT_SECRET as GitHub Secrets.',
       'Run deployhub doctor, then git push origin main.',
     ],
   },
@@ -940,6 +1013,7 @@ export const DEPLOYMENT_GUIDE = {
       'Copy .env.example to .env and set DOCKER_IMAGE_NAME, DOCKER_REGISTRY_USERNAME, and DOCKER_REGISTRY_TOKEN.',
       'Skipping registry credentials will very likely cause ImagePullBackOff — the cluster cannot see local Docker images.',
       'For private registries: also create kubectl create secret docker-registry ... and set KUBE_IMAGE_PULL_SECRET.',
+      'Interpreted backends (Node/Python/PHP/Rails): rollback refuses to rebuild from the artifact when the buildId image is not local — keep pipeline.docker builds so the restored tag exists.',
       'Add the GitHub Secrets listed below (Settings → Secrets and variables → Actions).',
       'Run deployhub doctor to verify cluster access and that your image is pullable.',
       'git push origin main to trigger your first deployment.',