Docker Multi-Stage Builds Explained

Multi-stage builds create smaller, more secure Docker images. Here's how to use them effectively.

Why Multi-Stage Builds#

Single-stage problems:
- Build tools in production image
- Large image sizes
- Security vulnerabilities from dev dependencies
- Slow deployments

Multi-stage benefits:
- Separate build and runtime
- Smaller final images
- No build tools in production
- Better security posture

Basic Multi-Stage Build#

# Stage 1: Build
FROM node:20-alpine AS builder

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Build application
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:20-alpine AS production

WORKDIR /app

# Copy only production dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy built files from builder
COPY --from=builder /app/dist ./dist

# Run as non-root user
USER node

EXPOSE 3000
CMD ["node", "dist/index.js"]

TypeScript Application#

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
COPY tsconfig.json ./
RUN npm ci

COPY src ./src
RUN npm run build

# Production stage
FROM node:20-alpine

WORKDIR /app

# Install production dependencies only
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Copy compiled JavaScript
COPY --from=builder /app/dist ./dist

USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]

Next.js Application#

# Dependencies stage
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Builder stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

# Production stage
FROM node:20-alpine AS runner
WORKDIR /app

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000

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

Go Application#

# Build stage
FROM golang:1.21-alpine AS builder

WORKDIR /app

# Download dependencies
COPY go.mod go.sum ./
RUN go mod download

# Build binary
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /app/server ./cmd/server

# Production stage - minimal image
FROM scratch

COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080
ENTRYPOINT ["/server"]

Python Application#

# Build stage
FROM python:3.11-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Create virtual environment
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Production stage
FROM python:3.11-slim

WORKDIR /app

# Copy virtual environment
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copy application
COPY . .

USER nobody
EXPOSE 8000
CMD ["gunicorn", "app:app", "-b", "0.0.0.0:8000"]

Optimizing Layer Caching#

FROM node:20-alpine AS builder

WORKDIR /app

# 1. Copy dependency files first (changes less often)
COPY package*.json ./

# 2. Install dependencies (cached if package.json unchanged)
RUN npm ci

# 3. Copy source code (changes most often)
COPY tsconfig.json ./
COPY src ./src

# 4. Build
RUN npm run build

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY --from=builder /app/dist ./dist

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

Using Build Arguments#

FROM node:20-alpine AS builder

ARG NODE_ENV=production
ARG API_URL

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

# Use build args during build
ENV NEXT_PUBLIC_API_URL=$API_URL
RUN npm run build

FROM node:20-alpine

WORKDIR /app

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/static ./.next/static

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

# Build with arguments
docker build \
  --build-arg API_URL=https://api.example.com \
  -t myapp:latest .

Testing Stage#

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

FROM base AS test
COPY . .
RUN npm run lint
RUN npm run test

FROM base AS builder
COPY . .
RUN npm run build

FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

# Run tests without building production image
docker build --target test .

# Build production image (includes test stage)
docker build --target production -t myapp:latest .

Size Comparison#

# Before: Single stage (~1.2GB)
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["node", "dist/index.js"]

# After: Multi-stage (~150MB)
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY package*.json ./
RUN npm ci --only=production
CMD ["node", "dist/index.js"]

Best Practices#

Structure:
✓ Use specific base image tags
✓ Order layers by change frequency
✓ Minimize layer count
✓ Use .dockerignore

Security:
✓ Run as non-root user
✓ Don't include secrets in image
✓ Scan images for vulnerabilities
✓ Use minimal base images

Performance:
✓ Leverage build cache
✓ Use --mount=type=cache for package managers
✓ Parallelize independent stages
✓ Clean up in same layer as install

Multi-stage builds separate build-time dependencies from runtime, resulting in smaller, more secure images. Structure Dockerfiles to maximize cache hits, use Alpine or distroless base images, and always run as non-root in production.