@akash-chowdhury-24/deployhub 2.0.32 → 2.0.34

package/package.json

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

package/src/commands/deploy.js

@@ -11,6 +11,10 @@ import {
   runHealthChecksForEnvs,
   formatHealthCheckAllSummary,
 } from '../utils/health-check.js';
+import {
+  runDockerPortPublishChecksForEnvs,
+  verifyStageShouldRun,
+} from '../utils/docker-port-publish.js';
 import { createLogger } from '../logger/index.js';
 
 /**
@@ -76,12 +80,28 @@ export function registerDeployCommand(program) {
             const deployed = /** @type {string[]} */ (
               ctx.state.deployedTargets || targets
             );
-            return anyEnvHasResolvableHealthCheckUrl(ctx.config, deployed);
+            return verifyStageShouldRun(
+              ctx.config,
+              deployed,
+              anyEnvHasResolvableHealthCheckUrl
+            );
           },
           async run(ctx) {
             const deployed = /** @type {string[]} */ (
               ctx.state.deployedTargets || targets
             );
+            const portOutcome = await runDockerPortPublishChecksForEnvs(
+              ctx.config,
+              deployed,
+              { requireRunning: true }
+            );
+            if (portOutcome.failures.length > 0) {
+              throw new Error(portOutcome.failures[0].error);
+            }
+            for (const r of portOutcome.results) {
+              console.log(chalk.green(`Docker port published (${r.envName}): ${r.message}`));
+            }
+
             const { results, failures } = await runHealthChecksForEnvs(
               ctx.config,
               deployed

package/src/commands/doctor.js

@@ -40,6 +40,10 @@ import {
   formatRemoteDockerDaemonOk,
 } from '../utils/docker-remote.js';
 import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
+import {
+  checkEnvDockerPortPublish,
+  resolveDockerPublishPort,
+} from '../utils/docker-port-publish.js';
 import {
   buildPhpFpmUnitListCommand,
   formatPhpFpmMissingError,
@@ -591,6 +595,22 @@ export async function runDeploymentChecks(config, envName, envConfig) {
         })
       );
     }
+
+    const publishPort = resolveDockerPublishPort(config, settings, envName);
+    if (dockerRemoteMode === 'ssh' || publishPort != null) {
+      checks.push(
+        await runCheck('Docker port published', async () => {
+          const outcome = await checkEnvDockerPortPublish(config, envName, {
+            requireRunning: false,
+          });
+          return {
+            name: 'Docker port published',
+            pass: outcome.pass,
+            message: outcome.message,
+          };
+        })
+      );
+    }
   }
 
   if (deployType === 'kubernetes') {

package/src/commands/env.js

@@ -164,6 +164,7 @@ export function registerEnvCommand(program) {
             existingEnvNames: Object.keys(config.environments || {}),
             deployType: opts.method,
             nonInteractive: Boolean(opts.yes),
+            portDefault: config.port,
           }
         );
       } catch (err) {
@@ -171,12 +172,21 @@ export function registerEnvCommand(program) {
         process.exit(1);
       }
 
+      // Docker env add must not inherit top-level port via singleConfig — that
+      // silently stamps another environment's port onto the new env. Interactive
+      // answers carry deployAnswers.port; --yes omits it so SSH deploy/doctor
+      // fail with the published-port error instead of a wrong fallback.
+      const entrySingleConfig =
+        deployAnswers.deployType === 'docker'
+          ? { framework: singleConfig?.framework, port: deployAnswers.port }
+          : singleConfig;
+
       config.environments[name] = buildServerEnvEntry(
         deployAnswers,
         projectType,
         config.project,
         backendConfig,
-        singleConfig
+        entrySingleConfig
       );
 
       if (!config.defaultEnvironment) {

package/src/commands/init.js

@@ -382,6 +382,7 @@ export function registerInitCommand(program) {
             {
               ...(opts.envName ? { envName: opts.envName } : {}),
               existingEnvNames: Object.keys(environments),
+              portDefault: singleConfig?.port ?? backendConfig?.port,
             }
           );
           primaryDeployType = deployAnswers.deployType;

package/src/commands/verify.js

@@ -7,6 +7,10 @@ import {
   runHealthChecksForEnvs,
   formatHealthCheckAllSummary,
 } from '../utils/health-check.js';
+import {
+  runDockerPortPublishChecksForEnvs,
+  verifyStageShouldRun,
+} from '../utils/docker-port-publish.js';
 
 /**
  * Standalone verify — same per-env URL resolution and summary as the deploy pipeline stage.
@@ -31,7 +35,7 @@ export async function runVerify(config, envFlag, options = {}) {
     };
   }
 
-  if (!anyEnvHasResolvableHealthCheckUrl(config, targets)) {
+  if (!verifyStageShouldRun(config, targets, anyEnvHasResolvableHealthCheckUrl)) {
     const label =
       targets.length === 1
         ? `environment "${targets[0]}"`
@@ -47,28 +51,47 @@ export async function runVerify(config, envFlag, options = {}) {
     };
   }
 
+  const portOutcome = await runDockerPortPublishChecksForEnvs(config, targets, {
+    requireRunning: true,
+    ...options,
+  });
+
   const { results, failures } = await runHealthChecksForEnvs(config, targets, options);
-  const multi = targets.length > 1 || failures.length > 0;
+  const allFailures = [
+    ...portOutcome.failures.map((f) => ({ envName: f.envName, url: '', error: f.error })),
+    ...failures,
+  ];
+  const portResults = portOutcome.results.map((r) => ({
+    envName: r.envName,
+    url: '',
+    status: 0,
+    elapsed: 0,
+    message: r.message,
+  }));
+  const mergedResults = [...portResults, ...results];
+  const multi = targets.length > 1 || allFailures.length > 0;
   const summary = multi ? formatHealthCheckAllSummary(results, failures) : '';
 
   let message = '';
-  if (failures.length === 0 && results.length === 1 && !multi) {
+  if (allFailures.length === 0 && results.length === 1 && portOutcome.results.length === 0 && !multi) {
     const r = results[0];
     message = `Health check passed (${r.envName}): HTTP ${r.status} (${r.elapsed}ms)`;
-  } else if (failures.length === 0 && results.length === 0) {
+  } else if (allFailures.length === 0 && results.length === 0 && portOutcome.results.length === 1) {
+    message = portOutcome.results[0].message;
+  } else if (allFailures.length === 0 && results.length === 0 && portOutcome.results.length === 0) {
     message = `No health check URL configured for the selected environment(s).`;
   }
 
   return {
-    ok: failures.length === 0 && results.length > 0,
+    ok: allFailures.length === 0 && (results.length > 0 || portOutcome.results.length > 0),
     targets,
-    results,
-    failures,
+    results: mergedResults,
+    failures: allFailures,
     summary,
     message:
       message ||
-      (failures.length > 0
-        ? failures[0].error
+      (allFailures.length > 0
+        ? allFailures[0].error
         : `All ${results.length} environment(s) passed health checks.`),
     skippedDisabled,
   };

package/src/core/stages.js

@@ -8,6 +8,11 @@ import {
   anyEnvHasResolvableHealthCheckUrl,
   runHealthChecksForEnvs,
 } from '../utils/health-check.js';
+import {
+  anyDockerEnvHasPublishPort,
+  runDockerPortPublishChecksForEnvs,
+  verifyStageShouldRun,
+} from '../utils/docker-port-publish.js';
 import { getProjectVersion } from '../utils/version.js';
 import { resolveBuildId } from '../utils/build-id.js';
 import { ensureDeployScaffold } from '../utils/scaffold.js';
@@ -224,12 +229,25 @@ export function buildPipelineStages(config, cwd, state) {
     {
       name: 'verify',
       enabled: (ctx) => {
-        if (ctx.config.pipeline.verify !== true) return false;
+        if (ctx.config.pipeline.verify !== true) {
+          const deployed = /** @type {string[]} */ (ctx.state.deployedTargets || []);
+          return anyDockerEnvHasPublishPort(ctx.config, deployed);
+        }
         const deployed = /** @type {string[]} */ (ctx.state.deployedTargets || []);
-        return anyEnvHasResolvableHealthCheckUrl(ctx.config, deployed);
+        return verifyStageShouldRun(
+          ctx.config,
+          deployed,
+          anyEnvHasResolvableHealthCheckUrl
+        );
       },
       async run(ctx) {
         const deployed = /** @type {string[]} */ (ctx.state.deployedTargets || []);
+        const portOutcome = await runDockerPortPublishChecksForEnvs(ctx.config, deployed, {
+          requireRunning: true,
+        });
+        if (portOutcome.failures.length > 0) {
+          throw new Error(portOutcome.failures[0].error);
+        }
         const { results, failures } = await runHealthChecksForEnvs(ctx.config, deployed);
         if (failures.length > 0) {
           throw new Error(failures[0].error);

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);
@@ -306,8 +311,12 @@ 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) {
+async function promptDockerDeployment(base, projectName, projectType, options = {}) {
   const imageAnswers = await inquirer.prompt([
     {
       type: 'input',
@@ -404,7 +413,25 @@ async function promptDockerDeployment(base, projectName, projectType) {
     ]);
   }
 
-  const { healthUrl } = await inquirer.prompt([
+  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',
       name: 'healthUrl',
@@ -418,6 +445,7 @@ async function promptDockerDeployment(base, projectName, projectType) {
     remoteMode,
     ...sshAnswers,
     dockerHost: rawAnswers.dockerHost || '',
+    port,
     healthUrl,
   };
 }
@@ -652,6 +680,15 @@ export function buildServerEnvEntry(
       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',

package/src/deployment/providers/docker.js

@@ -10,6 +10,13 @@ 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
@@ -38,6 +45,7 @@ export function createDockerProvider(config, envName, env = process.env) {
     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);
@@ -77,7 +85,10 @@ export function createDockerProvider(config, envName, env = process.env) {
     }
 
     if (remoteMode === 'ssh') {
-      await deployOverSsh(imageRef);
+      if (publishPort == null) {
+        throw new Error(formatDockerSshPortRequired(envName));
+      }
+      await deployOverSsh(imageRef, publishPort);
       log.success('Docker deployment complete');
       return;
     }
@@ -90,19 +101,59 @@ export function createDockerProvider(config, envName, env = process.env) {
       { 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) {
-    const cmds = buildRemoteDockerCommands(imageRef, containerName);
+  async function deployOverSsh(imageRef, port) {
+    const cmds = buildRemoteDockerCommands(imageRef, containerName, {}, { publishPort: port });
     const session = sshSession();
     const ssh = await session.connect();
     try {
@@ -126,6 +177,21 @@ export function createDockerProvider(config, envName, env = process.env) {
         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();
     }

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

@@ -15,6 +15,57 @@ import {
   EXPLICIT_IMAGE_TAG_WARNING,
 } from './docker-image.js';
 
+/**
+ * Classify `docker pull` failure for rollback logs / interpreted-backend errors.
+ * @param {unknown} err
+ * @returns {'not found'|'auth failed'|'network error'|string}
+ */
+export function classifyDockerPullFailure(err) {
+  const execErr = /** @type {{ message?: string, stderr?: string, stdout?: string }} */ (err);
+  const combined = `${execErr?.message || ''} ${execErr?.stderr || ''} ${execErr?.stdout || ''}`.toLowerCase();
+  // Docker Hub reports missing repos as "denied" — check existence first.
+  if (
+    combined.includes('manifest unknown') ||
+    combined.includes('not found') ||
+    combined.includes('repository does not exist') ||
+    combined.includes('no such image')
+  ) {
+    return 'not found';
+  }
+  if (
+    combined.includes('unauthorized') ||
+    combined.includes('authentication required') ||
+    combined.includes('access denied') ||
+    combined.includes('denied: requested access')
+  ) {
+    return 'auth failed';
+  }
+  if (
+    combined.includes('network') ||
+    combined.includes('timeout') ||
+    combined.includes('timed out') ||
+    combined.includes('econnrefused') ||
+    combined.includes('connection refused') ||
+    combined.includes('no such host') ||
+    combined.includes('dial tcp')
+  ) {
+    return 'network error';
+  }
+  const stderr = String(execErr?.stderr || '').trim().split('\n').filter(Boolean).pop();
+  return stderr || (err instanceof Error ? err.message : 'pull failed');
+}
+
+/**
+ * @param {string} imageRef
+ * @param {string} reason
+ */
+export function formatImageNotLocalAndPullFailed(imageRef, reason) {
+  return (
+    `Target image ${imageRef} not found locally and could not be pulled ` +
+    `from the registry (${reason}).`
+  );
+}
+
 /**
  * Shared Docker image build, reuse, push, and pullability logic used by
  * docker and kubernetes deploy providers.
@@ -105,6 +156,41 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
     }
   }
 
+  /**
+   * Rollback (and any skipImageReuse path): after a local-cache miss, pull the
+   * exact tag from the registry before falling through to artifact rebuild.
+   * @param {string} ref
+   * @returns {Promise<{ ok: true, output: string }|{ ok: false, reason: string, output: string }>}
+   */
+  async function tryPullImage(ref) {
+    log.info(`Pulling ${ref} from registry...`);
+    try {
+      const pulled = await execa('docker', ['pull', ref], {
+        stdio: 'pipe',
+        env: getDockerEnv(),
+      });
+      const output = [pulled.stdout, pulled.stderr].filter(Boolean).join('\n').trim();
+      if (output) log.info(output);
+      if (await imageExistsLocally(ref)) {
+        log.success(`Pulled ${ref}`);
+        return { ok: true, output };
+      }
+      return {
+        ok: false,
+        reason: 'pull reported success but image is still missing locally',
+        output,
+      };
+    } catch (err) {
+      const execErr = /** @type {{ stdout?: string, stderr?: string }} */ (err);
+      const output = [execErr.stdout, execErr.stderr]
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+      if (output) log.info(output);
+      return { ok: false, reason: classifyDockerPullFailure(err), output };
+    }
+  }
+
   /**
    * Prefer the image already built during the pipeline `docker` stage.
    * Retag when the pipeline used `:latest` and deploy needs a version tag.
@@ -138,8 +224,15 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
    * @param {Record<string, unknown>} metadata
    * @param {string} framework
    * @param {number} port
+   * @param {string} [imageRef]
    */
-  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
+  async function prepareBackendBuildContext(
+    buildContext,
+    metadata,
+    framework,
+    port,
+    imageRef = fullImage
+  ) {
     if (framework === 'spring') {
       const targetDir = path.join(buildContext, 'target');
       if (await fs.pathExists(targetDir)) {
@@ -199,7 +292,7 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
     if (isInterpretedBackendFramework(framework)) {
       const gap = describeInterpretedBackendGap(framework);
       throw new Error(
-        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" from the packaged artifact.\n` +
+        `Cannot rebuild ${gap.ecosystem} backend image "${imageRef}" from the packaged artifact.\n` +
           `Backend artifacts include source/manifests but not ${gap.missing}, ` +
           `so Dockerfiles that run \`${gap.installCmd}\` cannot reliably succeed from the artifact alone.\n\n` +
           'What to do instead:\n' +
@@ -286,7 +379,13 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
           generateFrontendRuntimeDockerfile(buildOutput)
         );
       } else {
-        await prepareBackendBuildContext(buildContext, metadata, framework, port);
+        await prepareBackendBuildContext(
+          buildContext,
+          metadata,
+          framework,
+          port,
+          imageRef
+        );
       }
 
       await execa('docker', ['build', '-t', imageRef, '.'], {
@@ -322,6 +421,8 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
     await dockerLogin();
 
     let reused = false;
+    /** @type {string|null} */
+    let registryPullFailure = null;
     if (!options.skipImageReuse) {
       // Normal deploy: prefer pipeline image (exact tag, then :latest retag).
       reused = await ensureImageFromPipeline(imageRef);
@@ -331,16 +432,32 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
       log.info(`Using restored image ${imageRef} (skipImageReuse — no :latest retag)`);
       reused = true;
     } else {
-      log.info(
-        `Target image ${imageRef} not found locally — attempting rebuild from artifact`
-      );
+      const pulled = await tryPullImage(imageRef);
+      if (pulled.ok) {
+        reused = true;
+      } else {
+        registryPullFailure = pulled.reason;
+        log.info(
+          `${formatImageNotLocalAndPullFailed(imageRef, pulled.reason)} — attempting rebuild from artifact`
+        );
+      }
     }
 
     let ranCompose = false;
 
     if (!reused) {
-      const result = await buildFromArtifactContents(artifactDir, imageRef);
-      ranCompose = Boolean(result?.ranCompose);
+      try {
+        const result = await buildFromArtifactContents(artifactDir, imageRef);
+        ranCompose = Boolean(result?.ranCompose);
+      } catch (err) {
+        if (registryPullFailure) {
+          const detail = err instanceof Error ? err.message : String(err);
+          throw new Error(
+            `${formatImageNotLocalAndPullFailed(imageRef, registryPullFailure)}\n${detail}`
+          );
+        }
+        throw err;
+      }
     }
 
     if (ranCompose) {
@@ -372,6 +489,7 @@ export function createDockerImageDeployContext(config, env = process.env, log) {
     dockerLogin,
     maybePushImage,
     ensureImageFromPipeline,
+    tryPullImage,
     buildFromArtifactContents,
     ensureImageReadyForDeploy,
   };

package/src/utils/docker-port-publish.js

@@ -0,0 +1,328 @@
+import { execa } from 'execa';
+import { getEnvMethod, getEnvSettings } from '../core/environments.js';
+import { resolveDockerContainerName } from './docker-container-name.js';
+import { resolveDockerRemoteMode } from './docker-remote-mode.js';
+import { resolveDockerSshTarget } from './docker-remote.js';
+import { createSshExecSession } from '../deployment/ssh-connection.js';
+import { shellQuote } from './shell-quote.js';
+
+/** Go template: running|bindings. Empty HostIp treated as 0.0.0.0. */
+export const DOCKER_INSPECT_PORT_FORMAT =
+  `{{if .State.Running}}running{{else}}stopped{{end}}|` +
+  `{{range $p, $conf := .NetworkSettings.Ports}}` +
+  `{{range $conf}}` +
+  `{{if eq .HostIp ""}}0.0.0.0{{else}}{{.HostIp}}{{end}}:{{.HostPort}}->` +
+  `{{end}}{{end}}`;
+
+export const DOCKER_PORT_NOT_PUBLISHED_TRAILER =
+  'The app is not reachable from outside the container.';
+
+/**
+ * Exact doctor/verify failure copy when a container is running without `-p`.
+ * @param {string} containerName
+ * @param {number} port
+ */
+export function formatDockerPortNotPublished(containerName, port) {
+  return (
+    `Container '${containerName}' is running but port ${port} is not published ` +
+    `on the host (no 0.0.0.0:${port}-> mapping).\n` +
+    DOCKER_PORT_NOT_PUBLISHED_TRAILER
+  );
+}
+
+/**
+ * @param {string} containerName
+ * @param {number} port
+ */
+export function formatDockerPortPublished(containerName, port) {
+  return `Container '${containerName}' publishes 0.0.0.0:${port}->`;
+}
+
+/**
+ * @param {string} envName
+ */
+export function formatDockerSshPortRequired(envName) {
+  return (
+    `Docker remote.mode "ssh" requires a published port. ` +
+    `Set environments.${envName}.config.port (or top-level port) so the container ` +
+    `is started with -p <port>:<port>. Deploying without -p leaves the app unreachable.`
+  );
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {number|null}
+ */
+function parsePublishPort(raw) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) return null;
+  return n;
+}
+
+/**
+ * Top-level `config.port` is the legacy single-env fallback (scenario 2A).
+ * With two or more docker environments it must not be inherited by a later
+ * env that never stored its own `config.port` — that would silently publish
+ * another environment's port.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @param {string} [envName]
+ */
+function shouldUseTopLevelDockerPortFallback(config = {}, envName) {
+  const dockerNames = Object.entries(config.environments || {})
+    .filter(([, entry]) => getEnvMethod(entry) === 'docker')
+    .map(([name]) => name);
+
+  if (dockerNames.length <= 1) return true;
+  if (!envName) return false;
+
+  if (config.defaultEnvironment && dockerNames.includes(config.defaultEnvironment)) {
+    return envName === config.defaultEnvironment;
+  }
+  if (
+    config.unprefixedSecretEnvironment &&
+    dockerNames.includes(config.unprefixedSecretEnvironment)
+  ) {
+    return envName === config.unprefixedSecretEnvironment;
+  }
+  return false;
+}
+
+/**
+ * Configured host/container publish port. No silent default — missing means
+ * SSH must fail loudly instead of running unpublished.
+ *
+ * Fallback chain is still `settings.port ?? config.port` (plus `backend.port`)
+ * for legacy single-env configs and the original docker env. It is not used
+ * for additional docker environments that omitted `config.port`.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @param {Record<string, unknown>} [settings]
+ * @param {string} [envName]
+ * @returns {number|null}
+ */
+export function resolveDockerPublishPort(config = {}, settings = {}, envName) {
+  const own = parsePublishPort(settings.port);
+  if (own != null) return own;
+  if (!shouldUseTopLevelDockerPortFallback(config, envName)) return null;
+  return parsePublishPort(config.port ?? config.backend?.port);
+}
+
+/**
+ * @param {string} stdout
+ * @param {number} port
+ */
+export function inspectShowsHostPortMapping(stdout, port) {
+  return String(stdout || '').includes(`0.0.0.0:${port}->`);
+}
+
+/**
+ * @param {string} containerName
+ */
+export function buildDockerInspectPortsArgs(containerName) {
+  return ['inspect', '--format', DOCKER_INSPECT_PORT_FORMAT, containerName];
+}
+
+/**
+ * @param {string} containerName
+ */
+export function buildDockerInspectPortsCommand(containerName) {
+  const args = buildDockerInspectPortsArgs(containerName);
+  return `docker inspect --format ${shellQuote(args[2])} ${shellQuote(containerName)}`;
+}
+
+/**
+ * @param {{ code?: number|null, stdout?: string, stderr?: string }} result
+ * @param {{ containerName: string, port: number, requireRunning: boolean }} opts
+ * @returns {{ pass: boolean, reason: 'published'|'not-running'|'unpublished'|'missing-container', message: string }}
+ */
+export function evaluateDockerPortPublish(result, opts) {
+  const { containerName, port, requireRunning } = opts;
+  const code = result.code;
+  const raw = String(result.stdout || '');
+  let running = true;
+  let mappings = raw;
+  const pipe = raw.indexOf('|');
+  if (pipe >= 0 && (raw.startsWith('running|') || raw.startsWith('stopped|'))) {
+    running = raw.startsWith('running|');
+    mappings = raw.slice(pipe + 1);
+  }
+
+  if ((code !== 0 && code !== null && code !== undefined) || !running) {
+    if (!requireRunning) {
+      return {
+        pass: true,
+        reason: 'not-running',
+        message: `No running container '${containerName}' — deploy first, then re-run this check.`,
+      };
+    }
+    if (!running && (code === 0 || code === null || code === undefined)) {
+      return {
+        pass: false,
+        reason: 'missing-container',
+        message:
+          `Container '${containerName}' is not running — cannot confirm port ${port} is published.`,
+      };
+    }
+    return {
+      pass: false,
+      reason: 'missing-container',
+      message:
+        `Container '${containerName}' is not running — cannot confirm port ${port} is published.`,
+    };
+  }
+
+  if (inspectShowsHostPortMapping(mappings, port)) {
+    return {
+      pass: true,
+      reason: 'published',
+      message: formatDockerPortPublished(containerName, port),
+    };
+  }
+
+  return {
+    pass: false,
+    reason: 'unpublished',
+    message: formatDockerPortNotPublished(containerName, port),
+  };
+}
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string[]} envNames
+ */
+export function anyDockerEnvHasPublishPort(config, envNames) {
+  return (envNames || []).some((envName) => {
+    const entry = config.environments?.[envName];
+    if (getEnvMethod(entry) !== 'docker') return false;
+    const settings = getEnvSettings(entry);
+    return resolveDockerPublishPort(config, settings, envName) != null;
+  });
+}
+
+/**
+ * Whether the post-deploy verify stage should run (HTTP health and/or docker port).
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string[]} envNames
+ * @param {(config: import('../core/config.js').DeployHubConfig, envNames: string[]) => boolean} hasHealthUrl
+ */
+export function verifyStageShouldRun(config, envNames, hasHealthUrl) {
+  return Boolean(hasHealthUrl(config, envNames) || anyDockerEnvHasPublishPort(config, envNames));
+}
+
+/**
+ * Inspect one docker environment's running container for 0.0.0.0:<port>->.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string} envName
+ * @param {{ requireRunning?: boolean, env?: Record<string, string|undefined> }} [options]
+ */
+export async function checkEnvDockerPortPublish(config, envName, options = {}) {
+  const entry = config.environments?.[envName];
+  const method = getEnvMethod(entry);
+  if (method !== 'docker') {
+    return { skipped: true, envName, pass: true, message: '' };
+  }
+
+  const settings = getEnvSettings(entry);
+  const env = options.env || process.env;
+  const requireRunning = options.requireRunning !== false;
+  const port = resolveDockerPublishPort(config, settings, envName);
+  const remoteMode = resolveDockerRemoteMode(settings, env);
+  const containerName = resolveDockerContainerName(config, envName);
+
+  if (port == null) {
+    if (remoteMode === 'ssh') {
+      return {
+        skipped: false,
+        envName,
+        pass: false,
+        message: formatDockerSshPortRequired(envName),
+      };
+    }
+    return { skipped: true, envName, pass: true, message: '' };
+  }
+
+  /** @type {{ code?: number|null, stdout?: string, stderr?: string }} */
+  let result;
+  if (remoteMode === 'ssh') {
+    const target = resolveDockerSshTarget(settings, env);
+    const session = createSshExecSession({
+      ...target,
+      keyPath: target.keyPath ? String(target.keyPath) : undefined,
+      env,
+    });
+    const ssh = await session.connect();
+    try {
+      result = await session.execUnchecked(ssh, buildDockerInspectPortsCommand(containerName));
+    } finally {
+      ssh.dispose();
+    }
+  } else {
+    try {
+      const inspected = await execa('docker', buildDockerInspectPortsArgs(containerName), {
+        stdio: 'pipe',
+        env: { ...process.env, ...env },
+      });
+      result = { code: 0, stdout: inspected.stdout, stderr: inspected.stderr };
+    } catch (err) {
+      const execErr = /** @type {{ exitCode?: number, stdout?: string, stderr?: string }} */ (err);
+      result = {
+        code: execErr.exitCode ?? 1,
+        stdout: execErr.stdout || '',
+        stderr: execErr.stderr || (err instanceof Error ? err.message : String(err)),
+      };
+    }
+  }
+
+  const verdict = evaluateDockerPortPublish(result, {
+    containerName,
+    port,
+    requireRunning,
+  });
+  return {
+    skipped: false,
+    envName,
+    pass: verdict.pass,
+    message: verdict.message,
+    reason: verdict.reason,
+  };
+}
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {string[]} envNames
+ * @param {{ requireRunning?: boolean, env?: Record<string, string|undefined> }} [options]
+ */
+export async function runDockerPortPublishChecksForEnvs(config, envNames, options = {}) {
+  /** @type {{ envName: string, message: string }[]} */
+  const results = [];
+  /** @type {{ envName: string, error: string }[]} */
+  const failures = [];
+
+  for (const envName of envNames || []) {
+    const outcome = await checkEnvDockerPortPublish(config, envName, options);
+    if (outcome.skipped) continue;
+    if (outcome.pass) {
+      results.push({ envName: outcome.envName, message: outcome.message });
+    } else {
+      failures.push({ envName: outcome.envName, error: outcome.message });
+    }
+  }
+
+  return { results, failures };
+}
+
+export default {
+  DOCKER_INSPECT_PORT_FORMAT,
+  formatDockerPortNotPublished,
+  formatDockerPortPublished,
+  formatDockerSshPortRequired,
+  resolveDockerPublishPort,
+  inspectShowsHostPortMapping,
+  evaluateDockerPortPublish,
+  anyDockerEnvHasPublishPort,
+  verifyStageShouldRun,
+  checkEnvDockerPortPublish,
+  runDockerPortPublishChecksForEnvs,
+};

package/src/utils/docker-remote.js

@@ -178,8 +178,9 @@ export async function probeRemoteDockerPs(target) {
  * @param {string} imageRef
  * @param {string} containerName
  * @param {Record<string, string>} [runEnv]
+ * @param {{ publishPort?: number|null }} [options]
  */
-export function buildRemoteDockerCommands(imageRef, containerName, runEnv = {}) {
+export function buildRemoteDockerCommands(imageRef, containerName, runEnv = {}, options = {}) {
   const image = shellQuote(imageRef);
   const name = shellQuote(containerName);
   /** @type {string[]} */
@@ -188,12 +189,15 @@ export function buildRemoteDockerCommands(imageRef, containerName, runEnv = {})
     envFlags.push(`-e ${shellQuote(`${key}=${value}`)}`);
   }
   const envArg = envFlags.length > 0 ? `${envFlags.join(' ')} ` : '';
+  const publishPort = options.publishPort;
+  const pFlag =
+    publishPort != null ? `-p ${shellQuote(`${publishPort}:${publishPort}`)} ` : '';
 
   return {
     stop: `docker stop ${name} 2>/dev/null || true`,
     rm: `docker rm -f ${name} 2>/dev/null || true`,
     pull: `docker pull ${image}`,
-    run: `docker run -d --rm --name ${name} ${envArg}${image}`,
+    run: `docker run -d --rm --name ${name} ${pFlag}${envArg}${image}`,
     ps: `docker ps --filter ${shellQuote(`name=^/${containerName}$`)} --format ${shellQuote('{{.Status}}')}`,
     info: 'docker info',
     /**

package/src/utils/rollback/engine.js

@@ -11,6 +11,9 @@ import {
   getEnvMethod,
   resolveDefaultEnvironmentName,
 } from '../../core/environments.js';
+import {
+  runDockerPortPublishChecksForEnvs,
+} from '../docker-port-publish.js';
 import fs from 'fs-extra';
 import path from 'path';
 
@@ -32,6 +35,19 @@ async function rollbackTarget(config, artifactDir, envName, meta) {
 
   const provider = getDeploymentProvider(method, config, envName);
   await provider.rollback(artifactDir, meta);
+
+  // Same post-deploy port-publish check as the deploy pipeline verify stage
+  // (`runDockerPortPublishChecksForEnvs`). SSH/EC2/VM skip; docker envs fail
+  // if the restored container is up without 0.0.0.0:<port>->.
+  const portOutcome = await runDockerPortPublishChecksForEnvs(config, [envName], {
+    requireRunning: true,
+  });
+  if (portOutcome.failures.length > 0) {
+    throw new Error(portOutcome.failures[0].error);
+  }
+  for (const r of portOutcome.results) {
+    log.success(r.message);
+  }
 }
 
 /**