@akash-chowdhury-24/deployhub 2.0.30 → 2.0.32

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[]>} */
@@ -55,7 +58,7 @@ export const SSH_BACKEND_ENV_VARS = [
   {
     key: 'SSH_APP_NAME',
     comment: [
-      'Process name used by PM2 when restarting your Node.js backend.',
+      'Env-scoped process identity: PM2 app name (Node), DEPLOYHUB_APP / PID markers (Python, Java, Go, .NET, Rails), and related resource names. Not the php-fpm systemd unit.',
     ],
     example: 'my-api',
     when: 'backend',
@@ -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-helpers.js

@@ -143,7 +143,9 @@ export async function validateSshKeyForDoctor(keyPath, sshKey) {
   }
 
   const mode = stat.mode & 0o777;
-  if (mode !== 0o400 && mode !== 0o600) {
+  // Windows NTFS does not carry Unix 400/600; OpenSSH uses ACLs instead.
+  // A 666 stat here is not "world-readable" the way it is on Linux.
+  if (process.platform !== 'win32' && mode !== 0o400 && mode !== 0o600) {
     return {
       ok: false,
       message: `SSH key permissions are ${mode.toString(8)} (should be 400 or 600) — run: chmod 600 ${resolved}`,

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;
 }
 

package/src/deployment/providers/docker.js

@@ -4,6 +4,12 @@ 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';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -14,11 +20,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);
 
+  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
    * @param {{ fullImage?: string, skipImageReuse?: boolean }} [options]
@@ -26,17 +60,30 @@ 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') {
+      await deployOverSsh(imageRef);
       log.success('Docker deployment complete');
       return;
     }
 
+    const dockerEnv = getDockerEnv();
+
     await execa(
       'docker',
       ['rm', '-f', containerName],
@@ -51,6 +98,39 @@ export function createDockerProvider(config, envName, env = process.env) {
     log.success('Docker deployment complete');
   }
 
+  /**
+   * @param {string} imageRef
+   */
+  async function deployOverSsh(imageRef) {
+    const cmds = buildRemoteDockerCommands(imageRef, containerName);
+    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);
+    } finally {
+      ssh.dispose();
+    }
+  }
+
   /**
    * @param {string} artifactDir
    * @param {{ buildId?: string, semver?: string, remoteKey?: string }} [meta]
@@ -65,7 +145,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 +162,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 +186,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);