Docker Multi-Stage Optimizer
Expert in crafting minimal, secure Docker images using multi-stage builds, distroless bases, and BuildKit optimizations.
Activation Triggers
Activate on: "Dockerfile optimization", "multi-stage build", "distroless image", "container size", "Docker security scan", "BuildKit", "image layers", "slim image", "Docker best practices"
NOT for: Container orchestration → kubernetes-manifest-generator | CI/CD pipelines → github-actions-pipeline-builder | Runtime config → environment-config-manager
Quick Start
- Audit the existing Dockerfile — identify redundant layers, large base images, leaked secrets
- Design multi-stage pipeline — separate build, test, and runtime stages
- Select minimal base — distroless, alpine, or scratch depending on runtime needs
- Enable BuildKit — use cache mounts, secret mounts, and parallel builds
- Scan and validate — run Trivy/Grype, verify no dev dependencies in final image
Core Capabilities
| Domain | Technologies |
|---|
| Multi-Stage Builds | Builder pattern, named stages, COPY --from, cross-compilation |
| Base Images | gcr.io/distroless, alpine 3.21, chainguard, scratch |
| BuildKit | Cache mounts, secret mounts, SSH mounts, heredocs, parallel stages |
| Security | Trivy, Grype, Syft SBOM, non-root USER, read-only filesystem |
| Size Optimization | Layer squashing, .dockerignore, multi-arch builds, UPX compression |
Architecture Patterns
Multi-Stage Build Pipeline
# Stage 1: Dependencies (cached aggressively)
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
pnpm install --frozen-lockfile
# Stage 2: Build
FROM deps AS build
COPY . .
RUN pnpm build
# Stage 3: Production (minimal)
FROM gcr.io/distroless/nodejs22-debian12 AS production
COPY --from=build /app/dist /app
COPY --from=deps /app/node_modules /app/node_modules
USER nonroot
EXPOSE 3000
CMD ["app/server.js"]
BuildKit Cache Mount Pattern
# Python: cache pip downloads across builds
RUN --mount=type=cache,target=/root/.cache/pip \
pip install -r requirements.txt
# Go: cache module downloads and build cache
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
go build -o /app ./cmd/server
Security-First Layer Ordering
Least-changing layers first (maximize cache):
1. Base image selection
2. System packages (apt-get)
3. Dependency lockfiles (package-lock, go.sum)
4. Dependency install
5. Source code COPY
6. Build command
7. Runtime stage (minimal)
Anti-Patterns
- Single-stage production images — shipping compilers, dev tools, and test fixtures in production. Always use multi-stage to separate build from runtime.
- Using
latest tag for base images — non-reproducible builds. Pin to digest or specific version (node:22.14-alpine3.21).
- Running as root — containers default to root. Always add
USER nonroot or USER 1000:1000 in the final stage.
- COPY . . before dependency install — busts the dependency cache on every source change. Copy lockfiles first, install, then copy source.
- Secrets in build args —
ARG/ENV values persist in image layers. Use --mount=type=secret with BuildKit instead.
Quality Checklist
[ ] Final image uses distroless, alpine, or scratch base
[ ] No compiler, build tools, or dev dependencies in final stage
[ ] Image runs as non-root user
[ ] No secrets in build args or environment variables
[ ] .dockerignore excludes .git, node_modules, .env files
[ ] Base image pinned to specific version (not :latest)
[ ] Trivy scan passes with zero critical/high CVEs
[ ] BuildKit cache mounts used for package managers
[ ] HEALTHCHECK instruction defined
[ ] Image size under target (Node: <150MB, Go: <30MB, Python: <200MB)
[ ] Multi-arch build tested (amd64 + arm64)
[ ] SBOM generated with Syft