IHOR.DEVKNOWLEDGE_BASE
MENU

~/blog / Delivery / production-docker-images-for-node-js-apps.md

// guide · 4 min read

Production Docker Images for Node.js Apps

Build Node.js production images with separate build and runtime stages, locked dependencies, a controlled context, non-root execution, and an inspected runtime artifact.

Quick answer

Separate dependency installation and compilation from the runtime image. Ship only the built application and runtime dependencies, run as a non-root user, keep credentials out of image layers, and inspect the image as the deployed artifact. A smaller image is useful, but correctness includes native dependency compatibility, required files, startup behavior, and graceful termination. Docker packaging does not make process memory or the container filesystem durable business storage.

Practical implementation steps

1. Define the runtime entrypoint

A plain TypeScript server may emit dist/server.js. Next.js standalone output instead produces a traced server and selected dependencies; public and .next/static are not copied automatically. Name the expected artifact before writing COPY rules. Check runtime-loaded templates, certificates, dictionaries, native binaries, and content files rather than assuming the JavaScript entrypoint is sufficient. This portfolio is a Next.js app, so a generic dist example is not its existing deployment recipe.

2. Control the build context and dependencies

Exclude local node_modules, prior output, VCS data, logs, and secret environment files through .dockerignore. Copy package manifests before source to support useful layer reuse, then install from the lockfile. Build tools belong in the build stage; production dependencies belong in the runtime dependency stage. If lifecycle scripts need generated files, adjust that process explicitly instead of assuming every package supports the same installation order.

3. Keep builder and runner compatible

Use compatible OS and runtime families when native packages are compiled or copied. Switching from a glibc builder to a musl runtime can break otherwise valid JavaScript packages with native components. Choose a supported base version, review updates, and pin a digest when immutable provenance is required. Digest pinning also means an update process is necessary; it does not automatically pick up a patched base image.

4. Inspect the runtime behavior

Start the built image without source mounts and verify its required route, assets, permissions, and configuration. Inject server secrets at runtime through the platform’s secret mechanism rather than build arguments or copied .env files. Use an exec-form command so the intended process receives signals, then verify the application drains or safely interrupts work. A non-root user still needs explicit access to any writable directory it actually uses.

Implementation example

This illustrative Dockerfile assumes a locked Node.js application whose build emits dist/server.js and whose production dependencies install independently. Both stages use the same base family to reduce native compatibility surprises. It is not a tested Dockerfile for this repository. Supply the .dockerignore before building, and adapt assets and lifecycle scripts to the actual app rather than copying the artifact names blindly.

FROM node:22-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-bookworm-slim AS production-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22-bookworm-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY --from=production-deps --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
COPY --from=build --chown=node:node /app/package.json ./package.json
USER node
CMD ["node", "dist/server.js"]
# Run in the illustrative application after creating its Dockerfile.
docker build --tag node-service:review .
docker run --rm --init --publish 3000:3000 node-service:review

Tradeoffs and alternatives

A slim base retains familiar tooling and libraries; a more minimal runtime can reduce unused surface while making debugging and native support less convenient. Framework tracing can reduce copied dependencies but requires verifying runtime-loaded files. A managed build service can handle packaging, yet the team still needs to know which artifact, runtime, and configuration it deploys. Choose minimum size after correctness, rather than deleting files until startup fails.

Common mistakes

Do not copy a development node_modules tree from the host, bake secrets into layers, use a root runtime merely for convenience, or assume EXPOSE publishes a port. Do not run the build again when the container starts. Avoid a successful startup check that never requests a real route: missing runtime assets or permissions can remain hidden until a visitor exercises the application.

Production checklist

  • Runtime files are identified and inspected in the built image.
  • Build context excludes secrets and stale local output.
  • Native dependencies match the runner environment.
  • Non-root execution and writable paths are deliberate.
  • Startup, route delivery, and termination are verified.

FAQ

Does multi-stage building remove secrets from every stage?

No. Avoid adding them to the build in the first place, use supported secret mounts when needed, and inspect exported artifacts and logs. A final-stage omission alone is not a complete secret policy.

Is this generic Dockerfile suitable for Next.js?

Not unchanged. Use the actual Next.js deployment mode and traced or installed runtime output, including its required public and static assets.

Next step

Build one runtime image and exercise it without source mounts or development dependencies. Verify configuration, asset reads, and shutdown before publishing it. Record the image digest and update procedure so the release is reproducible and patchable.

Primary sources

Ihor Kharchyshyn

Independent full-stack product engineer writing source-backed implementation guides for browser extensions and modern web products.

Need this implemented in a real product?

One connected implementation across the interface, application logic, APIs, and data layer.