@akash-chowdhury-24/deployhub 2.0.31 → 2.0.33

package/src/deployment/providers/docker.js

@@ -4,6 +4,19 @@ import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.
 import { resolveDockerImageRefForTag } from '../../utils/docker-image.js';
 import { resolveDockerContainerName } from '../../utils/docker-container-name.js';
 import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environments.js';
+import { createSshExecSession } from '../ssh-connection.js';
+import { resolveDockerRemoteMode } from '../../utils/docker-remote-mode.js';
+import {
+  resolveDockerSshTarget,
+  buildRemoteDockerCommands,
+} from '../../utils/docker-remote.js';
+import {
+  resolveDockerPublishPort,
+  formatDockerSshPortRequired,
+  evaluateDockerPortPublish,
+  buildDockerInspectPortsArgs,
+  buildDockerInspectPortsCommand,
+} from '../../utils/docker-port-publish.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -14,10 +27,39 @@ export function createDockerProvider(config, envName, env = process.env) {
   const log = createLogger('docker');
   const settings = getEnvSettings(config.environments?.[envName]);
   const effectiveEnv = mergeMethodSettingsIntoEnv(env, settings);
-  const imageOps = createDockerImageDeployContext(config, effectiveEnv, log);
-  const { fullImage, getDockerEnv, ensureImageReadyForDeploy } = imageOps;
+  const remoteMode = resolveDockerRemoteMode(settings, effectiveEnv);
+
+  // SSH remote runs pull/run/stop/rm over node-ssh. Image build/push still uses
+  // the local Docker daemon — never inject DOCKER_HOST into the shared image
+  // helpers (kubernetes.js also uses those helpers and has no SSH docker host).
+  /** @type {Record<string, string|undefined>} */
+  const imageEnv = { ...effectiveEnv };
+  if (remoteMode === 'ssh') {
+    delete imageEnv.DOCKER_HOST;
+    delete imageEnv.DOCKER_TLS_VERIFY;
+    delete imageEnv.DOCKER_CERT_PATH;
+  }
+
+  const imageOps = createDockerImageDeployContext(config, imageEnv, log);
+  const { fullImage, getDockerEnv, ensureImageReadyForDeploy, hasRegistryCredentials } =
+    imageOps;
   // Env-scoped like PM2/Nginx — same-daemon multi-env must not share one container name.
   const containerName = resolveDockerContainerName(config, envName);
+  const publishPort = resolveDockerPublishPort(config, settings, envName);
+
+  function sshTarget() {
+    return resolveDockerSshTarget(settings, effectiveEnv);
+  }
+
+  function sshSession() {
+    const target = sshTarget();
+    return createSshExecSession({
+      ...target,
+      keyPath: target.keyPath ? String(target.keyPath) : undefined,
+      env: effectiveEnv,
+      log,
+    });
+  }
 
   /**
    * @param {string} artifactDir
@@ -26,31 +68,135 @@ export function createDockerProvider(config, envName, env = process.env) {
   async function deploy(artifactDir, options = {}) {
     const imageRef = options.fullImage || fullImage;
     log.info(`Deploying via Docker (image: ${imageRef})...`);
-    const dockerEnv = getDockerEnv();
 
     const result = await ensureImageReadyForDeploy(artifactDir, {
       fullImage: options.fullImage,
       skipImageReuse: options.skipImageReuse,
     });
     if (result.ranCompose) {
+      if (remoteMode === 'ssh') {
+        throw new Error(
+          'docker-compose.yml deploys are not supported with remote.mode "ssh". ' +
+            'Use local Docker, advanced raw DOCKER_HOST, or a single-image Dockerfile deploy.'
+        );
+      }
       log.success('Docker deployment complete');
       return;
     }
 
+    if (remoteMode === 'ssh') {
+      if (publishPort == null) {
+        throw new Error(formatDockerSshPortRequired(envName));
+      }
+      await deployOverSsh(imageRef, publishPort);
+      log.success('Docker deployment complete');
+      return;
+    }
+
+    const dockerEnv = getDockerEnv();
+
     await execa(
       'docker',
       ['rm', '-f', containerName],
       { stdio: 'pipe', env: dockerEnv }
     ).catch(() => {});
 
-    await execa('docker', ['run', '-d', '--rm', '--name', containerName, imageRef], {
+    /** @type {string[]} */
+    const runArgs = ['run', '-d', '--rm', '--name', containerName];
+    if (publishPort != null) {
+      runArgs.push('-p', `${publishPort}:${publishPort}`);
+    }
+    runArgs.push(imageRef);
+
+    await execa('docker', runArgs, {
       stdio: 'inherit',
       env: dockerEnv,
     });
 
+    if (publishPort != null) {
+      await assertLocalPortPublished(dockerEnv, publishPort);
+    }
+
     log.success('Docker deployment complete');
   }
 
+  /**
+   * @param {Record<string, string>} dockerEnv
+   * @param {number} port
+   */
+  async function assertLocalPortPublished(dockerEnv, port) {
+    try {
+      const inspected = await execa('docker', buildDockerInspectPortsArgs(containerName), {
+        stdio: 'pipe',
+        env: dockerEnv,
+      });
+      const verdict = evaluateDockerPortPublish(
+        { code: 0, stdout: inspected.stdout },
+        { containerName, port, requireRunning: false }
+      );
+      if (!verdict.pass) {
+        throw new Error(verdict.message);
+      }
+      if (verdict.reason === 'published') {
+        log.info(verdict.message);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("Container '")) {
+        throw err;
+      }
+      // One-shot images (hello-world) exit before inspect; verify/doctor catch long-running misses.
+    }
+  }
+
+  /**
+   * @param {string} imageRef
+   * @param {number} port
+   */
+  async function deployOverSsh(imageRef, port) {
+    const cmds = buildRemoteDockerCommands(imageRef, containerName, {}, { publishPort: port });
+    const session = sshSession();
+    const ssh = await session.connect();
+    try {
+      const registryUser = imageEnv.DOCKER_REGISTRY_USERNAME || '';
+      const registryToken = imageEnv.DOCKER_REGISTRY_TOKEN || '';
+      const registryUrl = imageEnv.DOCKER_REGISTRY_URL || '';
+
+      if (registryUser && registryToken) {
+        const registry = registryUrl || 'https://index.docker.io/v1/';
+        log.info('Logging in to container registry on remote host...');
+        await session.exec(ssh, cmds.login(registry, registryUser, registryToken));
+      } else if (!hasRegistryCredentials()) {
+        log.warn(
+          'No DOCKER_REGISTRY_USERNAME/TOKEN — remote docker pull requires a public image or one already present on the host.'
+        );
+      }
+
+      await session.exec(ssh, cmds.stop);
+      await session.exec(ssh, cmds.rm);
+      await session.exec(ssh, cmds.pull, {
+        timeoutMs: Math.max(session.defaultExecTimeoutMs, 300_000),
+      });
+      await session.exec(ssh, cmds.run);
+      const inspected = await session.execUnchecked(
+        ssh,
+        buildDockerInspectPortsCommand(containerName)
+      );
+      const verdict = evaluateDockerPortPublish(inspected, {
+        containerName,
+        port,
+        requireRunning: false,
+      });
+      if (!verdict.pass) {
+        throw new Error(verdict.message);
+      }
+      if (verdict.reason === 'published') {
+        log.info(verdict.message);
+      }
+    } finally {
+      ssh.dispose();
+    }
+  }
+
   /**
    * @param {string} artifactDir
    * @param {{ buildId?: string, semver?: string, remoteKey?: string }} [meta]
@@ -65,7 +211,7 @@ export function createDockerProvider(config, envName, env = process.env) {
     // Tag stays buildId-based; env only scopes which history informed this buildId.
     const rollbackImage = resolveDockerImageRefForTag(
       config,
-      effectiveEnv,
+      imageEnv,
       meta.buildId
     ).fullImage;
     log.info(
@@ -82,6 +228,18 @@ export function createDockerProvider(config, envName, env = process.env) {
     if (!url) return true;
 
     try {
+      if (remoteMode === 'ssh') {
+        const cmds = buildRemoteDockerCommands(fullImage, containerName);
+        const session = sshSession();
+        const ssh = await session.connect();
+        try {
+          const result = await session.exec(ssh, cmds.ps);
+          return String(result.stdout || '').includes('Up');
+        } finally {
+          ssh.dispose();
+        }
+      }
+
       const { stdout } = await execa(
         'docker',
         ['ps', '--filter', `name=^/${containerName}$`, '--format', '{{.Status}}'],
@@ -94,10 +252,21 @@ export function createDockerProvider(config, envName, env = process.env) {
   }
 
   async function testConnection() {
+    if (remoteMode === 'ssh') {
+      const cmds = buildRemoteDockerCommands(fullImage, containerName);
+      const session = sshSession();
+      const ssh = await session.connect();
+      try {
+        await session.exec(ssh, cmds.info);
+      } finally {
+        ssh.dispose();
+      }
+      return;
+    }
     await execa('docker', ['info'], { stdio: 'pipe', env: getDockerEnv() });
   }
 
-  return { deploy, rollback, healthCheck, testConnection };
+  return { deploy, rollback, healthCheck, testConnection, remoteMode };
 }
 
 export default { createDockerProvider };

package/src/deployment/providers/kubernetes.js

@@ -19,6 +19,9 @@ import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environme
 export function createKubernetesProvider(config, envName, env = process.env) {
   const log = createLogger('kubernetes');
   const settings = getEnvSettings(config.environments?.[envName]);
+  // Overlay is a field whitelist (METHOD_SETTINGS_ENV_OVERLAY). It never copies
+  // docker `remote.mode` / SSH host identity. Kubernetes talks to the cluster
+  // via kubectl regardless of any docker-ssh fields that might sit on settings.
   const effectiveEnv = mergeMethodSettingsIntoEnv(env, settings);
   const imageOps = createDockerImageDeployContext(config, effectiveEnv, log);
 

package/src/deployment/providers/ssh.js

@@ -1,9 +1,7 @@
-import { NodeSSH } from 'node-ssh';
-import fs from 'fs-extra';
 import path from 'path';
-import os from 'os';
 import { createLogger } from '../../logger/index.js';
 import { getEnvSettings } from '../../core/config.js';
+import { createSshExecSession } from '../ssh-connection.js';
 import {
   getNginxSitesAvailablePath,
   getNginxSitesEnabledPath,
@@ -11,7 +9,7 @@ import {
   resolveNginxSiteName,
 } from '../../utils/nginx.js';
 import { resolvePm2AppName } from '../../utils/pm2-app-name.js';
-import { shellQuote, formatRemoteCommandFailure } from '../../utils/shell-quote.js';
+import { shellQuote } from '../../utils/shell-quote.js';
 import { extractGunicornTarget } from '../../utils/python-app-target.js';
 import { resolvePhpVersion } from '../../utils/php-version.js';
 import {
@@ -64,94 +62,21 @@ export function createSshProvider(config, envName, env = process.env) {
 
   const log = createLogger('ssh');
 
-  // Defense-in-depth: never let a stuck SSH channel hang CI indefinitely.
-  // Override with DEPLOYHUB_SSH_EXEC_TIMEOUT_MS (ms). Backend start/stop uses a shorter bound.
-  const defaultExecTimeoutMs = Number(env.DEPLOYHUB_SSH_EXEC_TIMEOUT_MS) || 120_000;
+  const session = createSshExecSession({
+    host,
+    user,
+    keyPath,
+    sshKey,
+    sshPort,
+    env,
+    log,
+  });
+  const { connect, exec, defaultExecTimeoutMs } = session;
   const startStopTimeoutMs = Math.min(
     defaultExecTimeoutMs,
     Number(env.DEPLOYHUB_SSH_START_TIMEOUT_MS) || 60_000
   );
 
-  async function connect() {
-    if (!host || !user) {
-      throw new Error(
-        'SSH host and user are required. Set SSH_HOST and SSH_USER in .env (see .env.example comments).'
-      );
-    }
-
-    if (!sshKey && !keyPath) {
-      throw new Error(
-        'SSH authentication required. Set SSH_KEY_PATH (local) or SSH_KEY (CI secret) in .env — see .env.example.'
-      );
-    }
-
-    const ssh = new NodeSSH();
-    /** @type {import('node-ssh').SSHConnectOptions} */
-    const connectOpts = { host, username: user, port: sshPort };
-
-    if (sshKey) {
-      const tmpKeyPath = path.join(os.tmpdir(), 'deployhub-ssh-key');
-      await fs.writeFile(tmpKeyPath, sshKey, { mode: 0o600 });
-      connectOpts.privateKeyPath = tmpKeyPath;
-    } else if (keyPath) {
-      const expanded = keyPath.replace(/^~/, os.homedir());
-      connectOpts.privateKeyPath = path.resolve(expanded);
-    }
-
-    try {
-      await ssh.connect(connectOpts);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `SSH connection failed to ${user}@${host}:${sshPort} — ${msg}. Check SSH_HOST, SSH_USER, SSH_KEY_PATH, and that port ${sshPort} is open in your firewall/security group.`
-      );
-    }
-    return ssh;
-  }
-
-  /**
-   * @param {import('node-ssh').NodeSSH} ssh
-   * @param {string} command
-   * @param {{ timeoutMs?: number }} [opts]
-   */
-  async function exec(ssh, command, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? defaultExecTimeoutMs;
-    log.info(`$ ${command}`);
-
-    /** @type {ReturnType<typeof setTimeout> | undefined} */
-    let timer;
-    const timeoutPromise = new Promise((_, reject) => {
-      timer = setTimeout(() => {
-        reject(
-          new Error(
-            `SSH command timed out after ${timeoutMs}ms on ${user}@${host}. ` +
-              `The remote command may still be running — check the server. ` +
-              `Command: ${command.length > 240 ? `${command.slice(0, 240)}…` : command}`
-          )
-        );
-      }, timeoutMs);
-    });
-
-    let result;
-    try {
-      result = await Promise.race([ssh.execCommand(command), timeoutPromise]);
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-
-    if (result.code !== 0 && result.code !== null) {
-      const message = formatRemoteCommandFailure(
-        command,
-        result.code,
-        result.stderr,
-        result.stdout
-      );
-      log.error(message);
-      throw new Error(message);
-    }
-    return result;
-  }
-
   /**
    * Exact marker match in a null-delimited /proc file (cmdline or environ).
    * Uses grep -xF so DEPLOYHUB_APP=myapi does not match DEPLOYHUB_APP=myapi-staging.

package/src/deployment/ssh-connection.js

@@ -0,0 +1,149 @@
+import { NodeSSH } from 'node-ssh';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { formatRemoteCommandFailure } from '../utils/shell-quote.js';
+
+/**
+ * Shared node-ssh connection + exec wrapper used by ssh.js and docker
+ * `remote.mode === "ssh"`. Do not duplicate this layer in providers.
+ *
+ * @param {{
+ *   host?: string,
+ *   user?: string,
+ *   keyPath?: string,
+ *   sshKey?: string,
+ *   sshPort?: number,
+ *   env?: Record<string, string|undefined>,
+ *   log?: { info: Function, error: Function },
+ * }} opts
+ */
+export function createSshExecSession(opts) {
+  const env = opts.env || process.env;
+  const host = opts.host;
+  const user = opts.user;
+  const sshKey = opts.sshKey || env.SSH_KEY;
+  const keyPath = opts.keyPath;
+  const sshPort = Number(opts.sshPort) || 22;
+  const log = opts.log || { info() {}, error() {} };
+
+  // Defense-in-depth: never let a stuck SSH channel hang CI indefinitely.
+  // Override with DEPLOYHUB_SSH_EXEC_TIMEOUT_MS (ms).
+  const defaultExecTimeoutMs = Number(env.DEPLOYHUB_SSH_EXEC_TIMEOUT_MS) || 120_000;
+
+  async function connect() {
+    if (!host || !user) {
+      throw new Error(
+        'SSH host and user are required. Set SSH_HOST and SSH_USER in .env (see .env.example comments).'
+      );
+    }
+
+    if (!sshKey && !keyPath) {
+      throw new Error(
+        'SSH authentication required. Set SSH_KEY_PATH (local) or SSH_KEY (CI secret) in .env — see .env.example.'
+      );
+    }
+
+    const ssh = new NodeSSH();
+    /** @type {import('node-ssh').SSHConnectOptions} */
+    const connectOpts = { host, username: user, port: sshPort };
+
+    if (sshKey) {
+      const tmpKeyPath = path.join(
+        os.tmpdir(),
+        `deployhub-ssh-key-${process.pid}-${Date.now()}`
+      );
+      await fs.writeFile(tmpKeyPath, sshKey, { mode: 0o600 });
+      connectOpts.privateKeyPath = tmpKeyPath;
+    } else if (keyPath) {
+      const expanded = keyPath.replace(/^~/, os.homedir());
+      connectOpts.privateKeyPath = path.resolve(expanded);
+    }
+
+    try {
+      await ssh.connect(connectOpts);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `SSH connection failed to ${user}@${host}:${sshPort} — ${msg}. Check SSH_HOST, SSH_USER, SSH_KEY_PATH, and that port ${sshPort} is open in your firewall/security group.`
+      );
+    }
+    return ssh;
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} command
+   * @param {{ timeoutMs?: number }} [execOpts]
+   */
+  async function runCommand(ssh, command, execOpts = {}) {
+    const timeoutMs = execOpts.timeoutMs ?? defaultExecTimeoutMs;
+    log.info(`$ ${command}`);
+
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new Error(
+            `SSH command timed out after ${timeoutMs}ms on ${user}@${host}. ` +
+              `The remote command may still be running — check the server. ` +
+              `Command: ${command.length > 240 ? `${command.slice(0, 240)}…` : command}`
+          )
+        );
+      }, timeoutMs);
+    });
+
+    let result;
+    try {
+      result = await Promise.race([ssh.execCommand(command), timeoutPromise]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    return result;
+  }
+
+  /**
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} command
+   * @param {{ timeoutMs?: number }} [execOpts]
+   */
+  async function exec(ssh, command, execOpts = {}) {
+    const result = await runCommand(ssh, command, execOpts);
+    if (result.code !== 0 && result.code !== null) {
+      const message = formatRemoteCommandFailure(
+        command,
+        result.code,
+        result.stderr,
+        result.stdout
+      );
+      log.error(message);
+      throw new Error(message);
+    }
+    return result;
+  }
+
+  /**
+   * Same timeout wrapper as exec(), but does not throw on non-zero exit.
+   * Used by doctor so a failed remote probe is classified, not a crash.
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @param {string} command
+   * @param {{ timeoutMs?: number }} [execOpts]
+   */
+  async function execUnchecked(ssh, command, execOpts = {}) {
+    return runCommand(ssh, command, execOpts);
+  }
+
+  return {
+    connect,
+    exec,
+    execUnchecked,
+    host,
+    user,
+    sshPort,
+    defaultExecTimeoutMs,
+  };
+}
+
+export default { createSshExecSession };

package/src/utils/credential-inventory.js

@@ -197,6 +197,16 @@ export const SHARED_BY_DESIGN_DEPLOY_PAIRS = [
   },
 ];
 
+/**
+ * When docker `remote.mode === "ssh"`, the docker method also reads SSH_HOST,
+ * SSH_USER, SSH_KEY_PATH, SSH_SSH_PORT, and SSH_KEY at runtime — the same
+ * names as ssh/ec2/azure-vm/gcp-vm. Those keys are NOT in static
+ * DEPLOYMENT_ENV_KEYS.docker (local and raw docker do not use them), so they
+ * do not appear in the storage×deploy matrix. Per-environment secret prefixing
+ * already separates a docker-ssh env from a sibling ssh/ec2 env on the same
+ * config. Do not invent DOCKER_SSH_* aliases unless prefixing cannot apply.
+ */
+
 /**
  * @param {string[]} a
  * @param {string[]} b

package/src/utils/docker-image-deploy.js

@@ -29,6 +29,10 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
   const registryUrl = env.DOCKER_REGISTRY_URL || '';
   const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
   const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
+  // DOCKER_HOST here is only the raw CLI transport (tcp:// / ssh://).
+  // docker remote.mode "ssh" is resolved in docker.js and must not be injected
+  // into this shared helper — kubernetes.js uses the same context for build/push
+  // and has no remote SSH docker host.
   const dockerHost = env.DOCKER_HOST || '';
 
   if (tagSource === 'explicit') {