Docker Build Optimization: Cache, BuildKit, and Layer Ordering

How Docker Build Cache Works

Docker caches each layer (Dockerfile instruction) and reuses the cached layer on subsequent builds when the instruction and its inputs have not changed. Cache invalidation is sequential and cascading: once a layer’s cache is invalidated, all subsequent layers are rebuilt from scratch, even if their instructions did not change.

The critical implication: instruction order in a Dockerfile determines which layers benefit from cache. Dependencies that change rarely (package.json, requirements.txt, go.mod) should be copied and installed before application source code. Application source code changes on every commit; if source code is copied before dependency installation, every build reinstalls all dependencies regardless of whether they changed.

Cache invalidation triggers: a FROM base image has been updated (new digest); a COPY or ADD instruction source files have changed (Docker checksums all copied files); a RUN instruction text has changed; or any parent layer cache has been invalidated (cascading).

BuildKit (enabled by default since Docker 23.0) adds two important optimisation tools: ‘–mount=type=cache’ for mounting a persistent cache directory during RUN instructions (eliminates the need to copy package caches into the image), and ‘–mount=type=bind’ for reading source files during RUN without adding them as a layer.

Build Cache Optimization Patterns

# Enable BuildKit (default since Docker 23.0, or set env var)
export DOCKER_BUILDKIT=1

# WRONG layer ordering: source code before dependencies
# (source change invalidates npm install cache)
FROM node:20-alpine
WORKDIR /app
COPY . .              # invalidated on every source change
RUN npm install       # reinstalls every time

# CORRECT layer ordering: dependencies before source code
# (npm install cache survives source-only changes)
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./   # copied first
RUN npm ci                               # only reinstalls when package*.json changes
COPY . .                                 # source copied after
RUN npm run build

# BuildKit RUN --mount=type=cache (persistent cache directory)
# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --cache /root/.npm

# Python with pip cache
FROM python:3.11-alpine
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# Build with explicit cache from a registry
docker buildx build \
  --cache-from=type=registry,ref=myregistry/myapp:cache \
  --cache-to=type=registry,ref=myregistry/myapp:cache,mode=max \
  --tag myapp:latest .

# Build and immediately tag for deployment
docker build \
  --build-arg APP_VERSION=1.2.3 \
  --tag myapp:1.2.3 \
  --tag myapp:latest \
  .

The ‘–mount=type=cache’ directive in BuildKit preserves a directory between builds without including its content in image layers. npm’s download cache stored in /root/.npm persists across builds, so only packages not in the cache need to be downloaded. This can reduce a 3-minute dependency installation to under 10 seconds for builds where only a few packages changed.

Build Optimisation Techniques

CI/CD Build Optimisation

GitHub Actions Build Cache

GitHub Actions provides a native cache mechanism for Docker BuildKit layers. This avoids reinstalling dependencies on every pull request build without requiring a separate registry.

# .github/workflows/build.yml
name: Build Docker Image
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: false
          tags: myregistry/myapp:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

# On first run: full build, cache written
# On subsequent runs: dependency layers restored from cache
# Only layers invalidated by actual changes are rebuilt

Measuring and Profiling Build Time

Before optimising, measure where build time is actually spent. Docker BuildKit provides timing information in its output; enabling it reveals which instructions are slow.

# Enable BuildKit progress display (shows timing per instruction)
DOCKER_BUILDKIT=1 docker build --progress=plain -t myapp:latest . 2>&1 | \
  grep -E 'DONE|CACHED|ERROR'

# CACHED lines show cache hits (no rebuild cost)
# DONE lines show rebuild time in seconds

# Force rebuild without cache (to measure cold build time)
DOCKER_BUILDKIT=1 docker build --no-cache -t myapp:latest .

# View build cache storage
docker buildx du
docker system df  # shows build cache size

# Prune build cache (keeps disk usage in check)
docker builder prune --keep-storage 5GB

Build Security: ARGs, Secrets, and Cache Poisoning

Practical Examples

Optimised Multi-Stage Dockerfile with BuildKit Cache

# syntax=docker/dockerfile:1
# Requires BuildKit (DOCKER_BUILDKIT=1 or Docker 23.0+)

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,id=npm-cache,target=/root/.npm \
    npm ci --cache /root/.npm

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src/ ./src/
COPY tsconfig.json ./
RUN npm run build && npm prune --production

FROM node:20-alpine AS production
RUN addgroup -S app && adduser -S app -G app
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]

This Dockerfile achieves maximum cache reuse: the npm install step is only rerun when package.json or package-lock.json changes. The BuildKit cache mount means npm does not re-download packages even when the lockfile changes — it serves them from the persistent cache. Source code changes (the most frequent change) only rebuild the TypeScript compilation step and the production stage, not the dependency installation.

Quick Reference: Key Commands and Options

# Inspect current configuration
docker inspect <container> --format='{{json .HostConfig}}' | python3 -m json.tool

# View container resource usage
docker stats <container> --no-stream

# Check container logs
docker logs <container> --tail 50 --timestamps

# Verify running processes inside container
docker exec <container> ps aux

# Check container environment variables
docker exec <container> env | sort

These diagnostic commands work across all container scenarios: ‘docker inspect’ shows the full HostConfig including all runtime parameters, ‘docker stats’ shows real-time resource consumption, and ‘docker logs’ shows output from the main process. Use these as the starting point for any container investigation before diving into more specific tooling.

Common Build Optimisation Issues

Layer Ordering Is the Foundation; BuildKit Adds the Speed

The majority of Docker build time in typical applications is spent on dependency installation. Correct layer ordering (dependency manifests first, source code last) ensures the dependency installation layer is a cache hit on every source-only change. BuildKit’s cache mounts eliminate redundant package downloads even when dependencies change. Registry caching brings these benefits to CI environments. Together, these techniques can reduce typical build times from minutes to seconds for the common case.

• Copy dependency manifest files (package.json, requirements.txt, go.mod) before application source in the Dockerfile. This single change makes the dependency installation layer cache-stable across source code changes.
• Use BuildKit ‘–mount=type=cache’ for package manager caches. This avoids both re-downloading packages between builds and baking package caches into image layers.
• For CI/CD environments, use registry-backed build cache (‘–cache-from type=registry’ and ‘–cache-to type=registry’). Local cache mounts do not persist between ephemeral CI runners.