Dockerfile Optimization Best Practices

Comprehensive Dockerfile optimization guide sourced exclusively from official Docker documentation. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Dockerfiles or modifying existing ones
• Optimizing Docker build times (layer caching, cache mounts, context management)
• Reducing Docker image size (multi-stage builds, minimal base images)
• Hardening container security (secret mounts, non-root users, attestations)
• Setting up CI/CD pipelines with Docker builds
• Reviewing Dockerfiles for anti-patterns

Rule Categories by Priority

Quick Reference

1. Layer Caching & Ordering (CRITICAL)

• cache-layer-order – Order layers by change frequency
• cache-copy-deps-first – Copy dependency files before source code
• cache-copy-link – Use COPY –link for cache-efficient layer copying
• cache-mount-package – Use cache mounts for package managers
• cache-apt-combine – Combine apt-get update with install
• cache-external – Use external cache for CI/CD builds
• cache-invalidation – Avoid unnecessary cache invalidation
• cache-minimize-layers – Consolidate related RUN instructions

2. Multi-Stage Builds (CRITICAL)

• stage-separate-build-runtime – Separate build and runtime stages
• stage-named-stages – Use named build stages
• stage-parallel-branches – Exploit parallel stage execution
• stage-target-builds – Use target builds for dev/prod
• stage-copy-artifacts-only – Copy only final artifacts between stages
• stage-reusable-base – Create reusable base stages

3. Base Image Selection (HIGH)

• base-minimal-image – Use minimal base images
• base-official-images – Use Docker Official Images
• base-pin-versions – Pin base image versions with digests
• base-arg-version – Use ARG before FROM to parameterize base images
• base-rebuild-regularly – Rebuild images regularly with –pull
• base-distroless – Use distroless or scratch images for production

4. Build Context Management (HIGH)

• ctx-dockerignore – Use .dockerignore to exclude unnecessary files
• ctx-bind-mounts – Use bind mounts instead of COPY for build-only files
• ctx-minimize-context – Keep build context small
• ctx-syntax-directive – Use syntax directive for latest BuildKit features (prerequisite for cache mounts, secret mounts, heredocs, COPY –link)

5. Security & Secrets (HIGH)

• sec-secret-mounts – Use secret mounts for sensitive data
• sec-non-root-user – Run as non-root user
• sec-no-secrets-in-args – Never pass secrets via ARG or ENV
• sec-ssh-mounts – Use SSH mounts for private repository access
• sec-attestations – Enable SBOM and provenance attestations
• sec-no-unnecessary-packages – Avoid installing unnecessary packages
• sec-ephemeral-containers – Design ephemeral, stateless containers

6. Dependency Management (MEDIUM-HIGH)

• dep-cache-mount-apt – Use cache mount for apt package manager
• dep-cache-mount-npm – Use cache mount for npm, yarn, and pnpm
• dep-cache-mount-pip – Use cache mount for pip
• dep-version-pin – Pin package versions for reproducibility
• dep-cleanup-caches – Clean package manager caches in the same layer

7. Instruction Patterns (MEDIUM)

• inst-json-cmd – Use JSON form for CMD and ENTRYPOINT
• inst-healthcheck – Define HEALTHCHECK for container orchestration
• inst-heredoc-scripts – Use heredocs for multi-line scripts
• inst-entrypoint-exec – Use exec in entrypoint scripts
• inst-workdir-absolute – Use absolute paths with WORKDIR
• inst-copy-over-add – Prefer COPY over ADD

8. Quality & Validation (MEDIUM)

• lint-build-checks – Enable Docker build checks
• lint-pipefail – Use pipefail for piped RUN commands
• lint-labels – Use standard labels for image metadata
• lint-sort-arguments – Sort multi-line arguments alphabetically
• lint-single-concern – One concern per container

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files