@akash-chowdhury-24/deployhub 2.0.31 → 2.0.33

package/src/deployment/deployment-env.js

@@ -3,6 +3,9 @@
  * and post-init next steps.
  */
 
+import { getEnvSettings } from '../core/environments.js';
+import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
+
 /** @typedef {{ key: string, comment: string[], example?: string, default?: string, optionalReason?: string, when?: 'backend'|'optional'|'ci' }} EnvVarDef */
 
 /** @type {Record<string, EnvVarDef[]>} */
@@ -131,10 +134,12 @@ export const DEPLOYMENT_ENV_DEFS = {
     },
     {
       key: 'DOCKER_HOST',
-      optionalReason: 'only required when deploying to a remote Docker daemon instead of local Docker',
+      optionalReason:
+        'only for advanced raw Docker CLI transport (tcp:// or custom ssh://). Prefer remote.mode "ssh" (SSH_HOST / SSH_USER / SSH_KEY_PATH) for a remote Linux box',
       comment: [
-        'Remote Docker daemon address.',
-        'Examples: ssh://ubuntu@203.0.113.10 | tcp://203.0.113.10:2376',
+        'Advanced/escape-hatch: raw Docker daemon URI. DeployHub cannot validate ssh:// via doctor.',
+        'Prefer "Remote Linux server via SSH" at init (remote.mode: ssh) unless you manage TLS/ssh:// yourself.',
+        'Examples: tcp://203.0.113.10:2376 | ssh://ubuntu@203.0.113.10',
       ],
       when: 'optional',
     },
@@ -394,6 +399,56 @@ export const DEPLOYMENT_ENV_KEYS = Object.fromEntries(
   ])
 );
 
+const DOCKER_HOST_KEYS = new Set(['DOCKER_HOST', 'DOCKER_TLS_VERIFY', 'DOCKER_CERT_PATH']);
+
+/**
+ * SSH identity vars used when docker `remote.mode === "ssh"`.
+ * Same names as ec2; per-env secret prefixing separates a sibling ssh/ec2 env.
+ * Not listed in static DEPLOYMENT_ENV_KEYS.docker (local/raw docker do not read them).
+ */
+export const DOCKER_SSH_ENV_VARS = [
+  ...SSH_BASE_ENV_VARS.filter((d) => d.key !== 'SSH_DEPLOY_PATH'),
+  ...SSH_CI_ENV_VARS,
+];
+
+/**
+ * @param {Record<string, unknown>|null|undefined} settings
+ * @returns {boolean}
+ */
+function dockerHasExplicitRemoteMode(settings) {
+  const remote = settings && /** @type {Record<string, unknown>} */ (settings).remote;
+  const mode =
+    remote && typeof remote === 'object'
+      ? /** @type {Record<string, unknown>} */ (remote).mode
+      : undefined;
+  return mode === 'ssh' || mode === 'local' || mode === 'raw';
+}
+
+/**
+ * Per-env docker defs: ssh mode adds SSH_* and drops raw DOCKER_HOST;
+ * explicit local drops DOCKER_HOST; configs with no remote.mode keep legacy defs.
+ *
+ * @param {string} deployType
+ * @param {Record<string, unknown>|null} [settings]
+ * @returns {EnvVarDef[]}
+ */
+export function getMethodEnvDefs(deployType, settings = null) {
+  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+  if (deployType !== 'docker') return defs;
+  const s = settings || {};
+  if (!dockerHasExplicitRemoteMode(s)) {
+    return defs;
+  }
+  const mode = resolveDockerRemoteMode(s, {});
+  if (mode === 'ssh') {
+    return [...defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key)), ...DOCKER_SSH_ENV_VARS];
+  }
+  if (mode === 'local') {
+    return defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key));
+  }
+  return defs;
+}
+
 /**
  * Deployment-side cloud-API lookup credentials — distinct from storage-provider
  * env vars (storage stays project-wide / unprefixed).
@@ -422,8 +477,8 @@ export const DEPLOYMENT_LOOKUP_ENV_KEYS = new Set([
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string[]}
  */
-export function getDeploymentEnvKeys(deployType, config = null) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+export function getDeploymentEnvKeys(deployType, config = null, settings = null) {
+  const defs = getMethodEnvDefs(deployType, settings);
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
 
@@ -452,8 +507,8 @@ function toGithubSecretKey(key) {
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string[]}
  */
-export function getDeploymentSecretKeys(deployType, config = null) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+export function getDeploymentSecretKeys(deployType, config = null, settings = null) {
+  const defs = getMethodEnvDefs(deployType, settings);
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
 
@@ -477,8 +532,8 @@ export function getDeploymentSecretKeys(deployType, config = null) {
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string[]}
  */
-export function getDeploymentWorkflowSecretKeys(deployType, config = null) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+export function getDeploymentWorkflowSecretKeys(deployType, config = null, settings = null) {
+  const defs = getMethodEnvDefs(deployType, settings);
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
 
@@ -503,8 +558,8 @@ export function getDeploymentWorkflowSecretKeys(deployType, config = null) {
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {SecretChecklistItem[]}
  */
-export function getDeploymentSecretChecklistItems(deployType, config = null) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+export function getDeploymentSecretChecklistItems(deployType, config = null, settings = null) {
+  const defs = getMethodEnvDefs(deployType, settings);
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
 
@@ -651,7 +706,11 @@ export function applyEnvSecretOverlay(envName, config, env = process.env) {
     null;
   if (!method) return out;
 
-  const keys = getDeploymentWorkflowSecretKeys(method, /** @type {any} */ (config));
+  const keys = getDeploymentWorkflowSecretKeys(
+    method,
+    /** @type {any} */ (config),
+    getEnvSettings(entry)
+  );
   for (const key of keys) {
     const prefixed = prefixSecretKey(envName, key);
     if (out[prefixed]) {
@@ -680,10 +739,12 @@ export function getDeploymentWorkflowSecretKeysForEnv(
   config = null,
   environments = null
 ) {
-  const keys = getDeploymentWorkflowSecretKeys(deployType, config);
+  const envs = environments || config?.environments || {};
+  const settings = getEnvSettings(envs[envName]);
+  const keys = getDeploymentWorkflowSecretKeys(deployType, config, settings);
   const cfg = {
     ...(config || {}),
-    environments: environments || config?.environments || {},
+    environments: envs,
   };
   if (!envUsesPrefixedSecrets(envName, cfg)) {
     return keys;
@@ -705,7 +766,9 @@ export function getDeploymentSecretChecklistItemsForEnv(
   config = null,
   environments = null
 ) {
-  const items = getDeploymentSecretChecklistItems(deployType, config);
+  const envs = environments || config?.environments || {};
+  const settings = getEnvSettings(envs[envName]);
+  const items = getDeploymentSecretChecklistItems(deployType, config, settings);
   const cfg = {
     ...(config || {}),
     environments: environments || config?.environments || {},
@@ -736,10 +799,12 @@ export function getDeploymentSecretKeysForEnv(
   config = null,
   environments = null
 ) {
-  const keys = getDeploymentSecretKeys(deployType, config);
+  const envs = environments || config?.environments || {};
+  const settings = getEnvSettings(envs[envName]);
+  const keys = getDeploymentSecretKeys(deployType, config, settings);
   const cfg = {
     ...(config || {}),
-    environments: environments || config?.environments || {},
+    environments: envs,
   };
   if (!envUsesPrefixedSecrets(envName, cfg)) {
     return keys;
@@ -786,7 +851,6 @@ export function generateDeploymentEnvSection(
   environments = {},
   options = {}
 ) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
   const projectType = config?.projectType || 'frontend';
   const isBackend = projectType === 'backend' || projectType === 'both';
   const envName = options.envName;
@@ -819,7 +883,7 @@ export function generateDeploymentEnvSection(
       ? /** @type {Record<string, unknown>} */ (envEntry.config)
       : envEntry;
 
-  for (const d of defs) {
+  for (const d of getMethodEnvDefs(deployType, settings)) {
     if (d.when === 'backend' && !isBackend) continue;
 
     const isOptional = d.when === 'optional' || d.when === 'ci';
@@ -907,23 +971,25 @@ export const DEPLOYMENT_GUIDE = {
   },
   docker: {
     before: [
-      'Docker installed locally (docker --version works).',
-      'If deploying to a remote host: Docker installed on that host and reachable.',
+      'Docker installed locally (docker --version works) — used to build/push images.',
+      'For remote Linux via SSH: Docker installed on that host and the SSH user in the docker group.',
       'A Dockerfile or docker-compose.yml in your project (or enable pipeline.docker).',
       'Registry account if pushing to a private registry (Docker Hub, GHCR, etc.).',
     ],
     automates: [
       'Generates config, workflow, and .env.example for registry and image settings.',
       'Generates a starter Dockerfile and .dockerignore when missing.',
-      'Tests Docker daemon connectivity during init.',
+      'Offers local Docker, first-class remote SSH (node-ssh), or advanced raw DOCKER_HOST.',
+      'Validates SSH key and host when remote.mode is ssh; tests the local daemon otherwise.',
       'Builds the image once during the pipeline docker stage, then reuses it on deploy.',
     ],
     after: [
       'Copy .env.example to .env and set DOCKER_IMAGE_NAME (required — e.g. myuser/myapp).',
-      'Optional in .env: DOCKER_IMAGE_TAG, DOCKER_REGISTRY_URL, DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.',
+      'Remote Linux via SSH: also set SSH_HOST, SSH_USER, SSH_KEY_PATH (same names as EC2).',
+      'Advanced raw URI only: DOCKER_HOST, and DOCKER_TLS_VERIFY / DOCKER_CERT_PATH for tcp:// TLS.',
       'If using a private registry: also set DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN.',
       'Add the GitHub Secrets listed below (Settings → Secrets and variables → Actions). Local .env is NOT used by GitHub Actions — doctor only checks your machine.',
-      'Run deployhub doctor to verify Docker is reachable.',
+      'Run deployhub doctor to verify Docker (and SSH, when remote.mode is ssh).',
       'git push origin main to trigger your first deployment.',
     ],
   },

package/src/deployment/init-prompts.js

@@ -58,13 +58,15 @@ export function backendProcessNamePromptMessage(framework, projectName, projectT
  * @param {'frontend'|'backend'|'both'} projectType
  * @param {Record<string, unknown>|null} backendConfig
  * @param {{
- *   envName?: string,
- *   existingEnvNames?: string[],
- *   deployType?: string,
- *   nonInteractive?: boolean,
- * }} [options]
- *   — when envName is set, skip the name prompt; existingEnvNames blocks in-session / config duplicates
- *   — deployType skips the method list; nonInteractive uses defaults (requires deployType)
+   *   envName?: string,
+   *   existingEnvNames?: string[],
+   *   deployType?: string,
+   *   nonInteractive?: boolean,
+   *   portDefault?: number,
+   * }} [options]
+   *   — when envName is set, skip the name prompt; existingEnvNames blocks in-session / config duplicates
+   *   — deployType skips the method list; nonInteractive uses defaults (requires deployType)
+   *   — portDefault seeds the docker "Default port" prompt (init / env add)
  */
 export async function promptServerDeployment(
   projectName,
@@ -133,7 +135,10 @@ export async function promptServerDeployment(
   }
 
   if (deployType === 'docker') {
-    return promptDockerDeployment(base, projectName, projectType);
+    return promptDockerDeployment(base, projectName, projectType, {
+      backendConfig,
+      portDefault: options.portDefault,
+    });
   }
 
   return promptSshBasedDeployment(base, projectName, projectType, backendConfig, deployType);
@@ -161,6 +166,7 @@ function buildNonInteractiveDeployAnswers(
       dockerRegistryUsername: '',
       dockerRegistryToken: '',
       dockerHost: '',
+      remoteMode: 'local',
       healthUrl: '',
     };
   }
@@ -305,9 +311,13 @@ async function promptKubernetesDeployment(base, projectName, projectType, option
  * @param {Record<string, string>} base
  * @param {string} projectName
  * @param {'frontend'|'backend'|'both'} projectType
+ * @param {{
+ *   backendConfig?: Record<string, unknown>|null,
+ *   portDefault?: number,
+ * }} [options]
  */
-async function promptDockerDeployment(base, projectName, projectType) {
-  const dockerAnswers = await inquirer.prompt([
+async function promptDockerDeployment(base, projectName, projectType, options = {}) {
+  const imageAnswers = await inquirer.prompt([
     {
       type: 'input',
       name: 'dockerImageName',
@@ -329,10 +339,98 @@ async function promptDockerDeployment(base, projectName, projectType) {
       name: 'dockerRegistryToken',
       message: 'Registry token/password (only if using a private registry):',
     },
+  ]);
+
+  const { remoteMode } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'dockerHost',
-      message: 'Remote Docker host (optional, e.g. ssh://ubuntu@203.0.113.10):',
+      type: 'list',
+      name: 'remoteMode',
+      message: 'Where should the container run?',
+      choices: [
+        { name: 'Locally (this machine or CI runner)', value: 'local' },
+        {
+          name: 'Remote Linux server via SSH (recommended for production)',
+          value: 'ssh',
+        },
+        {
+          name: 'Advanced: raw Docker host URI (tcp://, custom SSH setup)',
+          value: 'raw',
+        },
+      ],
+      default: 'local',
+    },
+  ]);
+
+  /** @type {Record<string, string>} */
+  let sshAnswers = {};
+  /** @type {Record<string, string>} */
+  let rawAnswers = {};
+
+  if (remoteMode === 'ssh') {
+    sshAnswers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'host',
+        message: 'Remote server host/IP:',
+      },
+      {
+        type: 'input',
+        name: 'user',
+        message: 'SSH username:',
+      },
+      {
+        type: 'input',
+        name: 'keyPath',
+        message: 'Path to SSH private key:',
+      },
+    ]);
+
+    await runSshInitValidation({
+      host: sshAnswers.host,
+      user: sshAnswers.user,
+      keyPath: sshAnswers.keyPath,
+      sshPort: 22,
+      deployType: getDeployTypeLabel('docker'),
+    });
+  }
+
+  if (remoteMode === 'raw') {
+    console.log(
+      chalk.gray(
+        '\n  Note: this mode uses Docker\'s native ssh://tcp:// transport and\n' +
+          '  depends on your local machine\'s own SSH/TLS configuration —\n' +
+          '  DeployHub cannot validate this connection ahead of time. Prefer\n' +
+          '  "Remote Linux server via SSH" above unless you have a specific\n' +
+          '  reason to use this.\n'
+      )
+    );
+    rawAnswers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'dockerHost',
+        message: 'Remote Docker host (optional, e.g. ssh://ubuntu@203.0.113.10):',
+      },
+    ]);
+  }
+
+  const portDefaultRaw = options.portDefault ?? options.backendConfig?.port;
+  const portDefault = Number.isInteger(Number(portDefaultRaw))
+    ? Number(portDefaultRaw)
+    : 3000;
+
+  const { port, healthUrl } = await inquirer.prompt([
+    {
+      type: 'number',
+      name: 'port',
+      message: 'Default port:',
+      default: portDefault,
+      validate: (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1 || n > 65535) {
+          return 'Enter a port number between 1 and 65535.';
+        }
+        return true;
+      },
     },
     {
       type: 'input',
@@ -341,7 +439,15 @@ async function promptDockerDeployment(base, projectName, projectType) {
     },
   ]);
 
-  return { ...base, ...dockerAnswers };
+  return {
+    ...base,
+    ...imageAnswers,
+    remoteMode,
+    ...sshAnswers,
+    dockerHost: rawAnswers.dockerHost || '',
+    port,
+    healthUrl,
+  };
 }
 
 /**
@@ -563,7 +669,26 @@ export function buildServerEnvEntry(
   if (deployAnswers.deployType === 'docker') {
     settings.dockerImageName = deployAnswers.dockerImageName || projectName;
     settings.dockerRegistryUrl = deployAnswers.dockerRegistryUrl || '';
-    settings.dockerHost = deployAnswers.dockerHost || '';
+    const remoteMode =
+      deployAnswers.remoteMode || (deployAnswers.dockerHost ? 'raw' : 'local');
+    settings.remote = { mode: remoteMode };
+    // Raw URI stays in config (existing DOCKER_HOST overlay). SSH key path is
+    // env-only. Host/user are non-secret settings (same as ec2) so doctor and
+    // .env.example can resolve them without writing the private key path here.
+    settings.dockerHost = remoteMode === 'raw' ? deployAnswers.dockerHost || '' : '';
+    if (remoteMode === 'ssh') {
+      if (deployAnswers.host) settings.host = deployAnswers.host;
+      if (deployAnswers.user) settings.user = deployAnswers.user;
+    }
+    // Per-env port (same key resolveDockerPublishPort reads). Prefer the
+    // docker "Default port" answer; fall back to init's project-level port.
+    // Do not invent || 3000 — missing port must stay missing so SSH deploy
+    // fails loudly instead of publishing a sibling environment's port.
+    const rawPort = deployAnswers.port ?? singleConfig?.port;
+    const n = Number(rawPort);
+    if (Number.isInteger(n) && n >= 1 && n <= 65535) {
+      settings.port = n;
+    }
     return {
       enabled: true,
       method: 'docker',
@@ -680,6 +805,12 @@ export function getDockerEnvSecrets(deployAnswers) {
   if (deployAnswers.dockerRegistryToken) {
     vars.DOCKER_REGISTRY_TOKEN = deployAnswers.dockerRegistryToken;
   }
+  if (deployAnswers.deployType === 'docker' && deployAnswers.remoteMode === 'ssh') {
+    if (deployAnswers.keyPath) vars.SSH_KEY_PATH = deployAnswers.keyPath;
+  }
+  if (deployAnswers.deployType === 'docker' && deployAnswers.remoteMode === 'raw') {
+    if (deployAnswers.dockerHost) vars.DOCKER_HOST = deployAnswers.dockerHost;
+  }
   return Object.keys(vars).length > 0 ? vars : null;
 }