Multi Stage Dockerfile

A Docker optimization skill for creating multi-stage Dockerfiles that produce minimal, secure container images by separating build dependencies from runtime environments.

What Is This?

Overview

This skill provides best practices for writing multi-stage Dockerfiles that separate build-time dependencies from the final runtime image. It covers stage organization, layer caching, dependency management, and security hardening to produce production-ready container images with minimal attack surface and file size.

Who Should Use This

Perfect for backend developers containerizing applications, DevOps engineers optimizing Docker images, and security teams enforcing minimal container policies. Useful for any language or framework that requires build tools not needed at runtime.

Why Use It?

Problems It Solves

Single-stage Dockerfiles include build tools, compilers, and development dependencies in the final image. This inflates image size, increases attack surface, and slows deployments. Multi-stage builds produce images containing only the runtime binary and its dependencies.

Core Highlights

• Minimal Images - Final images contain only runtime necessities
• Layer Caching - Optimized stage ordering for faster rebuilds
• Security Hardening - No build tools or source code in production images
• Multi-Platform - Support for cross-compilation and multi-arch builds
• Reproducible Builds - Pinned base images and dependency versions

How to Use It?

Basic Usage

Ask Claude to create a multi-stage Dockerfile, and this skill generates optimized builds.

Scenario 1: Node.js Application

Ask Claude: "Create a multi-stage Dockerfile for my Node.js API"

Claude will generate:

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production

FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
USER appuser
EXPOSE 3000
CMD ["node", "dist/server.js"]

Scenario 2: Go Application

Tell Claude: "Multi-stage Dockerfile for a Go binary"

Claude will create a minimal image:

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server ./cmd/server

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

Real-World Examples

Image Size Reduction

A Python ML service reduced its Docker image from 2.4GB (single-stage with PyTorch build tools) to 800MB using multi-stage builds that copied only trained models and runtime dependencies into the final image.

CI/CD Pipeline Optimization

An engineering team cut Docker build times by 60% using proper layer caching. Dependency installation stages cached independently, so only code changes triggered rebuilds.

Advanced Tips

Cache Mount for Package Managers

Use BuildKit cache mounts to persist package manager caches across builds, dramatically speeding up dependency installation without bloating the final image.

Distroless Base Images

For maximum security, use Google's distroless images as the final stage. These contain only the language runtime with no shell, package manager, or OS utilities.

When to Use It?

Use Cases

• API Services - Containerize Node.js, Go, Java, or Python APIs
• Frontend Builds - Build React or Vue apps and serve with nginx
• CLI Tools - Package compiled binaries in minimal containers
• Microservices - Standardize container builds across service fleet
• Security Compliance - Produce images meeting minimal container policies

Related Topics

When you ask Claude these questions, this skill will activate:

• "Create multi-stage Dockerfile"
• "Optimize Docker image size"
• "Reduce Docker build time"
• "Secure Dockerfile best practices"

Important Notes

Requirements

• Docker 17.05+ with multi-stage build support
• BuildKit recommended for advanced features (cache mounts, secrets)
• Understanding of application build and runtime dependencies
• Base image selection appropriate for target language

Usage Recommendations

Do:

• Pin base image versions - Use specific tags, not latest, for reproducibility
• Order stages by cache efficiency - Copy dependency files before source code
• Use non-root users - Create and switch to unprivileged users in final stage
• Minimize layers - Combine related RUN commands with && operators

Don't:

• Don't copy unnecessary files - Use .dockerignore to exclude build artifacts
• Don't install dev tools in final stage - Keep runtime images minimal
• Don't skip health checks - Add HEALTHCHECK instruction for orchestrators

Limitations

• Multi-stage builds cannot share volumes between stages
• Build cache invalidation cascades when early layers change
• Cross-platform builds require BuildKit with QEMU emulation
• Debug images may need separate Dockerfile with additional tools