ADR-051: Multi-stage Docker builds for minimal images

Category: development Provenance: human

Decision

Use multi-stage Docker builds to produce minimal production images. Build stage installs dependencies, final stage contains only runtime requirements.

Rationale

Multi-stage builds produce smaller images (100s of MB vs GBs). Smaller images = faster pulls, less storage, smaller attack surface. Build tools (gcc, make) not needed at runtime. Only ship runtime dependencies. Separates build-time and runtime concerns. Faster image pulls in production. Lower network costs. Better security (fewer packages = fewer vulnerabilities).

Agent Instructions

Define Dockerfile with separate build and runtime stages. Build stage: install uv, sync all dependencies including dev/build tools. Runtime stage: copy only installed packages and application code. Use slim base images (python:3.13-slim). Don't include build tools, compilers, or dev dependencies in final image.

Rejected Alternatives

Single-stage builds

Large images with unnecessary build tools. Slower deployments. More security vulnerabilities.

Separate build and runtime Dockerfiles

Harder to maintain. Duplication. Multi-stage achieves same goal in single file.