Docker Build Cache Optimization

Optimize Docker build performance by effectively managing build cache, understanding cache invalidation, and implementing advanced caching strategies with BuildKit.

What This Skill Does

This skill guides you through Docker build cache optimization techniques to dramatically reduce build times in local development and CI/CD pipelines. You'll learn to leverage BuildKit's caching mechanisms, implement multi-stage builds efficiently, use cache mount types, configure external cache backends, and structure Dockerfiles for maximum cache reuse.

Instructions

1. Understand Docker Build Cache Fundamentals

**Analyze current build cache behavior:**

**Key concepts:**

2. Optimize Dockerfile Layer Ordering

**Restructure Dockerfile for better cache hits:**

```dockerfile

❌ Bad: Dependencies reinstall on any code change

COPY . /app

RUN npm install

✅ Good: Cache dependencies separately

COPY package.json package-lock.json /app/

RUN npm install

COPY . /app

```

**Best practices:**

3. Implement BuildKit Cache Mounts

**Use `--mount=type=cache` for package managers:**

```dockerfile

Cache npm packages across builds

RUN --mount=type=cache,target=/root/.npm \

npm install

Cache apt packages

RUN --mount=type=cache,target=/var/cache/apt \

--mount=type=cache,target=/var/lib/apt \

apt-get update && apt-get install -y build-essential

Cache Go modules

RUN --mount=type=cache,target=/go/pkg/mod \

go build -o app

```

**Enable BuildKit if not default:**

```bash

export DOCKER_BUILDKIT=1

docker build --progress=plain .

```

4. Configure External Cache Backends

**For CI/CD: Use registry cache for build artifacts sharing:**

```bash

Push cache to registry

docker buildx build \

--cache-to type=registry,ref=myregistry.com/myapp:buildcache \

--cache-from type=registry,ref=myregistry.com/myapp:buildcache \

-t myregistry.com/myapp:latest \

--push .

```

**For GitHub Actions: Use GitHub Actions cache:**

```yaml

uses: docker/build-push-action@v5

with:

context: .

cache-from: type=gha

cache-to: type=gha,mode=max

```

**For local development: Use local cache:**

```bash

docker buildx build \

--cache-to type=local,dest=/tmp/docker-cache \

--cache-from type=local,src=/tmp/docker-cache \

.

```

5. Implement Multi-Stage Build Caching

**Optimize multi-stage builds for cache efficiency:**

```dockerfile

Stage 1: Dependencies (cached separately)

FROM node:20 AS deps

WORKDIR /app

COPY package*.json ./

RUN --mount=type=cache,target=/root/.npm npm ci

Stage 2: Builder (uses cached deps)

FROM node:20 AS builder

WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules

COPY . .

RUN npm run build

Stage 3: Production (minimal final image)

FROM node:20-slim

WORKDIR /app

COPY --from=builder /app/dist ./dist

COPY --from=deps /app/node_modules ./node_modules

CMD ["node", "dist/index.js"]

```

**Benefits:**

6. Use Build Secrets Without Cache Invalidation

**Mount secrets without leaking into cache:**

```dockerfile

❌ Bad: Secret baked into layer

ARG NPM_TOKEN

RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && \

npm install && \

rm .npmrc

✅ Good: Secret mounted, not cached

RUN --mount=type=secret,id=npm_token \

echo "//registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token)" > .npmrc && \

npm install

```

**Build with secret:**

```bash

docker buildx build --secret id=npm_token,src=$HOME/.npmrc .

```

7. Inspect and Debug Cache Usage

**Analyze build cache effectiveness:**

```bash

Show detailed build progress

docker buildx build --progress=plain .

Inspect build history

docker history myimage:latest

Clear build cache when needed

docker buildx prune -f

Clear specific cache

docker buildx prune --filter type=exec.cachemount

```

**Look for:**

8. Implement Cache-Efficient Patterns

**Copy only what's needed, when needed:**

```dockerfile

Install dependencies first (changes rarely)

COPY package.json package-lock.json ./

RUN npm ci --production

Copy source code last (changes frequently)

COPY src/ ./src/

COPY public/ ./public/

Build artifacts

RUN npm run build

```

**Use .dockerignore:**

```

node_modules

.git

.env*

*.md

.dockerignore

Dockerfile

.gitignore

dist/

coverage/

```

9. Configure CI/CD Pipeline Cache

**GitHub Actions example:**

```yaml

uses: docker/setup-buildx-action@v3

uses: docker/build-push-action@v5

with:

context: .

push: true

tags: myregistry.com/myapp:${{ github.sha }}

cache-from: |

type=registry,ref=myregistry.com/myapp:buildcache

type=gha

cache-to: type=gha,mode=max

```

**GitLab CI example:**

```yaml

build:

image: docker:latest

services:

- docker:dind

before_script:

- docker buildx create --use

script:

- docker buildx build

--cache-from type=registry,ref=$CI_REGISTRY_IMAGE:buildcache

--cache-to type=registry,ref=$CI_REGISTRY_IMAGE:buildcache,mode=max

--push

-t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .

```

10. Monitor and Measure Impact

**Track build performance improvements:**

**Key metrics:**

Important Notes

Examples

**Before optimization:**

```dockerfile

FROM node:20

WORKDIR /app

COPY . .

RUN npm install

RUN npm run build

CMD ["npm", "start"]

Build time: 5m 30s (clean), 4m 45s (cached)

```

**After optimization:**

```dockerfile

FROM node:20 AS deps

WORKDIR /app

COPY package*.json ./

RUN --mount=type=cache,target=/root/.npm npm ci

FROM node:20 AS builder

WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules

COPY . .

RUN npm run build

FROM node:20-slim

WORKDIR /app

COPY --from=builder /app/dist ./dist

COPY --from=deps /app/node_modules ./node_modules

CMD ["node", "dist/index.js"]

Build time: 5m 10s (clean), 45s (cached)

```

**Result: 84% faster incremental builds**

Reference

Based on Docker official documentation: https://docs.docker.com/build/cache/