Multi-Stage Builds
Multi-stage builds allow you to use multiple FROM instructions in a single Dockerfile, dramatically reducing final image size by separating build-time dependencies from runtime.
The Problem Multi-Stage Solves
Without multi-stage builds, images include all build tools:
# Single-stage build - LARGE IMAGE
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install # Includes devDependencies
COPY . .
RUN npm run build # Build tools in image
CMD ["node", "dist/index.js"]
# Result: 1GB+ image with npm, build tools, source code
Multi-Stage Build Syntax
Each FROM instruction starts a new build stage:
# Stage 1: Build
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Stage 2: Production
FROM node:18-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm install --only=production
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/index.js"]
# Result: ~150MB image with only runtime dependencies
How Multi-Stage Works
┌─────────────────────────────────────────────────────────────┐
│ Stage 1: builder │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ node:18 (full image) │ │
│ │ + All source code │ │
│ │ + devDependencies │ │
│ │ + Build tools │ │
│ │ → Produces: /app/dist/ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ COPY --from=builder │
│ ▼ │
│ Stage 2: production │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ node:18-alpine (small image) │ │
│ │ + Only production dependencies │ │
│ │ + Built application (from Stage 1) │ │
│ │ → Final image │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Naming Stages
Name stages for clarity and reference:
# Named stages
FROM node:18 AS dependencies
FROM node:18 AS builder
FROM node:18-alpine AS production
# Copy from named stage
COPY --from=builder /app/dist ./dist
COPY --from=dependencies /app/node_modules ./node_modules
Building Specific Stages
Target specific stages during build:
# Build only the builder stage
docker build --target builder -t myapp:builder .
# Build production stage (default - last stage)
docker build -t myapp:production .
# Build dependencies stage
docker build --target dependencies -t myapp:deps .
Practical Examples
Node.js Application
# Build stage
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Production stage
FROM node:18-alpine
WORKDIR /app
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]
Go Application
Go compiles to a static binary, enabling ultra-small images:
# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o main .
# Production stage - distroless for security
FROM gcr.io/distroless/static-debian11
COPY --from=builder /app/main /
CMD ["/main"]
# Result: ~10MB image!
Python Application
# Build stage
FROM python:3.11 AS builder
WORKDIR /app
RUN pip install --user pipenv
ENV PIPENV_VENV_IN_PROJECT=1
COPY Pipfile Pipfile.lock ./
RUN pipenv install --deploy
# Production stage
FROM python:3.11-slim
WORKDIR /app
# Copy virtual environment from builder
COPY --from=builder /app/.venv ./.venv
ENV PATH="/app/.venv/bin:$PATH"
COPY . .
CMD ["python", "app.py"]
React Application with Nginx
# Build stage
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Production stage
FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
# Result: ~25MB image with optimized static files
Multiple Build Stages
You can have more than two stages:
# Stage 1: Base dependencies
FROM node:18 AS base
WORKDIR /app
COPY package*.json ./
# Stage 2: Development dependencies
FROM base AS dev-deps
RUN npm install
# Stage 3: Production dependencies
FROM base AS prod-deps
RUN npm install --only=production
# Stage 4: Build
FROM dev-deps AS builder
COPY . .
RUN npm run build
# Stage 5: Development image
FROM dev-deps AS development
COPY . .
CMD ["npm", "run", "dev"]
# Stage 6: Production image
FROM node:18-alpine AS production
WORKDIR /app
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/index.js"]
Build different images:
docker build --target development -t myapp:dev .
docker build --target production -t myapp:prod .
Copying from External Images
Copy from any image, not just build stages:
FROM alpine
# Copy from an external image
COPY --from=nginx:alpine /etc/nginx/nginx.conf /etc/nginx/
# Copy from official tool images
COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/
COPY --from=docker/compose:latest /usr/local/bin/docker-compose /usr/local/bin/
Size Comparison
Example image sizes for a Node.js application:
| Build Type | Image Size |
|---|---|
| Single stage (node:18) | 1.1 GB |
| Multi-stage (node:18-alpine) | 150 MB |
| With production deps only | 100 MB |
| With optimized layers | 85 MB |
Best Practices
Use Appropriate Base Images
# Build stage: Full image with build tools
FROM node:18 AS builder
# Production: Minimal image
FROM node:18-alpine AS production
# or
FROM gcr.io/distroless/nodejs18-debian11 AS production
Clean Up in Build Stages
FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm ci \
&& npm run build \
&& npm prune --production # Remove devDependencies
Use .dockerignore
# Exclude unnecessary files from build context
node_modules
.git
*.md
Dockerfile
.dockerignore
Leverage Layer Caching
FROM node:18 AS builder
WORKDIR /app
# Copy package files first (changes less often)
COPY package*.json ./
RUN npm ci
# Then copy source (changes more often)
COPY . .
RUN npm run build
Key Takeaways
- Multi-stage builds separate build-time from runtime dependencies
- Each FROM instruction starts a new stage
- COPY --from copies files between stages or from external images
- Name stages with AS for clarity
- Target specific stages with --target for development builds
- Multi-stage builds can reduce image size by 90% or more
- Use minimal base images for production stages
- Go applications can use scratch or distroless for tiny images
التالي · الدرس 14 من 32
Introduction to Volumes
قراءة 4 دقيقة
أنهيت 13 من 32 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

