Dockerizing a NestJS App for Production

A Dockerfile that works locally is not automatically ready for production. Production containers need small images, deterministic builds, secure defaults, clean environment handling, and health checks that orchestration can trust.

This guide focuses on a practical NestJS deployment path.

Use a multi-stage Dockerfile

Multi-stage builds keep development tooling out of the final image. The builder stage installs dependencies and compiles the app. The runtime stage carries only what the app needs to start.

FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/main.js"]

Keep the final image boring. It should start the compiled server and nothing else.

Keep configuration out of the image

Do not bake secrets or environment-specific URLs into the image. The same image should run in staging and production with different environment variables.

For NestJS, validate configuration at startup so missing values fail fast:

ConfigModule.forRoot({
  isGlobal: true,
  validationSchema: Joi.object({
    DATABASE_URL: Joi.string().required(),
    REDIS_URL: Joi.string().optional(),
    PORT: Joi.number().default(3000),
  }),
});

This makes deployment failures visible immediately instead of surfacing as random runtime errors later.

Add health checks before orchestration

Kubernetes, ECS, Fly.io, Render, and many other platforms rely on health signals. A good NestJS app should expose at least a lightweight readiness endpoint.

@Controller("health")
export class HealthController {
  @Get()
  check() {
    return { status: "ok" };
  }
}

For production, include checks for critical dependencies such as the database or queue. Keep liveness checks lightweight so the platform does not restart healthy instances during a slow dependency call.

Run as a non-root user

Containers should not run as root by default. Node Alpine images include a node user that works for most apps.

USER node

If the app needs writable directories, create and assign ownership during the image build. Avoid broad permissions like chmod 777.

Build once promote the same image

The safest pipeline builds one image, tags it with a commit SHA, scans it, and promotes that exact image across environments.

Avoid rebuilding separately for staging and production. Rebuilds create subtle differences in dependencies, build output, or base image versions. Promotion keeps rollback simple because every deployment points to a known immutable artifact.

Deployment readiness checklist

Before deploying a NestJS container, confirm:

• npm ci is used for reproducible installs.
• The final image excludes dev dependencies.
• Secrets come from runtime environment variables.
• The app validates required configuration at startup.
• Health endpoints exist and are wired into the platform.
• Logs go to stdout and stderr.
• The container runs as a non-root user.
• CI tags the image with a commit SHA.

Container quality is easier when the API architecture is already clean. Start with NestJS Modular Architecture: Building Production APIs That Scale, then make sure public pages around the product are discoverable with Next.js SEO Checklist for the App Router.