Agent skill
multi-stage-builds
Guide for Docker multi-stage builds with builder patterns, distroless and alpine base images, cache mounts, and build args. Use when the user needs to optimize Docker image size, separate build from runtime dependencies, or improve build performance. Trigger when the user mentions multi-stage, distroless, slim images, or Docker build optimization.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/multi-stage-builds
SKILL.md
Multi-Stage Builds
Use multi-stage Docker builds to produce minimal, secure production images by separating build-time tooling from runtime dependencies.
When to Use
- User needs to reduce Docker image size
- User ships compilers or build tools in production images
- User asks about distroless or alpine base images
- User wants faster Docker builds with cache mounts
- User needs different images for dev, test, and production
Core Patterns
Node.js Builder Pattern
Separate TypeScript compilation and dependency installation from the runtime image.
# ---------- Stage 1: Install dependencies ----------
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
# ---------- Stage 2: Build ----------
FROM deps AS builder
COPY tsconfig.json ./
COPY src/ src/
RUN npm run build && npm prune --omit=dev
# ---------- Stage 3: Production ----------
FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
CMD ["dist/index.js"]
Result: ~150MB image instead of ~1GB with full Node.js + dev dependencies.
Go Static Binary
Go compiles to a single static binary, making scratch or distroless ideal.
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 GOARCH=amd64 \
go build -ldflags="-s -w" -o /server ./cmd/server
FROM gcr.io/distroless/static-debian12
COPY --from=builder /server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]
Result: ~10-20MB image with zero OS packages and no shell for attackers to exploit.
Python with Virtual Environment
Isolate Python dependencies in a virtualenv, then copy only the venv to the runtime image.
FROM python:3.12-slim AS builder
WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
FROM python:3.12-slim
WORKDIR /app
RUN groupadd -r app && useradd -r -g app app
COPY --from=builder /opt/venv /opt/venv
COPY --from=builder /app /app
ENV PATH="/opt/venv/bin:$PATH"
USER app
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Cache Mounts for Faster Builds
Use BuildKit cache mounts to persist package manager caches across builds, avoiding repeated downloads.
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci
COPY . .
RUN npm run build
FROM rust:1.77-alpine AS rust-builder
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src/ src/
RUN --mount=type=cache,target=/usr/local/cargo/registry \
--mount=type=cache,target=/app/target \
cargo build --release && \
cp target/release/myapp /usr/local/bin/myapp
Build Args for Conditional Stages
Use build args to customize builds without separate Dockerfiles.
ARG BUILD_ENV=production
FROM node:20-alpine AS base
WORKDIR /app
COPY package.json package-lock.json ./
FROM base AS deps-production
RUN npm ci --omit=dev
FROM base AS deps-development
RUN npm ci
FROM deps-${BUILD_ENV} AS deps
FROM node:20-alpine AS final
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
Build with: docker build --build-arg BUILD_ENV=development -t myapp:dev .
Target-Based Development Workflow
Use named stages with --target for different environments from a single Dockerfile.
FROM node:20-alpine AS base
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
FROM base AS development
COPY . .
CMD ["npm", "run", "dev"]
FROM base AS test
COPY . .
RUN npm run lint && npm test
FROM base AS builder
COPY . .
RUN npm run build && npm prune --omit=dev
FROM gcr.io/distroless/nodejs20-debian12 AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["dist/index.js"]
docker build --target development -t myapp:dev .
docker build --target test -t myapp:test .
docker build --target production -t myapp:prod .
Anti-Patterns
- Copying build tools into production: Never include compilers, package managers, or dev headers in the final stage. They waste space and increase attack surface.
- Using
ubuntuordebianfor runtime: Preferalpine,slim,distroless, orscratch. A full Debian base adds 100-200MB of unnecessary packages. - Not separating dependency install from code copy: If you COPY everything before
npm ci, every source code change invalidates the dependency cache. - Ignoring
--mount=type=cache: Without cache mounts, every build re-downloads all dependencies from scratch. Enable BuildKit and use cache mounts. - Single Dockerfile per environment: Use
--targetand build args instead of maintaining separate Dockerfiles for dev, test, and prod.
Quick Reference
| Base Image | Size | Shell | Use Case |
|---|---|---|---|
scratch |
0 MB | No | Go static binaries |
distroless/static |
~2 MB | No | Static binaries, max security |
distroless/cc |
~20 MB | No | C/C++ apps needing libc |
distroless/nodejs20 |
~130 MB | No | Node.js production |
alpine |
~7 MB | Yes | When you need a shell |
debian-slim |
~80 MB | Yes | When you need apt packages |
# Enable BuildKit (required for cache mounts)
export DOCKER_BUILDKIT=1
# Build specific target
docker build --target production -t myapp:prod .
# Check final image size
docker images myapp:prod
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?