Docker Multi-Stage Builds

A typical Node.js app image can drop from 1.2 GB to 80 MB with multi-stage builds and the right base image.

# Everything in one image
FROM node:20
WORKDIR /app
COPY . .
RUN npm ci && npm run build
EXPOSE 3000
CMD ["node", "dist/server.js"]
# Result: ~1.1 GB image with
# build tools, node_modules, src...

# Stage 1: build
FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: production
FROM node:20-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
CMD ["node", "dist/server.js"]
# Result: ~180 MB image, production only

Multi-stage builds let you use multiple FROM statements — only the final stage becomes the shipped image.

Each FROM instruction starts a new build stage. Name stages with AS for clarity.

# Named stages make Dockerfiles readable and maintainable
FROM golang:1.22 AS builder        # Stage 0 - named "builder"
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM alpine:3.19 AS certs          # Stage 1 - named "certs"
RUN apk add --no-cache ca-certificates

FROM scratch AS runtime             # Stage 2 - named "runtime" (final)
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

COPY --from is the bridge between stages — selectively copy only what you need.

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json .
COPY --from=deps /app/node_modules ./node_modules

# Grab a binary from another image
COPY --from=busybox:uclibc /bin/sh /bin/sh
COPY --from=redis:7 /usr/local/bin/redis-cli /usr/local/bin/

Use --target to stop at a specific stage — one Dockerfile, multiple outputs.

FROM node:20 AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM base AS dev                   # docker build --target dev
COPY . .
CMD ["npm", "run", "dev"]          # Hot reload, debug tools

FROM base AS test                  # docker build --target test
COPY . .
RUN npm run lint && npm test

FROM base AS build
COPY . .
RUN npm run build

FROM node:20-slim AS prod          # docker build --target prod (default)
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
CMD ["node", "dist/server.js"]

Go compiles to a static binary — the ideal multi-stage candidate. Final image can be scratch.

FROM golang:1.22-alpine AS builder
RUN apk add --no-cache git ca-certificates
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-s -w" -o /bin/server ./cmd/server

FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

FROM eclipse-temurin:21-jre-alpine
COPY --from=build /app/target/*.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]
# JDK build: ~700MB -> JRE runtime: ~190MB

FROM python:3.12 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir \
    -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD ["python", "app.py"]
# Full Python: ~1GB -> Slim: ~150MB

Tip: For Java, use jlink to create a custom JRE and shrink the runtime further.

The final base image determines your security posture and image size.

Docker caches each layer. Order matters — put things that change least at the top.

# BAD: COPY . . invalidates everything
FROM node:20
WORKDIR /app
COPY . .                # Any change busts cache
RUN npm ci              # Always re-runs
RUN npm run build       # Always re-runs

# GOOD: deps cached until lockfile changes
FROM node:20
WORKDIR /app
COPY package*.json ./   # Changes rarely
RUN npm ci              # Cached if lock unchanged
COPY . .                # Only source changes
RUN npm run build       # Rebuilds only app

Use ARG to parameterize builds and select stages dynamically.

# Global ARG (available to all FROM instructions)
ARG GO_VERSION=1.22
ARG TARGET_ENV=prod

FROM golang:${GO_VERSION} AS builder
ARG TARGET_ENV
WORKDIR /src
COPY . .
RUN if [ "$TARGET_ENV" = "dev" ]; then \
      go build -gcflags="all=-N -l" -o /app .; \
    else \
      go build -ldflags="-s -w" -o /app .; \
    fi

FROM alpine:3.19 AS dev
COPY --from=builder /app /app
RUN apk add --no-cache curl jq  # debug tools
CMD ["/app"]

FROM scratch AS prod
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

docker build --build-arg TARGET_ENV=dev \
             --target dev -t myapp:dev .

docker build --build-arg GO_VERSION=1.21 \
             -t myapp:go1.21 .

Enable with DOCKER_BUILDKIT=1 or use docker buildx. BuildKit unlocks powerful caching and secret handling.

# syntax=docker/dockerfile:1
FROM golang:1.22 AS builder
WORKDIR /src
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -o /app .

# Python pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# syntax=docker/dockerfile:1
FROM node:20 AS build
WORKDIR /app
COPY . .
# Secret never stored in image layers
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci

# Build command:
# docker build --secret id=npmrc,src=.npmrc .

Real-world impact of multi-stage builds across languages:

A good .dockerignore is the first line of defence — it shrinks your build context before any stage runs.

# Version control
.git
.gitignore

# Dependencies (rebuilt in image)
node_modules
vendor
__pycache__
*.pyc

# Build outputs (rebuilt in image)
dist
build
target

# IDE & editor
.vscode
.idea
*.swp

# Environment & secrets
.env
.env.*
*.pem
*.key

# Docker files (avoid recursion)
Dockerfile*
docker-compose*
.dockerignore

# Documentation & CI
README.md
docs/
.github/
.gitlab-ci.yml

Multi-stage builds simplify CI pipelines — the Dockerfile is the build script.

name: Build & Push
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          context: .
          target: prod
          push: true
          tags: ghcr.io/org/app:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

# Run tests in Docker, then build prod
jobs:
  test:
    steps:
      - run: |
          docker build --target test \
            -t myapp:test .
          docker run myapp:test

  deploy:
    needs: test
    steps:
      - run: |
          docker build --target prod \
            -t myapp:prod .
          docker push myapp:prod

When builds fail, you need to inspect what happened inside a stage.

# Stop at the builder stage
docker build --target builder -t debug:builder .

# Shell into it
docker run -it debug:builder /bin/sh

# List what was built
docker run debug:builder ls -la /app/dist

# Check file sizes
docker run debug:builder du -sh /app/*

# See layer sizes and commands
docker history myapp:latest

# Dive tool: interactive layer explorer
dive myapp:latest

# Export filesystem for inspection
docker create --name tmp myapp:latest
docker export tmp | tar tf - | head -50
docker rm tmp

A complete, production-ready Node.js Dockerfile using every technique covered:

# syntax=docker/dockerfile:1
ARG NODE_VERSION=20

# --- Stage 1: Dependencies ---
FROM node:${NODE_VERSION}-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

# --- Stage 2: Build ---
FROM node:${NODE_VERSION}-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev

# --- Stage 3: Production ---
FROM gcr.io/distroless/nodejs${NODE_VERSION}-debian12
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
ENV NODE_ENV=production
EXPOSE 3000
USER nonroot:nonroot
CMD ["dist/server.js"]

Thank you — questions?