Advanced Docker Patterns: Multi-Stage Builds, Layer Caching, and Security Hardening

Beyond "Just Get It Running"

A Dockerfile that works in development often has serious problems in production: huge image sizes (1GB+ when 50MB would suffice), secrets baked into layers, running as root, rebuilding everything when only one file changed.

Advanced Docker patterns address these problems systematically. This guide covers the techniques that experienced teams use when Docker images go to production.

Multi-Stage Builds

Multi-stage builds separate the build environment from the runtime environment:

# Node.js example: build TypeScript, run compiled JS
# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production     # Install prod dependencies
# Separate layer for dev deps (more cacheable)
RUN npm ci                       # Install all deps for building

# Stage 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build                # Compile TypeScript → dist/

# Stage 3: Production image (minimal)
FROM node:20-alpine AS runner
WORKDIR /app

# Create non-root user
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 appuser

# Only copy what's needed for production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./package.json

USER appuser                     # Don't run as root
EXPOSE 3000
CMD ["node", "dist/index.js"]

Result: Build image might be 800MB. Production image: ~150MB. Deploy the production image only.

Go Multi-Stage (Even More Dramatic)

# Go produces a single static binary — final image can be ~10MB
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download                    # Cache dependencies separately
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /bin/app ./cmd/api

# Distroless: no shell, no package manager, minimal attack surface
FROM gcr.io/distroless/static-debian12 AS runner
COPY --from=builder /bin/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

# Or use scratch (absolute minimal — only the binary):
FROM scratch
COPY --from=builder /bin/app /app
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/app"]

Layer Caching Optimization

Every RUN, COPY, ADD instruction creates a layer. Docker caches layers and reuses them on rebuild if nothing changed. Order matters:

# ❌ Bad: Copy everything first — any file change invalidates all layers
FROM node:20-alpine
WORKDIR /app
COPY . .                         # Cache miss every build!
RUN npm ci
RUN npm run build

# ✅ Good: Copy package.json first — npm install only runs when deps change
FROM node:20-alpine AS builder
WORKDIR /app

# Layer 1: These rarely change → stays cached
COPY package*.json ./
RUN npm ci                       # Only runs when package.json changes

# Layer 2: These change frequently → rebuilt, but npm ci is cached
COPY . .
RUN npm run build

# Python example with proper caching
FROM python:3.12-slim AS builder
WORKDIR /app

# Layer 1: Install system dependencies (rare changes)
RUN apt-get update && apt-get install -y --no-install-recommends     build-essential     && rm -rf /var/lib/apt/lists/*

# Layer 2: Python dependencies (changes when requirements.txt changes)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Layer 3: Application code (changes most often)
COPY . .

FROM python:3.12-slim AS runner
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /app .
USER nobody
CMD ["python", "app.py"]

BuildKit Secrets (Don't Bake Secrets into Images)

# Problem: private npm registry requires token
# ❌ Bad: token ends up in image layers (visible in docker history)
FROM node:20-alpine
ARG NPM_TOKEN                    # Shows up in docker history!
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
RUN npm install
# .npmrc stays in layer even if you delete it later!

# ✅ Good: Use BuildKit secrets — not stored in any layer
# syntax=docker/dockerfile:1
FROM node:20-alpine
RUN --mount=type=secret,id=npm_token     NPM_TOKEN=$(cat /run/secrets/npm_token) &&     echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc &&     npm install &&     rm .npmrc
# Secret never stored in any layer!

# Build with secret
docker build --secret id=npm_token,src=~/.npmrc -t my-app .
# Or from environment variable:
docker build --secret id=npm_token,env=NPM_TOKEN -t my-app .

Security Hardening

Run as Non-Root

FROM node:20-alpine

# Create a dedicated user (don't use node's default user for custom apps)
RUN addgroup --system --gid 1001 appgroup &&     adduser --system --uid 1001 --ingroup appgroup --no-create-home appuser

WORKDIR /app
COPY --chown=appuser:appgroup . .
RUN npm ci --only=production

# Switch to non-root user
USER appuser

EXPOSE 3000
CMD ["node", "server.js"]

Read-Only Filesystem

# In Kubernetes deployment
securityContext:
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  runAsUser: 1001
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]     # Drop all Linux capabilities

# App needs to write? Mount specific writable paths
volumeMounts:
- name: tmp-volume
  mountPath: /tmp
- name: logs-volume
  mountPath: /app/logs

volumes:
- name: tmp-volume
  emptyDir: {}
- name: logs-volume
  emptyDir: {}

Dockerfile Security Best Practices

# syntax=docker/dockerfile:1
FROM node:20-alpine

# Pin exact versions — avoid :latest and floating tags
# Check: docker scout cves node:20-alpine

# Minimize installed packages
RUN apk add --no-cache curl     && rm -rf /var/cache/apk/*    # Clean up

# Don't install dev tools in production
RUN npm ci --only=production      # Not just npm install

# Reduce attack surface — use slim/alpine/distroless base images
# Layers: ubuntu (72MB) > debian-slim (48MB) > alpine (7MB) > distroless (4MB) > scratch (0MB)

# Don't copy .git, node_modules, secrets, etc.
# .dockerignore is essential:

# .dockerignore
.git
.github
node_modules
*.log
.env
.env.*
*.md
tests/
.nyc_output/
coverage/
dist/        # If building inside Docker

Image Scanning

# Scan for vulnerabilities before pushing
docker scout cves my-app:latest        # Docker Desktop built-in
trivy image my-app:latest              # Open source, comprehensive
grype my-app:latest                    # Fast, Anchore's scanner

# In CI/CD pipeline (GitHub Actions):
# uses: docker/scout-action@v1
#   with:
#     command: cves
#     image: ${{ env.IMAGE }}
#     exit-code: true    # Fail build on critical vulns

BuildKit Cache Mounts

# Cache package manager caches across builds
# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./

# Cache mount: persists npm cache across builds (massive speedup)
RUN --mount=type=cache,target=/root/.npm     npm ci

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

# Go with module cache
FROM golang:1.22-alpine
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod     go mod download

Optimized Production Dockerfile Template

# syntax=docker/dockerfile:1
# ─── Base image ───────────────────────────────────
FROM node:20-alpine AS base
WORKDIR /app
ENV NODE_ENV=production

# ─── Dependencies ─────────────────────────────────
FROM base AS deps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm     npm ci --only=production

FROM base AS devdeps
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm     npm ci

# ─── Build ────────────────────────────────────────
FROM devdeps AS builder
COPY . .
RUN npm run build && npm run test:unit

# ─── Security check ───────────────────────────────
FROM deps AS security
RUN npm audit --audit-level=high

# ─── Production ───────────────────────────────────
FROM base AS runner
# Metadata labels
LABEL org.opencontainers.image.source="https://github.com/company/repo"
LABEL org.opencontainers.image.revision="${GIT_COMMIT}"

# Non-root user
RUN addgroup --system --gid 1001 nodejs &&     adduser --system --uid 1001 --ingroup nodejs nodejs

COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

USER nodejs
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3     CMD wget -qO- http://localhost:3000/health || exit 1

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

The discipline of writing good Dockerfiles pays dividends across security audits, deployment speed, and operational clarity. Small images deploy faster, have smaller attack surfaces, and cost less to store and transfer. The patterns here are worth internalizing early.

→ Minify and compact JSON data with the JSON Minifier tool.