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

cache-

stage-

base-

ctx-

sec-

dep-

inst-

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