🏗️ Multi-Stage Docker Builds

Why Multi-Stage?

A traditional single-stage Dockerfile does everything in one image: install dev dependencies, copy the source, build, and run. The result carries the compiler, the source code, the test framework, and every build artifact into production — none of which the running app needs.

# Single-stage: everything ends up in the shipped image
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm install          # includes dev dependencies
COPY . .
RUN npm run build        # build tools stay in the image
CMD ["npm", "start"]

The drawbacks are real: bloated images (slow to pull and deploy), a larger attack surface (every extra package is a potential vulnerability), and source code shipped to production where it doesn't belong.

💡 A useful analogy: Building furniture needs a workshop full of saws, clamps, and sawdust. But you deliver only the finished chair — not the workshop. Multi-stage builds are the delivery truck that carries the chair and leaves the tools behind.

The Basics & Syntax

A multi-stage Dockerfile has multiple FROM statements. Each FROM starts a fresh stage. Name a stage with AS <name>, then pull artifacts forward with COPY --from=<name>. Only the last stage becomes the final image; earlier stages are discarded.

# --- Stage 1: build ---
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci                 # all deps, including dev
COPY . .
RUN npm run build          # produces /app/dist

# --- Stage 2: production runtime ---
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev      # runtime deps only
# Pull ONLY the built output from the builder stage
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/server.js"]

You can have as many stages as you need, but most real builds use two to four: build, optional test, and the lean production runtime.

Use Cases by App Type

Compiled languages (Go, Rust)

The classic win: a Go toolchain image is ~800 MB, but the compiled static binary is a few MB. Build in the full image, copy just the binary into a minimal base.

# Build stage
FROM golang:1.23 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o app .

# Final stage — tiny
FROM alpine:3.20
RUN apk --no-cache add ca-certificates
COPY --from=builder /app/app /app
CMD ["/app"]

Frontend apps (React, Vue)

Build the static bundle with Node, then serve it from a tiny web server like nginx. The Node runtime never ships.

# Build stage
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build           # produces /app/dist (Vite) or /app/build (CRA)

# Production stage — static files served by nginx
FROM nginx:1.27-alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Full-stack apps

Use several build stages — one per component — then assemble the outputs in a single runtime stage.

# Frontend build
FROM node:20 AS frontend-builder
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ .
RUN npm run build

# Backend build
FROM node:20 AS backend-builder
WORKDIR /app/backend
COPY backend/package*.json ./
RUN npm ci
COPY backend/ .
RUN npm run build

# Final runtime
FROM node:20-alpine
WORKDIR /app
COPY backend/package*.json ./
RUN npm ci --omit=dev
COPY --from=backend-builder /app/backend/dist ./dist
COPY --from=frontend-builder /app/frontend/dist ./public
EXPOSE 3000
CMD ["node", "dist/server.js"]

Advanced Techniques

Targeting a specific stage

Build up to a named stage with --target. Perfect for CI: run tests in a test stage, and only build the production image if they pass.

# Build only up to the test stage (for CI)
docker build --target test -t myapp:test .

# Build the full production image
docker build -t myapp:1.4.0 .

BuildKit and parallelism

BuildKit is the default builder in modern Docker. Stages that don't depend on each other build in parallel, and it caches more intelligently. You rarely need to enable it explicitly anymore, but you can force it:

# BuildKit is default in Docker 23+, but you can be explicit
DOCKER_BUILDKIT=1 docker build -t myapp .

# BuildKit cache mount: keep the npm cache across builds
# (inside the Dockerfile)
# RUN --mount=type=cache,target=/root/.npm npm ci

Multi-platform builds

Build one image that runs on both Intel and ARM (think Apple Silicon and Graviton servers) with buildx:

# Build and push for two architectures at once
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:1.4.0 \
  --push .

Copying from external images

COPY --from can also pull from a published image, not just a build stage — handy for grabbing a config file or a prebuilt tool:

# Pull a file straight from an official image
COPY --from=nginx:1.27 /etc/nginx/nginx.conf /nginx.conf

Optimizing Builds

Layer caching: order matters

Copy dependency manifests and install before copying source code. Since source changes far more often than dependencies, this keeps the expensive install layer cached across rebuilds.

# BEFORE: any file change busts the npm cache
COPY . .
RUN npm install

# AFTER: deps cached separately from source
COPY package*.json ./
RUN npm ci
COPY . .

Right base image per stage

Different stages have different needs. Use a full SDK to build, a test image to test, and the smallest possible runtime to ship.

Hands-on Exercise

# Single-stage Dockerfile
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

# --- Build stage ---
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# --- Production stage ---
FROM node:20-alpine

RUN addgroup -g 1001 appuser \
    && adduser -u 1001 -G appuser -s /bin/sh -D appuser

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

COPY --from=builder --chown=appuser:appuser /app/build ./build
COPY --from=builder --chown=appuser:appuser /app/server ./server

USER appuser
ENV NODE_ENV=production
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "server/index.js"]

Best Practices

Summary & Quiz

📚 Further Reading

• Docker — Multi-Stage Builds
• Docker — BuildKit
• Distroless Base Images

🚀 What's Next?

Now that your images are lean, we'll orchestrate several of them together with Docker Compose for production — health checks, networks, secrets, and scaling.