Why use a multi-stage build?

A multi-stage build compiles your app and installs dev dependencies in a builder stage, then copies only the runtime artifacts and production dependencies into a slim final image. This keeps the shipped image small and free of build tooling and source.

Why run as the non-root node user?

Official Node images include a built-in non-root node user. Running as USER node means a container escape or app compromise does not grant root inside the container, which is a baseline container-security best practice.

What does the HEALTHCHECK do?

The HEALTHCHECK periodically requests your /health endpoint from inside the container and marks it unhealthy after repeated failures. Orchestrators like Docker Swarm and many platforms use this to restart or stop routing traffic to broken containers.

Do I still need a .dockerignore?

Yes. Without one, Docker copies node_modules, .git and local files into the build context, slowing builds and risking secret leakage. Add at least node_modules, .git and .env to a .dockerignore next to the Dockerfile.

Will this work for Next.js?

Yes, with the build step enabled and an appropriate start command such as node server.js for standalone output, or next start. Adjust the copied paths if you use Next.js standalone output, which emits a .next/standalone folder.

Dockerfile Builder for Node.js

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

A builder for a production-ready, multi-stage Dockerfile for Node.js apps — Express, NestJS, Fastify or Next.js. Choose your Node version, package manager and port, and the tool emits an image that compiles in a builder stage and ships only the runtime in a slim final stage, running as a non-root user.

How it works

The generated Dockerfile uses three stages. The builder stage installs all dependencies (npm ci, yarn install --frozen-lockfile or pnpm install --frozen-lockfile), copies your source and runs the build script if you have one. A separate deps stage installs production-only dependencies so dev tooling never reaches the final image. The runner stage copies the production node_modules and the compiled dist/ output, sets NODE_ENV=production, switches to the built-in non-root node user, exposes your port and defines the start command.

Health checks and security

When enabled, the HEALTHCHECK instruction calls your /health endpoint with Node’s built-in fetch, exiting non-zero on failure so the orchestrator can restart the container. Running as USER node is a baseline hardening step: it ensures a compromised process does not have root inside the container.

Tips

Always add a .dockerignore next to the Dockerfile. A minimal one looks like:

node_modules
.git
.env
dist
npm-debug.log

This keeps the build context small and prevents secrets and local artifacts from being baked into the image. For Next.js standalone output, point the start command at node server.js and copy the .next/standalone and .next/static folders instead of dist/.