Multi-Stage Builds
Build in a fat image, ship in a tiny one — the professional way to minimize production images
Skills taught: docker.multi-stage, docker.builder-pattern, docker.production-images
The build-time vs runtime problem
To build a React app you need Node.js, npm, webpack, TypeScript, and dozens of devDependencies — all totaling hundreds of megabytes. But to run the app in production, you only need the compiled HTML/CSS/JS files served by nginx (~200 MB). Without multi-stage builds, you'd ship the entire build environment to production. Multi-stage builds solve this by using multiple FROM statements in one Dockerfile — each stage can use a different base image, and you can selectively copy files between stages.
# ❌ NAIVE — ships node_modules and build tools to production
FROM node:20
WORKDIR /app
COPY . .
RUN npm install && npm run build
# Image size: ~1.2 GB (node + all devDependencies + source)
CMD ["npm", "start"] # serves static files — wasteful
# ✅ MULTI-STAGE — build with Node, serve with nginx
# ── Stage 1: Build ───────────────────────────────────────
# Name this stage 'builder'
FROM node:20-alpine AS builder
WORKDIR /app
# Leverage layer cache: install deps first
COPY package*.json ./
RUN npm ci
# Copy source and build
COPY . .
RUN npm run build
# /app/dist now contains the compiled static files
# ── Stage 2: Production ──────────────────────────────────
# Fresh base — nothing from the builder stage carries over
FROM nginx:alpine
# COPY --from=builder: copy ONLY the built output from stage 1
COPY --from=builder /app/dist /usr/share/nginx/html
# Optional: custom nginx config
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
docker build -t myapp:prod .
docker images myapp
# REPOSITORY TAG SIZE
# myapp prod 24.5MB ← only nginx + static files!
# Compare:
# Single-stage approach: ~1.2 GB
# Multi-stage: ~25 MB
# That's a 48× reduction
Multi-stage for a Node.js API
# Stage 1: compile TypeScript
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json tsconfig.json ./
RUN npm ci
COPY src/ ./src/
RUN npm run build # tsc → compiles to /app/dist
# Stage 2: production — only compiled JS and prod deps
FROM node:20-alpine AS production
WORKDIR /app
ENV NODE_ENV=production
# Install ONLY production dependencies (no devDeps, no TypeScript)
COPY package*.json ./
RUN npm ci --omit=dev
# Copy compiled output from builder
COPY --from=builder /app/dist ./dist
# Run as non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
EXPOSE 3000
CMD ["node", "dist/server.js"]
Tip: Target a specific stage during development: docker build --target builder -t myapp:dev . — this builds only the build stage, great for debugging the build step without running the full pipeline.
Frequently Asked Questions
Can I have more than two stages?
Yes — you can have as many stages as you need. Common patterns: a 'test' stage that runs unit tests, a 'builder' stage that compiles, and a 'production' stage that only has the runtime. CI can target the test stage to run tests without building the full production image.