@akash-chowdhury-24/deployhub 2.0.3 → 2.0.5

package/README.md

@@ -185,6 +185,8 @@ The wizard asks the same core questions for every setup:
 - `.github/workflows/deployhub.yml` — CI pipeline
 - `.env.example` — list of env vars you may need
 - `nginx.conf` — auto-generated if frontend deploys to SSH
+- `Dockerfile` — auto-generated if missing and you chose Docker or Kubernetes deploy (your existing `Dockerfile` is never overwritten)
+- `k8s/deployment.yaml` and `k8s/service.yaml` — auto-generated if missing and you chose Kubernetes deploy (existing manifests are never overwritten)
 
 ---
 
@@ -596,7 +598,7 @@ DeployHub supports six deployment targets. Pick based on what infrastructure you
 | **ec2** | AWS users with an existing EC2 instance | Running EC2 instance, security group, key pair |
 | **azure-vm** | Azure users with an existing virtual machine | Running Azure VM, NSG allowing SSH |
 | **gcp-vm** | GCP users with an existing Compute Engine VM | Running VM, firewall rule for SSH, metadata SSH key |
-| **kubernetes** | Teams with an existing K8s cluster | Cluster, kubectl access, manifests in repo |
+| **kubernetes** | Teams with an existing K8s cluster | Cluster, kubectl access; manifests auto-generated if missing |
 
 ---
 
@@ -604,9 +606,38 @@ DeployHub supports six deployment targets. Pick based on what infrastructure you
 
 Each method below follows the same structure: **prerequisites** (before `deployhub init`), **what DeployHub automates**, **after init** (matches terminal output), and a **variable reference**.
 
+### One-time server setup (before your first deploy)
+
+SSH-based methods (SSH, EC2, Azure VM, GCP VM) require a few one-time steps on the server **before your first deploy**. DeployHub does not silently change ownership or sudo policy for you.
+
+SSH into your server once and run:
+
+```bash
+sudo mkdir -p /var/www/your-app-name
+sudo chown your-ssh-user:your-ssh-user /var/www/your-app-name
+```
+
+Replace `/var/www/your-app-name` with your actual deploy path and `your-ssh-user` with your configured `SSH_USER` (e.g. `ec2-user` on Amazon Linux, `ubuntu` on Ubuntu). Without this, DeployHub cannot write your build output — `deployhub doctor` will catch it and show the exact fix.
+
+**Frontend deploys** that auto-activate `nginx.conf` also need **passwordless sudo** for Nginx test/reload (and `cp` into `/etc/nginx/`). After installing Nginx, run `sudo visudo` and add a line like:
+
+```bash
+your-ssh-user ALL=(ALL) NOPASSWD: /usr/sbin/nginx, /bin/cp, /usr/bin/cp, /bin/systemctl, /usr/bin/systemctl
+```
+
+> **Security note:** This example grants broad privileges — unrestricted `cp` (any source/destination) and `systemctl` (any unit/action), not just Nginx. That keeps setup simple but is a significant trust boundary. For production, prefer a dedicated deploy user and a **narrow wrapper script** (e.g. `/usr/local/bin/deployhub-nginx-reload` that only copies to your project's config path and runs `nginx -t` + reload), then grant `NOPASSWD` only for that script. The line above is a starting point for dev/test servers; tighten it before production.
+
+Install Nginx if it is not already present:
+
+- **Amazon Linux / RHEL:** `sudo yum install -y nginx && sudo systemctl enable --now nginx`
+- **Ubuntu / Debian:** `sudo apt install -y nginx`
+
+DeployHub detects whether the server uses Debian-style `sites-available` or RHEL-style `conf.d` at deploy time and writes a **uniquely named** config file for your project only — it does not overwrite unrelated Nginx configs.
+
 ### SSH
 
 **Prerequisites (before `deployhub init`):**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (deploy path ownership + Nginx/sudo for frontends)
 - [ ] A Linux server with SSH enabled
 - [ ] Private SSH key file (.pem/.key) and public key in `authorized_keys`
 - [ ] Port 22 open in firewall for your IP
@@ -618,6 +649,9 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - SSH key permission check (offers to `chmod 600`)
 - SSH connectivity test during `init`
 - Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection (Debian `sites-available` vs RHEL `conf.d`) at deploy time
+- Nginx config test (`nginx -t`) before reload
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 - Artifact upload, extract, app restart (PM2, gunicorn, etc.)
 
 **After `init`:**
@@ -643,10 +677,11 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 
 **Prerequisites:**
 - [ ] Docker installed (`docker --version` works)
-- [ ] `Dockerfile` or `docker-compose.yml` in project
 - [ ] Registry account if pushing private images
+- [ ] `docker-compose.yml` in project if you use multi-service Compose (not auto-generated)
 
 **What DeployHub automates:**
+- Starter `Dockerfile` at project root when none exists (framework-aware; skipped if you already have one)
 - `.env.example` for image name, registry, remote `DOCKER_HOST`
 - Docker daemon connectivity test during `init`
 - `docker compose up` or build/push/run during deploy
@@ -669,6 +704,7 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### AWS EC2
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (`ec2-user` on Amazon Linux)
 - [ ] EC2 instance launched in AWS Console (DeployHub does not create it)
 - [ ] Key pair `.pem` downloaded at launch
 - [ ] Security group: inbound SSH (22) from your IP
@@ -679,6 +715,8 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - EC2-specific `.env.example` (SSH + optional AWS API vars)
 - SSH key validation and connectivity test
 - Deploy path write-permission check during `deployhub doctor`
+- 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
 
@@ -702,6 +740,7 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### Azure VM
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (`azureuser` or your VM login user)
 - [ ] Azure VM created in Portal (DeployHub does not provision it)
 - [ ] NSG rule allowing inbound SSH (port 22)
 - [ ] SSH public key on the VM
@@ -713,6 +752,8 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - Auto-detects subscription ID via `az` CLI if logged in
 - SSH key validation and connectivity test
 - Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection and config test before reload (frontend)
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 
 **After `init`:**
 1. Azure Portal → VM → Networking → allow SSH (22) from your IP
@@ -733,6 +774,7 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 ### GCP VM
 
 **Prerequisites:**
+- [ ] Complete **[one-time server setup](#one-time-server-setup-before-your-first-deploy)** (your GCP SSH username)
 - [ ] Compute Engine VM created (DeployHub does not create it)
 - [ ] Firewall rule allowing `tcp:22` (default `default-allow-ssh` may exist)
 - [ ] SSH public key in **Metadata → SSH Keys** (GCP uses metadata keys, not launch key pairs like AWS)
@@ -744,6 +786,8 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 - Auto-detects project ID via `gcloud` if authenticated
 - SSH key validation and connectivity test
 - Deploy path write-permission check during `deployhub doctor`
+- Nginx layout detection and config test before reload (frontend)
+- Passwordless sudo and Nginx checks during `deployhub doctor` (frontend)
 
 **After `init`:**
 1. GCP Console → VPC → Firewall → ensure SSH (tcp:22) allowed from your IP
@@ -771,11 +815,12 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 
 **Prerequisites:**
 - [ ] Existing Kubernetes cluster (DeployHub does not provision clusters)
-- [ ] `kubectl` installed and configured
-- [ ] Kubernetes manifests (`.yaml` or `k8s/` directory) in your repo
+- [ ] `kubectl` installed and configured on your **local machine** (for `deployhub doctor` / manual `deployhub deploy`)
 - [ ] Cluster reachable from CI (kubeconfig secret or cloud auth)
 
 **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)
 - Lists `kubectl` contexts during `init` for easy selection
 - Auto-detects `~/.kube/config`
 - Complete `.env.example` for kubeconfig, context, namespace
@@ -794,6 +839,7 @@ Each method below follows the same structure: **prerequisites** (before `deployh
 | `KUBE_CONTEXT` | Context name | `my-cluster` | `kubectl config get-contexts` |
 | `KUBE_NAMESPACE` | Target namespace | `my-app` | `kubectl get namespaces` |
 | `DOCKER_IMAGE_NAME` | Container image | `ghcr.io/org/app` | Your registry |
+| `DOCKER_IMAGE_TAG` | Image tag | `1.0.0` or `latest` | Project version or your choice |
 | `KUBE_IMAGE_PULL_SECRET` | Pull secret name | `regcred` | `kubectl create secret docker-registry` |
 
 ---

package/package.json

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

package/src/artifact/engine.js

@@ -6,6 +6,11 @@ import { createLogger } from '../logger/index.js';
 import { generateChecksums, formatChecksums } from '../utils/checksums.js';
 import { getProjectVersion } from '../utils/version.js';
 import { generateNginxConfig } from '../utils/nginx.js';
+import {
+  ensureDeployScaffold,
+  copyKubernetesManifestsIfPresent,
+  copyDeployAssetsToArtifactDir,
+} from '../utils/scaffold.js';
 import { getGeneratedByMetadata, getArtifactReadmeFooter } from '../utils/author.js';
 
 /**
@@ -143,6 +148,8 @@ async function stageFrontendArtifact(cwd, stagingDir, config) {
     await copyIfExists(cwd, stagingDir, file);
   }
 
+  await copyKubernetesManifestsIfPresent(cwd, stagingDir);
+
   const hasSshDeploy = (config.deploy || []).some(
     (envName) => config.environments[envName]?.type === 'ssh'
   );
@@ -172,6 +179,8 @@ async function stageBackendArtifact(cwd, stagingDir, config) {
     await copyIfExists(cwd, stagingDir, file);
   }
 
+  await copyKubernetesManifestsIfPresent(cwd, stagingDir);
+
   await copyDirectoryIfExists(cwd, stagingDir, 'config');
   await copyDirectoryIfExists(cwd, stagingDir, 'migrations');
 
@@ -259,6 +268,8 @@ export async function createArtifact(config, deployedTargets = [], cwd = process
 
   log.info(`Staging ${projectType} artifact...`);
 
+  await ensureDeployScaffold(cwd, config, config.environments || {}, { silent: false });
+
   if (projectType === 'both') {
     await stageFrontendArtifact(cwd, stagingDir, config);
     const backendStaging = path.join(stagingDir, 'backend');
@@ -337,6 +348,8 @@ ${getArtifactReadmeFooter()}`;
   const zipPath = path.join(artifactDir, 'artifact.zip');
   await createZip(stagingDir, zipPath);
 
+  await copyDeployAssetsToArtifactDir(stagingDir, artifactDir);
+
   const checksums = await generateChecksums(stagingDir);
   const checksumContent = formatChecksums(checksums);
   await fs.writeFile(path.join(artifactDir, 'checksums.txt'), checksumContent);

package/src/commands/doctor.js

@@ -18,6 +18,7 @@ import {
   buildDeployPathWriteTestCommand,
   formatDeployPathWriteFailure,
 } from '../utils/shell-quote.js';
+import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -82,6 +83,16 @@ function resolveSshDeployPaths(config, envConfig) {
   return [...new Set(paths.filter(Boolean))];
 }
 
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @returns {boolean}
+ */
+function needsNginxActivationForDeploy(config) {
+  if (config.projectType === 'backend') return false;
+  if (config.projectType === 'frontend' && config.framework === 'nextjs') return false;
+  return true;
+}
+
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {string} envName
@@ -207,6 +218,149 @@ async function runDeploymentChecks(config, envName, envConfig) {
       );
     }
 
+    if (needsNginxActivationForDeploy(config)) {
+      checks.push(
+        await runCheck('Nginx installed', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required to check Nginx on the server.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required to check Nginx on the server.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Nginx installed',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('command -v nginx >/dev/null 2>&1 && echo yes');
+          if (result.pass && result.message.includes('yes')) {
+            return { name: 'Nginx installed', pass: true, message: 'Nginx installed on server' };
+          }
+          return {
+            name: 'Nginx installed',
+            pass: false,
+            message:
+              'Nginx not found on server — install it first (e.g. sudo yum install nginx on Amazon Linux, or sudo apt install nginx on Ubuntu).',
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Passwordless sudo', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required for sudo check.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required for sudo check.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Passwordless sudo',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('sudo -n true');
+          if (result.pass) {
+            return {
+              name: 'Passwordless sudo',
+              pass: true,
+              message: 'Non-interactive sudo available (required for Nginx config activation)',
+            };
+          }
+          return {
+            name: 'Passwordless sudo',
+            pass: false,
+            message: formatPasswordlessSudoGuidance(sshUser),
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Nginx sudo access', async () => {
+          if (!host || !user) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'SSH_HOST and SSH_USER are required for Nginx sudo check.',
+            };
+          }
+          if (!keyPath && !process.env.SSH_KEY) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'SSH_KEY_PATH or SSH_KEY is required for Nginx sudo check.',
+            };
+          }
+
+          const provider = getDeploymentProvider(deployType, config, envName);
+          if (!provider.runRemoteCheck) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Deploy provider does not support remote checks.',
+            };
+          }
+
+          const nginxInstalled = await provider.runRemoteCheck('command -v nginx >/dev/null 2>&1 && echo yes');
+          if (!nginxInstalled.pass || !nginxInstalled.message.includes('yes')) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Skipped — install Nginx first.',
+            };
+          }
+
+          const sudoOk = await provider.runRemoteCheck('sudo -n true');
+          if (!sudoOk.pass) {
+            return {
+              name: 'Nginx sudo access',
+              pass: false,
+              message: 'Skipped — configure passwordless sudo first.',
+            };
+          }
+
+          const result = await provider.runRemoteCheck('sudo -n nginx -t 2>&1');
+          if (result.pass) {
+            return {
+              name: 'Nginx sudo access',
+              pass: true,
+              message: 'sudo nginx -t OK (can test config before reload)',
+            };
+          }
+          return {
+            name: 'Nginx sudo access',
+            pass: false,
+            message: `sudo nginx -t failed — ${result.message}. Check Nginx install and sudoers (see README one-time server setup).`,
+          };
+        })
+      );
+    }
+
     const isBackend = config.projectType === 'backend' || config.projectType === 'both';
     if (isBackend) {
       const backendChecks = await runBackendProcessChecks(config, envName, deployType);

package/src/commands/init.js

@@ -20,6 +20,10 @@ import {
 } from '../utils/github-actions.js';
 import { printAuthorFooter } from '../utils/author.js';
 import { generateNginxConfig } from '../utils/nginx.js';
+import {
+  ensureDockerfile,
+  ensureKubernetesManifests,
+} from '../utils/scaffold.js';
 import {
   promptServerDeployment,
   buildServerEnvEntry,
@@ -190,6 +194,21 @@ async function generateProjectScaffold(config, environments, cwd) {
     await fs.writeFile(path.join(cwd, 'nginx.conf'), nginxConf);
     console.log(chalk.gray('  • nginx.conf (auto-generated)'));
   }
+
+  const dockerResult = await ensureDockerfile(cwd, config);
+  if (dockerResult.generated) {
+    console.log(chalk.gray('  • Dockerfile (auto-generated)'));
+  }
+
+  const k8sResult = await ensureKubernetesManifests(cwd, config, environments);
+  if (k8sResult.generated) {
+    console.log(chalk.gray('  • k8s/deployment.yaml, k8s/service.yaml (auto-generated)'));
+  }
+
+  return {
+    dockerfileGenerated: dockerResult.generated,
+    kubernetesGenerated: k8sResult.generated,
+  };
 }
 
 /**
@@ -397,7 +416,7 @@ export function registerInitCommand(program) {
       }
 
       const version = await getProjectVersion(cwd);
-      const hasDocker =
+      let hasDocker =
         (detectedFrontend?.hasDocker || detectedBackend?.hasDocker) ?? false;
 
       /** @type {Record<string, unknown>} */
@@ -458,7 +477,14 @@ export function registerInitCommand(program) {
         config
       );
 
-      await generateProjectScaffold(config, environments, cwd);
+      const scaffoldResult = await generateProjectScaffold(config, environments, cwd);
+
+      if (scaffoldResult?.dockerfileGenerated) {
+        hasDocker = true;
+        config.docker = true;
+        config.pipeline.docker = true;
+        await saveConfig(config, cwd);
+      }
 
       const envExampleDest = path.join(cwd, '.env.example');
       const envExampleContent = generateEnvExampleContent(

package/src/core/stages.js

@@ -6,6 +6,7 @@ import { deployToAll } from '../deployment/index.js';
 import { sendNotifications } from '../notifications/index.js';
 import axios from 'axios';
 import { getProjectVersion } from '../utils/version.js';
+import { ensureDeployScaffold } from '../utils/scaffold.js';
 
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
@@ -40,6 +41,18 @@ export function buildPipelineStages(config, cwd, state) {
             ctx.config.port = detected.port;
           }
         }
+        const scaffold = await ensureDeployScaffold(
+          ctx.cwd,
+          ctx.config,
+          ctx.config.environments || {},
+          { silent: false }
+        );
+        if (scaffold.dockerfile) {
+          ctx.config.docker = true;
+          if (ctx.config.pipeline) {
+            ctx.config.pipeline.docker = true;
+          }
+        }
         ctx.state.framework = ctx.config.framework;
         ctx.state.projectType = ctx.config.projectType || 'frontend';
       },

package/src/deployment/deployment-env.js

@@ -323,6 +323,15 @@ export const DEPLOYMENT_ENV_DEFS = {
       example: 'ghcr.io/myorg/myapp',
       when: 'optional',
     },
+    {
+      key: 'DOCKER_IMAGE_TAG',
+      optionalReason: 'defaults to your project version, then "latest" if unset',
+      comment: [
+        'Image tag written into generated manifests and used at deploy time.',
+      ],
+      example: 'latest',
+      when: 'optional',
+    },
     {
       key: 'KUBE_IMAGE_PULL_SECRET',
       optionalReason: 'only required when pulling from a private container registry',

package/src/deployment/providers/kubernetes.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
+import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -15,6 +16,7 @@ export function createKubernetesProvider(config, envName, env = process.env) {
   const kubeconfig = env.KUBECONFIG || path.join(os.homedir(), '.kube', 'config');
   const context = env.KUBE_CONTEXT || '';
   const namespace = env.KUBE_NAMESPACE || config.project || 'default';
+  const deploymentName = sanitizeK8sName(config.project || 'app');
 
   function getKubectlEnv() {
     const expanded = kubeconfig.replace(/^~/, os.homedir());
@@ -66,8 +68,8 @@ export function createKubernetesProvider(config, envName, env = process.env) {
         kubectlArgs([
           'set',
           'image',
-          `deployment/${config.project}`,
-          `${config.project}=${imageName}:${imageTag}`,
+          `deployment/${deploymentName}`,
+          `${deploymentName}=${imageName}:${imageTag}`,
         ]),
         { stdio: 'pipe', env: getKubectlEnv() }
       ).catch(() => {
@@ -80,7 +82,7 @@ export function createKubernetesProvider(config, envName, env = process.env) {
 
   async function rollback(artifactDir) {
     log.info('Rolling back Kubernetes deployment...');
-    await execa('kubectl', kubectlArgs(['rollout', 'undo', `deployment/${config.project}`]), {
+    await execa('kubectl', kubectlArgs(['rollout', 'undo', `deployment/${deploymentName}`]), {
       stdio: 'inherit',
       env: getKubectlEnv(),
     }).catch(async () => {
@@ -105,7 +107,7 @@ export function createKubernetesProvider(config, envName, env = process.env) {
     try {
       await execa(
         'kubectl',
-        kubectlArgs(['rollout', 'status', `deployment/${config.project}`, '--timeout=30s']),
+        kubectlArgs(['rollout', 'status', `deployment/${deploymentName}`, '--timeout=30s']),
         { stdio: 'pipe', env: getKubectlEnv() }
       );
       return true;

package/src/deployment/providers/ssh.js

@@ -3,7 +3,11 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
-import { getNginxSitePath } from '../../utils/nginx.js';
+import {
+  getNginxSitesAvailablePath,
+  getNginxSitesEnabledPath,
+  getNginxConfDPath,
+} from '../../utils/nginx.js';
 import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
 
 /** @type {Set<string>} */
@@ -240,24 +244,85 @@ export function createSshProvider(config, envName, env = process.env) {
     await exec(ssh, 'pm2 save');
   }
 
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} remotePath
+   * @param {'f'|'d'} [kind='f']
+   */
+  async function remotePathExists(ssh, remotePath, kind = 'f') {
+    const flag = kind === 'd' ? '-d' : '-f';
+    const result = await ssh.execCommand(`test ${flag} ${sh(remotePath)} && echo yes`);
+    return result.code === 0 && result.stdout.trim() === 'yes';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} command
+   */
+  async function remoteCommandExists(ssh, command) {
+    const result = await ssh.execCommand(`command -v ${sh(command)} >/dev/null 2>&1 && echo yes`);
+    return result.code === 0 && result.stdout.trim() === 'yes';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @returns {Promise<'debian'|'rhel'>}
+   */
+  async function detectNginxLayout(ssh) {
+    if (await remotePathExists(ssh, '/etc/nginx/sites-available', 'd')) {
+      return 'debian';
+    }
+    return 'rhel';
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   */
+  async function reloadNginx(ssh) {
+    await exec(ssh, 'sudo systemctl reload nginx 2>/dev/null || sudo nginx -s reload');
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} targetPath
    */
   async function setupNginx(ssh, targetPath) {
-    const sitePath = getNginxSitePath(config.project);
     const nginxConfRemote = `${targetPath}/nginx.conf`;
 
-    await exec(
-      ssh,
-      `sudo cp ${sh(nginxConfRemote)} ${sh(sitePath)} 2>/dev/null || sudo cp ${sh(`${targetPath}/nginx.conf`)} ${sh(sitePath)}`
-    );
-    await exec(
-      ssh,
-      `sudo ln -sf ${sh(sitePath)} ${sh(`/etc/nginx/sites-enabled/${path.basename(sitePath)}`)}`
+    if (!(await remoteCommandExists(ssh, 'nginx'))) {
+      throw new Error(
+        'Nginx is not installed on the server. Install it first (e.g. sudo yum install nginx on Amazon Linux, or sudo apt install nginx on Ubuntu), then re-run deploy.'
+      );
+    }
+
+    if (!(await remotePathExists(ssh, nginxConfRemote))) {
+      throw new Error(
+        `Nginx config not found at ${nginxConfRemote} — artifact may be missing nginx.conf.`
+      );
+    }
+
+    const layout = await detectNginxLayout(ssh);
+    log.info(
+      layout === 'debian'
+        ? 'Detected Nginx layout: Debian/Ubuntu (sites-available)'
+        : 'Detected Nginx layout: RHEL/Amazon Linux (conf.d)'
     );
+
+    if (layout === 'debian') {
+      const sitePath = getNginxSitesAvailablePath(config.project);
+      const enabledPath = getNginxSitesEnabledPath(config.project);
+      await exec(ssh, `sudo cp ${sh(nginxConfRemote)} ${sh(sitePath)}`);
+      await exec(ssh, `sudo ln -sf ${sh(sitePath)} ${sh(enabledPath)}`);
+      log.info(`Nginx config installed: ${sitePath}`);
+    } else {
+      const confPath = getNginxConfDPath(config.project);
+      await exec(ssh, `sudo cp ${sh(nginxConfRemote)} ${sh(confPath)}`);
+      log.info(`Nginx config installed: ${confPath}`);
+    }
+
     await exec(ssh, 'sudo nginx -t');
-    await exec(ssh, 'sudo systemctl reload nginx');
+    await reloadNginx(ssh);
+    log.success('Nginx config tested and reloaded');
   }
 
   /**