@akash-chowdhury-24/deployhub 2.0.5 → 2.0.6

package/package.json

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

package/src/adapters/dotnet.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 function create(config, cwd) {
   const log = createLogger('dotnet');
@@ -28,11 +29,17 @@ function create(config, cwd) {
     },
 
     async docker() {
-      if (await fs.pathExists(path.join(cwd, 'Dockerfile'))) {
-        await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
-          cwd,
-          stdio: 'inherit',
-        });
+      if (!(await fs.pathExists(path.join(cwd, 'Dockerfile')))) {
+        return;
+      }
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd,
+        stdio: 'inherit',
+      });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
       }
     },
   };

package/src/adapters/go.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 function create(config, cwd) {
   const log = createLogger('go');
@@ -27,11 +28,17 @@ function create(config, cwd) {
     },
 
     async docker() {
-      if (await fs.pathExists(path.join(cwd, 'Dockerfile'))) {
-        await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
-          cwd,
-          stdio: 'inherit',
-        });
+      if (!(await fs.pathExists(path.join(cwd, 'Dockerfile')))) {
+        return;
+      }
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd,
+        stdio: 'inherit',
+      });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
       }
     },
   };

package/src/adapters/java.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 function create(config, cwd) {
   const log = createLogger('java');
@@ -33,11 +34,17 @@ function create(config, cwd) {
     },
 
     async docker() {
-      if (await fs.pathExists(path.join(cwd, 'Dockerfile'))) {
-        await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
-          cwd,
-          stdio: 'inherit',
-        });
+      if (!(await fs.pathExists(path.join(cwd, 'Dockerfile')))) {
+        return;
+      }
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd,
+        stdio: 'inherit',
+      });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
       }
     },
   };

package/src/adapters/node.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 /**
  * @typedef {Object} LanguageAdapter
@@ -64,12 +65,18 @@ function create(config, cwd) {
         log.warn('No Dockerfile found, skipping docker build');
         return;
       }
-      log.info('Building Docker image...');
-      const imageName = `${config.project}:latest`;
-      await execa('docker', ['build', '-t', imageName, '.'], {
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
         cwd,
         stdio: 'inherit',
       });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], {
+          cwd,
+          stdio: 'pipe',
+        });
+      }
     },
   };
 }

package/src/adapters/php.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 function create(config, cwd) {
   const log = createLogger('php');
@@ -30,11 +31,17 @@ function create(config, cwd) {
     },
 
     async docker() {
-      if (await fs.pathExists(path.join(cwd, 'Dockerfile'))) {
-        await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
-          cwd,
-          stdio: 'inherit',
-        });
+      if (!(await fs.pathExists(path.join(cwd, 'Dockerfile')))) {
+        return;
+      }
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd,
+        stdio: 'inherit',
+      });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
       }
     },
   };

package/src/adapters/python.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 function create(config, cwd) {
   const log = createLogger('python');
@@ -43,10 +44,15 @@ function create(config, cwd) {
         log.warn('No Dockerfile found, skipping');
         return;
       }
-      await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
         cwd,
         stdio: 'inherit',
       });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
+      }
     },
   };
 }

package/src/adapters/rails.adapter.js

@@ -2,6 +2,7 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../logger/index.js';
+import { resolveDockerImageRef } from '../utils/docker-image.js';
 
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
@@ -54,11 +55,15 @@ function create(config, cwd) {
         log.warn('No Dockerfile found, skipping docker build');
         return;
       }
-      log.info('Building Docker image...');
-      await execa('docker', ['build', '-t', `${config.project}:latest`, '.'], {
+      const { fullImage, latestImage } = resolveDockerImageRef(config);
+      log.info(`Building Docker image (${fullImage})...`);
+      await execa('docker', ['build', '-t', fullImage, '.'], {
         cwd,
         stdio: 'inherit',
       });
+      if (fullImage !== latestImage) {
+        await execa('docker', ['tag', fullImage, latestImage], { stdio: 'pipe' });
+      }
     },
   };
 }

package/src/commands/init.js

@@ -199,6 +199,9 @@ async function generateProjectScaffold(config, environments, cwd) {
   if (dockerResult.generated) {
     console.log(chalk.gray('  • Dockerfile (auto-generated)'));
   }
+  if (dockerResult.dockerignoreGenerated) {
+    console.log(chalk.gray('  • .dockerignore (auto-generated)'));
+  }
 
   const k8sResult = await ensureKubernetesManifests(cwd, config, environments);
   if (k8sResult.generated) {

package/src/core/stages.js

@@ -41,6 +41,8 @@ export function buildPipelineStages(config, cwd, state) {
             ctx.config.port = detected.port;
           }
         }
+        // Resolve version before docker so pipeline build and deploy share the same tag
+        ctx.config.version = await getProjectVersion(ctx.cwd);
         const scaffold = await ensureDeployScaffold(
           ctx.cwd,
           ctx.config,
@@ -118,7 +120,9 @@ export function buildPipelineStages(config, cwd, state) {
       name: 'artifact',
       enabled: (ctx) => ctx.config.artifact !== false,
       async run(ctx) {
-        ctx.config.version = await getProjectVersion(ctx.cwd);
+        if (!ctx.config.version) {
+          ctx.config.version = await getProjectVersion(ctx.cwd);
+        }
         const result = await createArtifact(
           ctx.config,
           /** @type {string[]} */ (ctx.state.deployedTargets || []),

package/src/deployment/deployment-env.js

@@ -388,7 +388,14 @@ export function getDeploymentSecretKeys(deployType, config = null) {
 
   for (const d of defs) {
     if (d.when === 'backend' && !isBackend) continue;
-    if (d.when === 'optional') continue;
+    // Docker optional vars must still appear in CI workflow/secrets checklist —
+    // empty secrets are fine when unused; missing DOCKER_IMAGE_NAME is not.
+    if (d.when === 'optional') {
+      if (deployType === 'docker' && d.key.startsWith('DOCKER_')) {
+        keys.push(d.key);
+      }
+      continue;
+    }
     if (d.key === 'SSH_KEY_PATH') {
       keys.push('SSH_KEY');
       continue;
@@ -512,13 +519,16 @@ export const DEPLOYMENT_GUIDE = {
     ],
     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.',
-      'Builds and runs containers via docker compose during deploy.',
+      '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 (and registry creds if private).',
-      'If using a remote Docker host, set DOCKER_HOST and TLS cert paths in .env.',
-      'Add the same values as GitHub Secrets for CI.',
+      '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.',
+      'If using a private registry: also set DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN.',
+      'Add GitHub Secrets (Settings → Secrets and variables → Actions): DOCKER_IMAGE_NAME (required). Local .env is NOT used by GitHub Actions — doctor only checks your machine.',
+      'Also add as GitHub Secrets if set locally: DOCKER_IMAGE_TAG, DOCKER_REGISTRY_URL, DOCKER_REGISTRY_USERNAME, DOCKER_REGISTRY_TOKEN, DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.',
       'Run deployhub doctor to verify Docker is reachable.',
       'git push origin main to trigger your first deployment.',
     ],

package/src/deployment/providers/docker.js

@@ -2,6 +2,17 @@ import { execa } from 'execa';
 import fs from 'fs-extra';
 import path from 'path';
 import { createLogger } from '../../logger/index.js';
+import { extractArtifact } from '../../artifact/engine.js';
+import {
+  describeInterpretedBackendGap,
+  generateDotnetRuntimeDockerfile,
+  generateFrontendRuntimeDockerfile,
+  generateGoRuntimeDockerfile,
+  generateSpringRuntimeDockerfile,
+  isFrontendStaticFramework,
+  isInterpretedBackendFramework,
+  resolveDockerImageRef,
+} from '../../utils/docker-image.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -11,8 +22,8 @@ import { createLogger } from '../../logger/index.js';
 export function createDockerProvider(config, envName, env = process.env) {
   const log = createLogger('docker');
 
-  const imageName = env.DOCKER_IMAGE_NAME || config.project;
-  const imageTag = env.DOCKER_IMAGE_TAG || config.version || 'latest';
+  const { fullImage, latestImage, legacyLatestImage, imageTag } =
+    resolveDockerImageRef(config, env);
   const registryUrl = env.DOCKER_REGISTRY_URL || '';
   const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
   const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
@@ -27,12 +38,12 @@ export function createDockerProvider(config, envName, env = process.env) {
     return dockerEnv;
   }
 
-  const fullImage = registryUrl && !imageName.includes('/')
-    ? `${registryUrl.replace(/\/$/, '')}/${imageName}:${imageTag}`
-    : `${imageName}:${imageTag}`;
+  function hasRegistryCredentials() {
+    return Boolean(registryUser && registryToken);
+  }
 
   async function dockerLogin() {
-    if (!registryUser || !registryToken) return;
+    if (!hasRegistryCredentials()) return;
     const registry = registryUrl || 'https://index.docker.io/v1/';
     log.info('Logging in to container registry...');
     await execa(
@@ -47,48 +58,284 @@ export function createDockerProvider(config, envName, env = process.env) {
   }
 
   /**
-   * @param {string} artifactDir
+   * Push only when registry credentials are configured. Avoids a noisy failed
+   * push to Docker Hub for local-only image names.
    */
-  async function deploy(artifactDir) {
-    log.info(`Deploying via Docker (image: ${fullImage})...`);
-    const dockerEnv = getDockerEnv();
+  async function maybePushImage() {
+    if (!hasRegistryCredentials()) {
+      log.info(
+        'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
+      );
+      return;
+    }
 
-    const composePath = path.join(artifactDir, 'docker-compose.yml');
-    const dockerfilePath = path.join(artifactDir, 'Dockerfile');
+    log.info(`Pushing ${fullImage} to registry...`);
+    await execa('docker', ['push', fullImage], {
+      stdio: 'inherit',
+      env: getDockerEnv(),
+    });
+    log.success(`Pushed ${fullImage}`);
+  }
 
-    const hasCompose = await fs.pathExists(composePath);
-    const hasDockerfile = await fs.pathExists(dockerfilePath);
+  /**
+   * @param {string} ref
+   */
+  async function imageExists(ref) {
+    try {
+      await execa('docker', ['image', 'inspect', ref], {
+        stdio: 'pipe',
+        env: getDockerEnv(),
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
-    await dockerLogin();
+  /**
+   * Prefer the image already built during the pipeline `docker` stage.
+   * Retag when the pipeline used `:latest` and deploy needs a version tag.
+   */
+  async function ensureImageFromPipeline() {
+    if (await imageExists(fullImage)) {
+      log.info(`Reusing existing image ${fullImage}`);
+      return true;
+    }
 
-    if (hasCompose) {
-      await execa(
-        'docker',
-        ['compose', 'up', '-d', '--build'],
-        { cwd: artifactDir, stdio: 'inherit', env: dockerEnv }
-      );
-    } else if (hasDockerfile) {
-      await execa('docker', ['build', '-t', fullImage, '.'], {
-        cwd: artifactDir,
+    const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
+      (ref) => ref !== fullImage
+    );
+
+    for (const candidate of candidates) {
+      if (!(await imageExists(candidate))) continue;
+      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
+      await execa('docker', ['tag', candidate, fullImage], {
         stdio: 'inherit',
-        env: dockerEnv,
+        env: getDockerEnv(),
       });
-      await execa('docker', ['push', fullImage], {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Backend artifacts omit lockfiles/node_modules. Prefer a pre-built binary
+   * runtime image when present; otherwise fail with an actionable error.
+   * @param {string} buildContext
+   * @param {Record<string, unknown>} metadata
+   * @param {string} framework
+   * @param {number} port
+   */
+  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
+    if (framework === 'spring') {
+      const targetDir = path.join(buildContext, 'target');
+      if (await fs.pathExists(targetDir)) {
+        const jars = (await fs.readdir(targetDir)).filter((f) => f.endsWith('.jar'));
+        if (jars.length > 0) {
+          const jarRel = `target/${jars[0]}`;
+          log.info(`Building runtime image from pre-built JAR (${jarRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateSpringRuntimeDockerfile(jarRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'go') {
+      const binDir = path.join(buildContext, 'bin');
+      if (await fs.pathExists(binDir)) {
+        const bins = await fs.readdir(binDir);
+        if (bins.length > 0) {
+          const binRel = `bin/${bins[0]}`;
+          log.info(`Building runtime image from pre-built Go binary (${binRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateGoRuntimeDockerfile(binRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'dotnet') {
+      const publishDir =
+        /** @type {string} */ (metadata.buildOutput) ||
+        config.buildOutput ||
+        'publish';
+      const publishPath = path.join(buildContext, publishDir);
+      if (await fs.pathExists(publishPath)) {
+        log.info(`Building runtime image from pre-built .NET output (${publishDir}/)...`);
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateDotnetRuntimeDockerfile(publishDir, port)
+        );
+        return;
+      }
+    }
+
+    const dockerfilePath = path.join(buildContext, 'Dockerfile');
+    if (!(await fs.pathExists(dockerfilePath))) {
+      throw new Error(
+        'No Dockerfile found in artifact and no pipeline image to reuse. ' +
+          'Add a Dockerfile and enable pipeline.docker so the image is built from project source.'
+      );
+    }
+
+    // Interpreted backends (Node/Python/PHP/Ruby): never rebuild from artifact.
+    // Artifacts ship source + manifest files, not installed dependency trees.
+    if (isInterpretedBackendFramework(framework)) {
+      const gap = describeInterpretedBackendGap(framework);
+      throw new Error(
+        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" 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' +
+          '  1. Enable pipeline.docker in deployhub.config.json (default when Docker deploy is selected).\n' +
+          '  2. Run a full `deployhub build` so the image is built from the project root (with full deps).\n' +
+          '  3. Deploy will reuse that local image (retag/push/run) — it will not rebuild from the artifact.\n\n' +
+          `Standalone \`deployhub deploy\` without a pre-built local image is not supported for ${gap.ecosystem} backends.`
+      );
+    }
+
+    // Remaining backends (unknown frameworks): try the packaged Dockerfile, but warn.
+    log.warn(
+      'Building backend image from extracted artifact. Prefer pipeline.docker so the image ' +
+        'is built once from full project source, then reused on deploy.'
+    );
+  }
+
+  /**
+   * Standalone deploy fallback: extract the packaged artifact and build a
+   * runtime image from pre-built output (frontend) or compiled backend artifacts.
+   * Never builds from artifactDir root — that only has zip/metadata + a source Dockerfile.
+   * @param {string} artifactDir
+   */
+  async function buildFromArtifactContents(artifactDir) {
+    const zipPath = path.join(artifactDir, 'artifact.zip');
+    if (!(await fs.pathExists(zipPath))) {
+      throw new Error(
+        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
+          'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
+      );
+    }
+
+    const buildContext = path.join(artifactDir, '_docker_build');
+    await fs.remove(buildContext);
+    await extractArtifact(artifactDir, buildContext);
+
+    try {
+      const metadataPath = path.join(buildContext, 'metadata.json');
+      const metadata = (await fs.pathExists(metadataPath))
+        ? await fs.readJson(metadataPath)
+        : {};
+
+      const projectType = metadata.projectType || config.projectType || 'frontend';
+      const framework =
+        metadata.framework ||
+        config.framework ||
+        config.frontend?.framework ||
+        '';
+      const buildOutput =
+        metadata.buildOutput ||
+        config.buildOutput ||
+        config.frontend?.buildOutput ||
+        'dist';
+      const port =
+        Number(metadata.port) ||
+        config.port ||
+        config.backend?.port ||
+        3000;
+
+      const composePath = path.join(buildContext, 'docker-compose.yml');
+      if (await fs.pathExists(composePath)) {
+        log.info('Building via docker compose from extracted artifact...');
+        await execa('docker', ['compose', 'up', '-d', '--build'], {
+          cwd: buildContext,
+          stdio: 'inherit',
+          env: getDockerEnv(),
+        });
+        return { ranCompose: true };
+      }
+
+      const isStaticFrontend =
+        projectType === 'frontend' || isFrontendStaticFramework(framework);
+
+      if (isStaticFrontend) {
+        const outputDir = path.join(buildContext, buildOutput);
+        if (!(await fs.pathExists(outputDir))) {
+          throw new Error(
+            `Frontend artifact is missing build output "${buildOutput}". ` +
+              'Cannot build a runtime image from this artifact.'
+          );
+        }
+        log.info(
+          `Building runtime image from pre-built ${buildOutput}/ (no source rebuild)...`
+        );
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateFrontendRuntimeDockerfile(buildOutput)
+        );
+      } else {
+        await prepareBackendBuildContext(buildContext, metadata, framework, port);
+      }
+
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd: buildContext,
         stdio: 'inherit',
-        env: dockerEnv,
-      }).catch(() => {
-        log.warn('docker push skipped (registry may be local or push not configured)');
+        env: getDockerEnv(),
       });
-      await execa('docker', ['run', '-d', '--rm', '--name', config.project, fullImage], {
-        stdio: 'inherit',
+      return { ranCompose: false };
+    } finally {
+      await fs.remove(buildContext).catch(() => {});
+    }
+  }
+
+  /**
+   * @param {string} artifactDir
+   */
+  async function deploy(artifactDir) {
+    log.info(`Deploying via Docker (image: ${fullImage})...`);
+    const dockerEnv = getDockerEnv();
+
+    await dockerLogin();
+
+    const reused = await ensureImageFromPipeline();
+    let ranCompose = false;
+
+    if (!reused) {
+      const result = await buildFromArtifactContents(artifactDir);
+      ranCompose = Boolean(result?.ranCompose);
+    }
+
+    if (ranCompose) {
+      log.success('Docker deployment complete');
+      return;
+    }
+
+    await maybePushImage();
+
+    // Keep :latest in sync when deploy uses a version tag
+    if (imageTag !== 'latest' && fullImage !== latestImage) {
+      await execa('docker', ['tag', fullImage, latestImage], {
+        stdio: 'pipe',
         env: dockerEnv,
-      });
-    } else {
-      throw new Error(
-        'No Dockerfile or docker-compose.yml found in artifact. Add one to your project or enable Docker in pipeline config.'
-      );
+      }).catch(() => {});
     }
 
+    await execa(
+      'docker',
+      ['rm', '-f', config.project],
+      { stdio: 'pipe', env: dockerEnv }
+    ).catch(() => {});
+
+    await execa('docker', ['run', '-d', '--rm', '--name', config.project, fullImage], {
+      stdio: 'inherit',
+      env: dockerEnv,
+    });
+
     log.success('Docker deployment complete');
   }
 

package/src/utils/docker-image.js

@@ -0,0 +1,181 @@
+/**
+ * Shared Docker image naming for pipeline builds and deploy.
+ */
+
+/**
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{
+ *   imageName: string,
+ *   imageTag: string,
+ *   fullImage: string,
+ *   latestImage: string,
+ *   legacyLatestImage: string,
+ * }}
+ */
+export function resolveDockerImageRef(config, env = process.env) {
+  const imageName = env.DOCKER_IMAGE_NAME || config.project;
+  const imageTag = env.DOCKER_IMAGE_TAG || config.version || 'latest';
+  const registryUrl = env.DOCKER_REGISTRY_URL || '';
+
+  const repository =
+    registryUrl && !imageName.includes('/')
+      ? `${registryUrl.replace(/\/$/, '')}/${imageName}`
+      : imageName;
+
+  return {
+    imageName,
+    imageTag,
+    fullImage: `${repository}:${imageTag}`,
+    latestImage: `${repository}:latest`,
+    legacyLatestImage: `${config.project}:latest`,
+  };
+}
+
+/**
+ * Runtime-only Dockerfile for frontend artifacts that already contain built static output.
+ * Used when deploy must build from an artifact (no source / no package-lock).
+ * @param {string} [buildOutput]
+ * @returns {string}
+ */
+export function generateFrontendRuntimeDockerfile(buildOutput = 'dist') {
+  const output = buildOutput.replace(/^\/+|\/+$/g, '') || 'dist';
+  return `# Generated by DeployHub for artifact deploy (pre-built static output)
+FROM nginx:alpine
+COPY ${output}/ /usr/share/nginx/html/
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+}
+
+/**
+ * @param {string} jarRelativePath e.g. target/app.jar
+ * @param {number} [port]
+ */
+export function generateSpringRuntimeDockerfile(jarRelativePath, port = 8080) {
+  return `# Generated by DeployHub for artifact deploy (pre-built JAR)
+FROM eclipse-temurin:17-jre-alpine
+WORKDIR /app
+COPY ${jarRelativePath} app.jar
+EXPOSE ${port}
+CMD ["java", "-jar", "app.jar"]
+`;
+}
+
+/**
+ * @param {string} binaryRelativePath e.g. bin/app
+ * @param {number} [port]
+ */
+export function generateGoRuntimeDockerfile(binaryRelativePath, port = 8080) {
+  return `# Generated by DeployHub for artifact deploy (pre-built Go binary)
+FROM alpine:3.19
+WORKDIR /app
+RUN apk add --no-cache ca-certificates
+COPY ${binaryRelativePath} ./app
+RUN chmod +x ./app
+EXPOSE ${port}
+CMD ["./app"]
+`;
+}
+
+/**
+ * @param {string} publishDir
+ * @param {number} [port]
+ */
+export function generateDotnetRuntimeDockerfile(publishDir = 'publish', port = 5000) {
+  const dir = publishDir.replace(/^\/+|\/+$/g, '') || 'publish';
+  return `# Generated by DeployHub for artifact deploy (pre-built .NET publish output)
+FROM mcr.microsoft.com/dotnet/aspnet:8.0
+WORKDIR /app
+COPY ${dir}/ .
+EXPOSE ${port}
+ENV ASPNETCORE_URLS=http://+:${port}
+CMD ["dotnet", "App.dll"]
+`;
+}
+
+/**
+ * @param {string} framework
+ * @returns {boolean}
+ */
+export function isFrontendStaticFramework(framework) {
+  return ['react', 'vue', 'angular', 'svelte', 'astro', 'vanilla'].includes(framework || '');
+}
+
+/**
+ * Node-style backends whose generated Dockerfiles run npm ci and need a lockfile.
+ * @param {string} framework
+ */
+export function isNodeBackendFramework(framework) {
+  return ['express', 'nestjs', 'fastify', 'koa', 'nextjs'].includes(framework || '');
+}
+
+/**
+ * Interpreted backends that install deps at image-build time (pip/composer/bundle/npm).
+ * Their artifacts lack vendor/venv/node_modules, so standalone artifact rebuild is unsupported.
+ * @param {string} framework
+ */
+export function isInterpretedBackendFramework(framework) {
+  return [
+    ...['express', 'nestjs', 'fastify', 'koa', 'nextjs'],
+    'fastapi',
+    'django',
+    'flask',
+    'laravel',
+    'symfony',
+    'rails',
+  ].includes(framework || '');
+}
+
+/**
+ * Human-readable dependency gap for interpreted backend artifact rebuilds.
+ * @param {string} framework
+ * @returns {{ ecosystem: string, missing: string, installCmd: string }}
+ */
+export function describeInterpretedBackendGap(framework) {
+  if (isNodeBackendFramework(framework)) {
+    return {
+      ecosystem: 'Node',
+      missing: 'package-lock.json / node_modules',
+      installCmd: 'npm ci',
+    };
+  }
+  if (['fastapi', 'django', 'flask'].includes(framework)) {
+    return {
+      ecosystem: 'Python',
+      missing: 'a pre-installed virtualenv / site-packages (artifacts only ship requirements.txt + source)',
+      installCmd: 'pip install',
+    };
+  }
+  if (['laravel', 'symfony'].includes(framework)) {
+    return {
+      ecosystem: 'PHP',
+      missing: 'vendor/ (Composer dependencies are not packaged into the artifact)',
+      installCmd: 'composer install',
+    };
+  }
+  if (framework === 'rails') {
+    return {
+      ecosystem: 'Ruby',
+      missing: 'vendor/bundle / installed gems (artifacts only ship Gemfile + lock)',
+      installCmd: 'bundle install',
+    };
+  }
+  return {
+    ecosystem: 'backend',
+    missing: 'installed dependencies (not packaged into the artifact)',
+    installCmd: 'dependency install',
+  };
+}
+
+export default {
+  resolveDockerImageRef,
+  generateFrontendRuntimeDockerfile,
+  generateSpringRuntimeDockerfile,
+  generateGoRuntimeDockerfile,
+  generateDotnetRuntimeDockerfile,
+  isFrontendStaticFramework,
+  isNodeBackendFramework,
+  isInterpretedBackendFramework,
+  describeInterpretedBackendGap,
+};

package/src/utils/dockerfile.js

@@ -5,6 +5,9 @@
 const GENERATED_HEADER =
   '# Generated by DeployHub — review exposed port and start command before deploying.\n';
 
+const DOCKERIGNORE_HEADER =
+  '# Generated by DeployHub — safe to edit. Existing .dockerignore is never overwritten.\n';
+
 /**
  * @param {string} projectName
  * @returns {string}
@@ -41,6 +44,100 @@ export function resolveDockerSettings(config) {
   };
 }
 
+/**
+ * Generate a .dockerignore matching the Dockerfile language/framework.
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @returns {string}
+ */
+export function generateDockerignore(config) {
+  const settings = resolveDockerSettings(config);
+  const { framework, buildOutput, projectType } = settings;
+
+  /** @type {string[]} */
+  const lines = [DOCKERIGNORE_HEADER.trimEnd(), ''];
+
+  const common = [
+    '.git',
+    '.gitignore',
+    '.env',
+    '.env.*',
+    '!.env.example',
+    'artifact',
+    '.deployhub',
+    'coverage',
+    '*.md',
+    '!README.md',
+    '.github',
+    '.vscode',
+    '.idea',
+    'deployhub.config.json',
+  ];
+  lines.push(...common, '');
+
+  const frontendStatic = ['react', 'vue', 'angular', 'svelte', 'astro', 'vanilla'];
+  const nodeFrameworks = [
+    ...frontendStatic,
+    'nextjs',
+    'nestjs',
+    'express',
+    'fastify',
+    'koa',
+  ];
+  const pythonFrameworks = ['fastapi', 'django', 'flask'];
+  const phpFrameworks = ['laravel', 'symfony'];
+
+  if (nodeFrameworks.includes(framework) || !framework) {
+    lines.push('node_modules', 'npm-debug.log*', 'yarn-error.log*', '.npm', '');
+    // Source Dockerfile rebuilds inside the image — exclude local build output from context
+    if (
+      frontendStatic.includes(framework) ||
+      framework === 'nextjs' ||
+      framework === 'nestjs' ||
+      (projectType === 'frontend' && buildOutput && buildOutput !== '.')
+    ) {
+      const out = buildOutput || 'dist';
+      if (out !== '.') lines.push(out);
+      if (framework === 'nextjs') lines.push('.next');
+      if (out !== 'build') lines.push('build');
+      lines.push('');
+    }
+  }
+
+  if (pythonFrameworks.includes(framework)) {
+    lines.push(
+      '__pycache__',
+      '*.py[cod]',
+      '.venv',
+      'venv',
+      '.pytest_cache',
+      '*.egg-info',
+      ''
+    );
+  }
+
+  if (phpFrameworks.includes(framework)) {
+    lines.push('vendor', '');
+  }
+
+  if (framework === 'spring') {
+    lines.push('target', '.gradle', 'build', '');
+  }
+
+  if (framework === 'go') {
+    lines.push('bin', '');
+  }
+
+  if (framework === 'dotnet') {
+    lines.push('bin', 'obj', '');
+  }
+
+  if (framework === 'rails') {
+    lines.push('tmp', 'log', 'vendor/bundle', '');
+  }
+
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}
+
 /**
  * @param {import('../core/config.js').DeployHubConfig} config
  * @returns {string}
@@ -480,6 +577,7 @@ export function getDockerfileFrameworkLabel(framework) {
 
 export default {
   generateDockerfile,
+  generateDockerignore,
   resolveDockerSettings,
   sanitizeDockerProjectName,
   getDockerfileFrameworkLabel,

package/src/utils/scaffold.js

@@ -3,6 +3,7 @@ import path from 'path';
 import chalk from 'chalk';
 import {
   generateDockerfile,
+  generateDockerignore,
   getDockerfileFrameworkLabel,
   resolveDockerSettings,
 } from './dockerfile.js';
@@ -48,11 +49,11 @@ export function needsKubernetesManifests(
  * @param {string} cwd
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {{ silent?: boolean }} [options]
- * @returns {Promise<{ generated: boolean, framework?: string }>}
+ * @returns {Promise<{ generated: boolean }>}
  */
-export async function ensureDockerfile(cwd, config, options = {}) {
-  const dockerfilePath = path.join(cwd, 'Dockerfile');
-  if (await fs.pathExists(dockerfilePath)) {
+export async function ensureDockerignore(cwd, config, options = {}) {
+  const dockerignorePath = path.join(cwd, '.dockerignore');
+  if (await fs.pathExists(dockerignorePath)) {
     return { generated: false };
   }
 
@@ -60,20 +61,56 @@ export async function ensureDockerfile(cwd, config, options = {}) {
     return { generated: false };
   }
 
-  const settings = resolveDockerSettings(config);
-  const content = generateDockerfile(config);
-  await fs.writeFile(dockerfilePath, content);
+  await fs.writeFile(dockerignorePath, generateDockerignore(config));
 
   if (!options.silent) {
-    const label = getDockerfileFrameworkLabel(settings.framework);
     console.log(
       chalk.yellow(
-        `No Dockerfile found — generated a starter Dockerfile at ./Dockerfile based on your detected ${label}. Review it before deploying, especially the exposed port and start command.`
+        'No .dockerignore found — generated one at ./.dockerignore to keep node_modules and build caches out of the Docker build context.'
       )
     );
   }
 
-  return { generated: true, framework: settings.framework };
+  return { generated: true };
+}
+
+/**
+ * @param {string} cwd
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {{ silent?: boolean }} [options]
+ * @returns {Promise<{ generated: boolean, framework?: string, dockerignoreGenerated?: boolean }>}
+ */
+export async function ensureDockerfile(cwd, config, options = {}) {
+  const dockerfilePath = path.join(cwd, 'Dockerfile');
+  let generated = false;
+  /** @type {string|undefined} */
+  let framework;
+
+  if (!(await fs.pathExists(dockerfilePath)) && needsDockerfile(config)) {
+    const settings = resolveDockerSettings(config);
+    const content = generateDockerfile(config);
+    await fs.writeFile(dockerfilePath, content);
+    generated = true;
+    framework = settings.framework;
+
+    if (!options.silent) {
+      const label = getDockerfileFrameworkLabel(settings.framework);
+      console.log(
+        chalk.yellow(
+          `No Dockerfile found — generated a starter Dockerfile at ./Dockerfile based on your detected ${label}. Review it before deploying, especially the exposed port and start command.`
+        )
+      );
+    }
+  }
+
+  // Always pair Dockerfile generation path with .dockerignore (never overwrite existing)
+  const dockerignoreResult = await ensureDockerignore(cwd, config, options);
+
+  return {
+    generated,
+    framework,
+    dockerignoreGenerated: dockerignoreResult.generated,
+  };
 }
 
 /**
@@ -133,6 +170,7 @@ export async function ensureDeployScaffold(
   const k8sResult = await ensureKubernetesManifests(cwd, config, environments, options);
   return {
     dockerfile: dockerResult.generated,
+    dockerignore: Boolean(dockerResult.dockerignoreGenerated),
     kubernetes: k8sResult.generated,
   };
 }
@@ -183,6 +221,7 @@ export async function copyDeployAssetsToArtifactDir(stagingDir, artifactDir) {
 
 export default {
   ensureDockerfile,
+  ensureDockerignore,
   ensureKubernetesManifests,
   ensureDeployScaffold,
   needsDockerfile,