Dockerfile Best Practices

Comprehensive guide for creating optimized, secure, and fast Docker images using modern BuildKit features.

Workflow

1. Identify language/framework → Pick a template from Language Templates
2. Apply essential rules → Every Dockerfile must follow Essential Rules
3. Security hardening → Non-root user, secret mounts, provenance and SBOM attestations (see references/supply_chain.md)
4. Optimize for cache → Separate deps from code, use cache mounts
5. Multi-stage if needed → Compiled languages or distroless runtime
6. Add metadata → OCI labels, HEALTHCHECK, STOPSIGNAL (see PID 1 and Signals)
7. Review → Run scripts/analyze_dockerfile.py, then docker build --check (see references/build_checks.md)

Essential Rules (Always Apply)

1. BuildKit syntax directive (first line, always)