@akash-chowdhury-24/deployhub 2.0.3 → 2.0.4

package/README.md

@@ -604,9 +604,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 +647,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`:**
@@ -669,6 +701,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 +712,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 +737,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 +749,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 +771,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 +783,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

package/package.json

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

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/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');
   }
 
   /**

package/src/utils/nginx.js

@@ -1,3 +1,12 @@
+/**
+ * Sanitize a project name for use in Nginx config file paths.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function sanitizeNginxProjectName(projectName) {
+  return projectName.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
 /**
  * Generate nginx server block config for SPA frontend deployments.
  *
@@ -22,13 +31,61 @@ export function generateNginxConfig(projectName, deployPath, buildOutput = 'dist
 `;
 }
 
+/**
+ * Debian/Ubuntu: sites-available path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxSitesAvailablePath(projectName) {
+  return `/etc/nginx/sites-available/${sanitizeNginxProjectName(projectName)}`;
+}
+
+/**
+ * Debian/Ubuntu: sites-enabled symlink path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxSitesEnabledPath(projectName) {
+  return `/etc/nginx/sites-enabled/${sanitizeNginxProjectName(projectName)}`;
+}
+
+/**
+ * RHEL/Amazon Linux: conf.d drop-in path for this project.
+ * @param {string} projectName
+ * @returns {string}
+ */
+export function getNginxConfDPath(projectName) {
+  return `/etc/nginx/conf.d/${sanitizeNginxProjectName(projectName)}.conf`;
+}
+
 /**
  * @param {string} projectName
  * @returns {string}
  */
 export function getNginxSitePath(projectName) {
-  const safeName = projectName.replace(/[^a-zA-Z0-9_-]/g, '-');
-  return `/etc/nginx/sites-available/${safeName}`;
+  return getNginxSitesAvailablePath(projectName);
+}
+
+/**
+ * @param {string} sshUser
+ * @returns {string}
+ */
+export function formatPasswordlessSudoGuidance(sshUser) {
+  return (
+    `Passwordless sudo required to activate Nginx config during deploy.\n` +
+    `  On your server, run sudo visudo and add a line like:\n` +
+    `    ${sshUser} ALL=(ALL) NOPASSWD: /usr/sbin/nginx, /bin/cp, /usr/bin/cp, /bin/systemctl, /usr/bin/systemctl\n` +
+    `  (replace ${sshUser} with your SSH_USER)\n` +
+    `  Security: this grants broad cp/systemctl access — see README one-time server setup for a production-hardening note.`
+  );
 }
 
-export default { generateNginxConfig, getNginxSitePath };
+export default {
+  generateNginxConfig,
+  sanitizeNginxProjectName,
+  getNginxSitesAvailablePath,
+  getNginxSitesEnabledPath,
+  getNginxConfDPath,
+  getNginxSitePath,
+  formatPasswordlessSudoGuidance,
+};