Docker NestJS Multi-Stage Build Production Optimization

I shipped a 2GB Docker image to production once. It pulled so slowly that the orchestrator's health check timed out before the container even started, which is a fun way to learn what your health-check timeout is set to. A multi-stage build got it to 180MB. Same application. Roughly one-eleventh the size, and deploys that finish before you have finished your coffee.

That 2GB image is why this post exists. A docker nestjs production multi-stage build optimization is not optional once you deploy more than one instance — the image size directly determines deploy speed, storage cost, and attack surface. The naive Dockerfile that copies everything and installs all dependencies produces images around 1GB-1.2GB. The multi-stage Alpine approach described here produces images under 200MB with better security and faster builds.

Why a Single-Stage Dockerfile Is a Liability

Most tutorials stop here:

1FROM node:20
2WORKDIR /app
3COPY . .
4RUN npm install
5RUN npm run build
6EXPOSE 3000
7CMD ["node", "dist/main"]

This image is over 1GB. It contains the full Node.js runtime with build tools, every dev dependency (TypeScript, ESLint, test frameworks), your entire source code including tests and config files, and the npm cache from the install step. Every unnecessary megabyte is attack surface. Every unnecessary binary is a potential CVE waiting to be exploited. A proper docker nestjs production multi-stage build optimization eliminates this entire class of risk by ensuring only the runtime essentials ship to production.

The fix is a multi-stage build. The concept is straightforward — use one stage to build and a separate stage to run, copying only the compiled output into the final image. NestJS's official documentation covers setting up database integrations for production, but the Dockerfile itself is the deployment foundation those integrations depend on.

Stage 1: Dependencies — Install Only What Is Needed

The first stage installs all dependencies, including dev dependencies needed for compilation. We copy only the package files first to exploit Docker layer caching — if dependencies do not change, this layer is cached and never rebuilt. This docker nestjs production multi-stage build optimization starts by minimizing what each layer contributes to the final image.

1FROM node:20-alpine AS deps
2WORKDIR /app
3COPY package.json package-lock.json ./
4RUN npm ci

The key detail: npm ci instead of npm install. CI installs exactly what the lockfile specifies, fails if the lockfile is out of date, and runs faster than npm install. This is the Docker Node.js best practice recommended for production builds.

Stage 2: Build — Compile TypeScript

The second stage copies the installed node_modules from the deps stage, copies the source code, and compiles TypeScript. After the build, we prune dev dependencies to reduce the size of what gets carried forward.

1FROM node:20-alpine AS build
2WORKDIR /app
3COPY --from=deps /app/node_modules ./node_modules
4COPY . .
5RUN npm run build
6RUN npm prune --production

npm prune --production removes devDependencies from node_modules after the build completes. The source code and TypeScript compiler that produced the output stay in this stage permanently — they are never copied to the final image.

Stage 3: Production — Copy Only the Compiled Output

The third stage starts fresh from a minimal Alpine image and copies only three things: the compiled JavaScript, the production dependencies, and the package.json (for the start script). Nothing else.

1FROM node:20-alpine AS production
2RUN addgroup -S app && adduser -S app -G app
3WORKDIR /app
4COPY --from=build /app/dist ./dist
5COPY --from=build /app/node_modules ./node_modules
6COPY --from=build /app/package.json ./
7USER app
8EXPOSE 3000
9HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
10  CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok?0:1)).catch(() => process.exit(1))"
11ENV NODE_ENV=production
12CMD ["node", "dist/main"]

The image size difference: single-stage builds produce roughly 1.2GB. This three-stage build produces around 180MB — an 85% reduction. This docker nestjs production multi-stage build optimization means over a gigabyte of build tools, source code, and dev dependencies never reach the registry or the production server.

Running as Non-Root User for Security

The addgroup and adduser commands in the production stage create a non-root user. The USER app directive switches to that user before running the application. This is not optional for production — running as root inside a container means any application vulnerability gives an attacker root access.

The NestJS application needs no elevated permissions at runtime. It does not need to bind to privileged ports (the container maps whatever port you specify), it does not need to install packages, and it does not need to write to the filesystem beyond the working directory. If your application writes logs to disk, ensure the directory is owned by the app user. This is a standard part of any docker nestjs production multi-stage build optimization that takes security seriously.

Environment Variable Handling in Docker

Environment variables pass into the container at runtime, not at build time. This is a common mistake — developers bake environment-specific values into the image, which means a separate image per environment. A docker nestjs production multi-stage build optimization avoids this by keeping the image environment-agnostic and injecting configuration at deploy time.

1# Wrong: env-specific values in the image
2ENV DATABASE_URL=postgres://localhost:5432/myapp
3ENV API_KEY=dev-key-123
4
5# Right: env vars passed at runtime
6# docker run -e DATABASE_URL=... -e API_KEY=... myapp:latest

NestJS's ConfigModule reads from process.env at startup, which is populated by Docker's -e flags or a .env file in development. For multi-environment deployments, keep the Dockerfile clean and use Docker Compose or your orchestrator to inject environment-specific values.

For production, use your deployment platform's secret management — Kubernetes secrets, AWS Secrets Manager, or Docker secrets — rather than plain environment variables. Environment variables in docker inspect output are visible to anyone with access to the host. This is covered in detail in the Docker Compose documentation for local development setups. Each layer of your docker nestjs production multi-stage build optimization should reduce the attack surface, and that includes keeping secrets out of the image layers.

Health Check Configuration

The HEALTHCHECK instruction in the production stage tells Docker how to verify the container is working. The check pings a dedicated /health endpoint every 30 seconds, with a 3-second timeout and a 30-second startup grace period. Including this in your docker nestjs production multi-stage build optimization ensures your orchestrator never routes traffic to a dead container.

Your NestJS application needs to expose this endpoint:

1import { Controller, Get } from '@nestjs/common';
2
3@Controller('health')
4export class HealthController {
5  @Get()
6  check() {
7    return { status: 'ok', timestamp: new Date().toISOString() };
8  }
9}

The endpoint should verify that the application can serve traffic — not just that the process is running. Optionally check database connectivity, Redis connectivity, and any downstream dependencies. A health check that always returns 200 even when the database is down is worse than no health check.

The Dockerfile's start-period is critical for NestJS. The framework takes a moment to bootstrap — NestJS needs to compile modules, connect to the database, and register routes. Without the --start-period, Docker would kill the container during initialization.

Docker Compose for Local Development with PostgreSQL and Redis

Local development should mirror production as closely as possible. Docker Compose ties your NestJS application, PostgreSQL database, and Redis cache together in a single command.

1# docker-compose.yml
2version: "3.8"
3services:
4  app:
5    build:
6      context: .
7      target: production
8    ports:
9      - "3000:3000"
10    environment:
11      - NODE_ENV=production
12      - DATABASE_URL=postgres://postgres:postgres@db:5432/myapp
13      - REDIS_URL=redis://cache:6379
14    depends_on:
15      db:
16        condition: service_healthy
17      cache:
18        condition: service_healthy
19    volumes:
20      - .:/app
21    command: npx nest start --watch
22
23  db:
24    image: postgres:16-alpine
25    environment:
26      POSTGRES_USER: postgres
27      POSTGRES_PASSWORD: postgres
28      POSTGRES_DB: myapp
29    ports:
30      - "5432:5432"
31    volumes:
32      - pgdata:/var/lib/postgresql/data
33    healthcheck:
34      test: ["CMD-SHELL", "pg_isready -U postgres"]
35      interval: 5s
36      timeout: 5s
37      retries: 5
38
39  cache:
40    image: redis:7-alpine
41    ports:
42      - "6379:6379"
43    healthcheck:
44      test: ["CMD", "redis-cli", "ping"]
45      interval: 5s
46      timeout: 5s
47      retries: 5
48
49volumes:
50  pgdata:

Three key decisions in this Compose file. The depends_on with condition: service_healthy ensures the application does not start until the database and cache are actually accepting connections — not just until their containers are running. The named volume pgdata persists database data across container restarts. And the command override in development uses npx nest start --watch instead of the production node dist/main, keeping hot-reloading available locally. This Compose setup complements the docker nestjs production multi-stage build optimization by providing a consistent local environment that matches production.

For monorepo setups using Turborepo, this Compose file fits naturally with the structure described in our SaaS monorepo guide. The .dockerignore file ensures local node_modules and build artifacts do not leak into the build context.

Docker NestJS Production Multi-Stage Build Optimization: Size Comparison

The numbers tell the story. These are real measurements from a typical NestJS SaaS application with Prisma, BullMQ, and 20-30 dependencies:

The deploy time improvement from 45 seconds to 7 seconds matters more than it sounds like. In a rolling update with 5 instances, that is 45 seconds of partial availability versus 35 seconds. For zero-downtime deploys, faster image pulls mean shorter deployment windows and less time in a mixed-version state. This directly impacts the CI/CD pipeline configuration we use for deploying these images.

Complete Dockerfile

Here is the complete production Dockerfile, combining all stages:

1FROM node:20-alpine AS deps
2WORKDIR /app
3COPY package.json package-lock.json ./
4RUN npm ci
5
6FROM node:20-alpine AS build
7WORKDIR /app
8COPY --from=deps /app/node_modules ./node_modules
9COPY . .
10RUN npm run build
11RUN npm prune --production
12
13FROM node:20-alpine AS production
14RUN addgroup -S app && adduser -S app -G app
15WORKDIR /app
16COPY --from=build /app/dist ./dist
17COPY --from=build /app/node_modules ./node_modules
18COPY --from=build /app/package.json ./
19USER app
20EXPOSE 3000
21HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
22  CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok?0:1)).catch(() => process.exit(1))"
23ENV NODE_ENV=production
24CMD ["node", "dist/main"]

This completes the core docker nestjs production multi-stage build optimization. Build it with:

1docker build -t my-nestjs-app:latest .

For development, use the Compose file above. For production, push the image to your registry and reference it in your deployment pipeline. The Docker multi-stage build documentation covers advanced patterns like buildkit caching and parallel stage execution if you need to optimize build times further.

The 2GB image I shipped that one Tuesday taught me the same lesson every team learns eventually: image size is not a cosmetic concern. It is a deploy-speed, security, and cost concern wearing a Dockerfile costume. A multi-stage build that drops your image from 1.2GB to 180MB is, very directly, the difference between a deployment you watch nervously and one you walk away from.

Putting It Together

The docker nestjs production multi-stage build optimization follows a consistent pattern across every NestJS project we ship: a deps stage for reproducible dependency installation, a build stage for TypeScript compilation with dev-dependency pruning, and a production stage that starts from Alpine, adds a non-root user, exposes the port, configures health checks, and runs only the compiled output.

Start with the complete Dockerfile above. It captures every aspect of a docker nestjs production multi-stage build optimization in a single file. Add the .dockerignore file to exclude node_modules, .git, dist, and .env. Wire up Docker Compose for local development with PostgreSQL and Redis. Test the health check endpoint. Measure the image size before and after — the difference will make you wonder why you ever shipped a single-stage build.

Most Docker over-engineering happens when teams try to optimize before they have measured. The image size reduction from single-stage to three-stage is roughly 85%. You do not need BuildKit caching, distroless base images, or layer squashing to get there. You need three FROM instructions and the discipline to copy only what the runtime needs. The rest is just adding bodies to the fire.

If you are setting up a Docker build for a NestJS application and want a second pair of eyes on the Dockerfile before it hits production, get in touch. It is the kind of thing we have been paged about — and we would rather help you get it right the first time.