@akash-chowdhury-24/deployhub 2.0.31 → 2.0.32

package/README.md

@@ -855,7 +855,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 1. Set `DOCKER_IMAGE_NAME` in `.env` (e.g. `myuser/myapp` for Docker Hub)
 2. For private registries (or any push): set `DOCKER_REGISTRY_USERNAME` and `DOCKER_REGISTRY_TOKEN`
 3. Leave `DOCKER_IMAGE_TAG` unset for a unique tag each build — set it only if you intentionally want a fixed tag
-4. For remote Docker: set `DOCKER_HOST` (e.g. `ssh://ubuntu@203.0.113.10`)
+4. For a remote Linux host, choose **Remote Linux server via SSH** at init (`remote.mode: "ssh"`) and set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` — DeployHub runs `docker pull`/`run` over node-ssh. Use `DOCKER_HOST` only for the advanced raw CLI transport (`tcp://` or a custom `ssh://` setup you already manage)
 5. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
@@ -865,7 +865,8 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `DOCKER_REGISTRY_URL` | Registry URL (optional) | `https://ghcr.io` | Registry docs |
 | `DOCKER_REGISTRY_USERNAME` | Registry user | `myuser` | Registry account |
 | `DOCKER_REGISTRY_TOKEN` | Registry password/token | *(secret)* | Docker Hub / GHCR PAT |
-| `DOCKER_HOST` | Remote daemon (optional) | `ssh://ubuntu@host` | Remote Docker setup |
+| `DOCKER_HOST` | Advanced raw daemon URI (optional) | `tcp://host:2376` | Only if you manage TLS/ssh:// yourself |
+| `SSH_HOST` / `SSH_USER` / `SSH_KEY_PATH` | Remote Linux via SSH (`remote.mode: ssh`) | `203.0.113.10` / `ubuntu` / `~/.ssh/key.pem` | Same names as EC2 |
 
 ### AWS EC2
 

package/package.json

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

package/src/commands/doctor.js

@@ -31,6 +31,15 @@ import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
 import { checkImagePullability } from '../utils/docker-image-deploy.js';
 import { namespaceExists } from '../utils/kubernetes-namespace.js';
 import { resolvePhpVersion } from '../utils/php-version.js';
+import {
+  resolveDockerSshTarget,
+  probeRemoteDockerPs,
+  formatRemoteDockerSshFailure,
+  formatRemoteDockerNotInstalled,
+  formatRemoteDockerPermissionDenied,
+  formatRemoteDockerDaemonOk,
+} from '../utils/docker-remote.js';
+import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
 import {
   buildPhpFpmUnitListCommand,
   formatPhpFpmMissingError,
@@ -183,14 +192,16 @@ export async function runDeploymentChecks(config, envName, envConfig) {
 
   /** @type {CheckResult[]} */
   const checks = [];
-  const requiredKeys = getDeploymentEnvKeys(deployType, config);
+  const requiredKeys = getDeploymentEnvKeys(deployType, config, settings);
 
   checks.push(
     await runCheck(`${deployType} env vars`, async () => {
       const missing = requiredKeys.filter((k) => {
         if (k === 'SSH_KEY_PATH') {
-          return !process.env.SSH_KEY_PATH && !process.env.SSH_KEY;
+          return !process.env.SSH_KEY_PATH && !process.env.SSH_KEY && !settings.keyPath;
         }
+        if (k === 'SSH_HOST') return !(settings.host || process.env.SSH_HOST);
+        if (k === 'SSH_USER') return !(settings.user || process.env.SSH_USER);
         return !process.env[k];
       });
       if (missing.length > 0) {
@@ -447,22 +458,139 @@ export async function runDeploymentChecks(config, envName, envConfig) {
   }
 
   if (deployType === 'docker') {
-    checks.push(
-      await runCheck('Docker daemon', async () => {
-        try {
-          const provider = getDeploymentProvider('docker', config, envName);
-          await provider.testConnection();
-          return { name: 'Docker daemon', pass: true, message: 'Docker daemon reachable' };
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
+    const dockerRemoteMode = resolveDockerRemoteMode(settings, process.env);
+
+    if (dockerRemoteMode === 'ssh') {
+      const target = resolveDockerSshTarget(settings, process.env);
+      const host = target.host;
+      const user = target.user;
+      const keyPath = target.keyPath;
+      const sshPort = target.sshPort;
+
+      checks.push(
+        await runCheck('SSH key', async () => {
+          const result = await validateSshKeyForDoctor(
+            keyPath ? String(keyPath) : undefined,
+            process.env.SSH_KEY
+          );
+          return {
+            name: 'SSH key',
+            pass: result.ok,
+            message: result.message,
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('SSH host reachability', async () => {
+          if (!host) {
+            return {
+              name: 'SSH host reachability',
+              pass: false,
+              message: 'SSH_HOST is required — set it in .env to your server IP or hostname.',
+            };
+          }
+          const result = await testSshHostReachability(String(host), sshPort);
+          return {
+            name: 'SSH host reachability',
+            pass: result.ok,
+            message: result.message,
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Remote Docker daemon reachable', async () => {
+          const probe = await probeRemoteDockerPs(target);
+          if (!probe.sshOk) {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: false,
+              message: formatRemoteDockerSshFailure(host, user),
+            };
+          }
+          if (probe.kind === 'not-installed') {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: false,
+              message: formatRemoteDockerNotInstalled(host, user),
+            };
+          }
+          if (probe.kind === 'ok' || probe.kind === 'permission') {
+            return {
+              name: 'Remote Docker daemon reachable',
+              pass: true,
+              message: formatRemoteDockerDaemonOk(host, user),
+            };
+          }
+          return {
+            name: 'Remote Docker daemon reachable',
+            pass: false,
+            message:
+              probe.detail ||
+              `Remote Docker daemon is not reachable (${user}@${host}).`,
+          };
+        })
+      );
+
+      checks.push(
+        await runCheck('Remote Docker permission', async () => {
+          const probe = await probeRemoteDockerPs(target);
+          if (!probe.sshOk) {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerSshFailure(host, user),
+            };
+          }
+          if (probe.kind === 'permission') {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerPermissionDenied(host, user),
+            };
+          }
+          if (probe.kind === 'ok') {
+            return {
+              name: 'Remote Docker permission',
+              pass: true,
+              message: `SSH user '${user}' can access the Docker daemon on ${host}`,
+            };
+          }
+          if (probe.kind === 'not-installed') {
+            return {
+              name: 'Remote Docker permission',
+              pass: false,
+              message: formatRemoteDockerNotInstalled(host, user),
+            };
+          }
           return {
-            name: 'Docker daemon',
+            name: 'Remote Docker permission',
             pass: false,
-            message: `Docker not reachable — ${msg}. Install Docker or set DOCKER_HOST for a remote daemon.`,
+            message:
+              probe.detail ||
+              `Cannot verify Docker permissions for '${user}' on ${host}.`,
           };
-        }
-      })
-    );
+        })
+      );
+    } else {
+      checks.push(
+        await runCheck('Docker daemon', async () => {
+          try {
+            const provider = getDeploymentProvider('docker', config, envName);
+            await provider.testConnection();
+            return { name: 'Docker daemon', pass: true, message: 'Docker daemon reachable' };
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+              name: 'Docker daemon',
+              pass: false,
+              message: `Docker not reachable — ${msg}. Install Docker or set DOCKER_HOST for a remote daemon.`,
+            };
+          }
+        })
+      );
+    }
   }
 
   if (deployType === 'kubernetes') {
@@ -1142,7 +1270,9 @@ export function registerDoctorCommand(program) {
             const method = getEnvMethod(env);
             if (!method) continue;
             // Local/.env uses unprefixed names; prefixed CI names are checked separately below.
-            required.push(...getDeploymentSecretKeys(method, config));
+            required.push(
+              ...getDeploymentSecretKeys(method, config, getEnvSettings(env))
+            );
           }
 
           const unique = [...new Set(required)];
@@ -1179,7 +1309,7 @@ export function registerDoctorCommand(program) {
             config,
             config.environments
           );
-          const baseKeys = getDeploymentSecretKeys(method, config);
+          const baseKeys = getDeploymentSecretKeys(method, config, getEnvSettings(env));
 
           for (let i = 0; i < baseKeys.length; i++) {
             const base = baseKeys[i];

package/src/core/config.js

@@ -54,6 +54,16 @@ const MethodConfigSchema = z
     dockerImageName: z.string().optional(),
     dockerRegistryUrl: z.string().optional(),
     dockerHost: z.string().optional(),
+    /**
+     * Docker-method only. Kubernetes must ignore this — it deploys via kubectl,
+     * never a remote Docker daemon. `ssh` = node-ssh + remote docker CLI;
+     * `local` = this machine; `raw` = unmanaged DOCKER_HOST (ssh:// or tcp://).
+     */
+    remote: z
+      .object({
+        mode: z.enum(['ssh', 'local', 'raw']),
+      })
+      .optional(),
     healthCheckUrl: z.string().optional(),
     appName: z.string().optional(),
     framework: z.string().optional(),

package/src/core/environments.js

@@ -266,6 +266,22 @@ export function resolveEnvTargets(config, envFlag) {
   return { targets: [envFlag], skippedDisabled: [] };
 }
 
+/**
+ * Whitelist of method-config fields copied onto process env for Docker and
+ * Kubernetes providers. Structural (not a per-method if): only these keys are
+ * ever copied. `remote` / `host` / `user` / `keyPath` are intentionally absent
+ * — docker SSH identity is read by docker.js from settings + SSH_* env vars.
+ * Kubernetes uses this same helper and therefore cannot observe remote.mode.
+ */
+export const METHOD_SETTINGS_ENV_OVERLAY = Object.freeze({
+  dockerImageName: 'DOCKER_IMAGE_NAME',
+  dockerRegistryUrl: 'DOCKER_REGISTRY_URL',
+  dockerHost: 'DOCKER_HOST',
+  kubeNamespace: 'KUBE_NAMESPACE',
+  kubeconfig: 'KUBECONFIG',
+  kubeContext: 'KUBE_CONTEXT',
+});
+
 /**
  * Overlay method-specific config onto process env for Docker/K8s providers.
  * Secrets still come from real env vars; non-secret names/paths come from config.
@@ -277,12 +293,10 @@ export function resolveEnvTargets(config, envFlag) {
 export function mergeMethodSettingsIntoEnv(env, settings) {
   /** @type {Record<string, string|undefined>} */
   const out = { ...env };
-  if (settings.dockerImageName) out.DOCKER_IMAGE_NAME = String(settings.dockerImageName);
-  if (settings.dockerRegistryUrl) out.DOCKER_REGISTRY_URL = String(settings.dockerRegistryUrl);
-  if (settings.dockerHost) out.DOCKER_HOST = String(settings.dockerHost);
-  if (settings.kubeNamespace) out.KUBE_NAMESPACE = String(settings.kubeNamespace);
-  if (settings.kubeconfig) out.KUBECONFIG = String(settings.kubeconfig);
-  if (settings.kubeContext) out.KUBE_CONTEXT = String(settings.kubeContext);
+  for (const [settingKey, envKey] of Object.entries(METHOD_SETTINGS_ENV_OVERLAY)) {
+    const value = settings[settingKey];
+    if (value) out[envKey] = String(value);
+  }
   return out;
 }
 
@@ -302,4 +316,5 @@ export default {
   buildEnvironmentEntry,
   resolveEnvTargets,
   mergeMethodSettingsIntoEnv,
+  METHOD_SETTINGS_ENV_OVERLAY,
 };

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

@@ -161,6 +161,7 @@ function buildNonInteractiveDeployAnswers(
       dockerRegistryUsername: '',
       dockerRegistryToken: '',
       dockerHost: '',
+      remoteMode: 'local',
       healthUrl: '',
     };
   }
@@ -307,7 +308,7 @@ async function promptKubernetesDeployment(base, projectName, projectType, option
  * @param {'frontend'|'backend'|'both'} projectType
  */
 async function promptDockerDeployment(base, projectName, projectType) {
-  const dockerAnswers = await inquirer.prompt([
+  const imageAnswers = await inquirer.prompt([
     {
       type: 'input',
       name: 'dockerImageName',
@@ -329,11 +330,81 @@ 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 { healthUrl } = await inquirer.prompt([
     {
       type: 'input',
       name: 'healthUrl',
@@ -341,7 +412,14 @@ async function promptDockerDeployment(base, projectName, projectType) {
     },
   ]);
 
-  return { ...base, ...dockerAnswers };
+  return {
+    ...base,
+    ...imageAnswers,
+    remoteMode,
+    ...sshAnswers,
+    dockerHost: rawAnswers.dockerHost || '',
+    healthUrl,
+  };
 }
 
 /**
@@ -563,7 +641,17 @@ 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;
+    }
     return {
       enabled: true,
       method: 'docker',
@@ -680,6 +768,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;
 }