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

Priority	Category	Impact	Prefix
1	Layer Caching & Ordering	CRITICAL	cache-
2	Multi-Stage Builds	CRITICAL	stage-
3	Base Image Selection	HIGH	base-
4	Build Context Management	HIGH	ctx-
5	Security & Secrets	HIGH	sec-
6	Dependency Management	MEDIUM-HIGH	dep-
7	Instruction Patterns	MEDIUM	inst-
8	Quality & Validation	MEDIUM	lint-

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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information