Docker Performance Optimization

# SLOW — cache busts on every code change
FROM node:18-alpine
WORKDIR /app
COPY . .
# Copies ALL files including source code.
# Every code change → this layer rebuilds → npm install re-runs.
# npm install takes 45 seconds. It re-runs on every single commit.
RUN npm install --omit=dev
EXPOSE 3000
CMD ["node", "server.js"]

# ────────────────────────────────────────────────────────

# FAST — dependency layer cached independently of source code
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
# Copy ONLY the dependency manifest — changes rarely.
# package.json unchanged → next layer is cache hit → npm install skipped.
RUN npm install --omit=dev
# This layer is cached as long as package.json doesn't change.
# A code-only change never reaches this layer.
COPY . .
# Source code copied AFTER install. Cache for npm install is unaffected.
EXPOSE 3000
CMD ["node", "server.js"]

# syntax=docker/dockerfile:1

# Stage 1 — builder: full toolchain, compiles everything
FROM node:18-alpine AS builder
WORKDIR /build
COPY package*.json ./
RUN npm install
# Install ALL dependencies including build tools, TypeScript compiler, etc.
COPY . .
RUN npm run build
# Compile TypeScript → JavaScript output in /build/dist/
# This stage will be discarded — it never appears in the registry.

# Stage 2 — production: minimal runtime, no build tooling
FROM node:18-alpine AS production
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
# Re-install production dependencies only — no compiler, no type checker.
COPY --from=builder /build/dist ./dist
# Copy ONLY the compiled output from the builder stage.
# Everything else in the builder — source .ts files, devDependencies,
# TypeScript compiler, test fixtures — is discarded here.
RUN addgroup -S appgroup && adduser -S appuser -G appgroup && \
    chown -R appuser:appgroup /app
USER appuser
EXPOSE 3000
CMD ["node", "dist/server.js"]

# syntax=docker/dockerfile:1
# BuildKit reads this comment and enables advanced features.

FROM node:18-alpine AS base
WORKDIR /app
COPY package*.json ./
RUN npm install

# ── These two stages are independent — BuildKit runs them in PARALLEL ──

FROM base AS test
# Test stage — runs linting and unit tests during the build.
# If tests fail, the build fails before the production image is created.
COPY . .
RUN npm run lint && npm test
# BuildKit starts this stage at the same time as the production stage below.

FROM base AS production
# Production stage — builds the final image.
# Runs IN PARALLEL with the test stage — no waiting.
RUN npm install --omit=dev
COPY . .
RUN addgroup -S appgroup && adduser -S appuser -G appgroup && \
    chown -R appuser:appgroup /app
USER appuser
EXPOSE 3000
CMD ["node", "server.js"]

# Enable BuildKit on older Docker versions:
DOCKER_BUILDKIT=1 docker build --target production -t payment-api:v1.0.0 .

# Docker 23+ — BuildKit is on by default, no env var needed:
docker build --target production -t payment-api:v1.0.0 .

# BuildKit cache mount — speeds up package managers inside RUN:
# Caches the npm/pip cache directory between builds on the same host.
RUN --mount=type=cache,target=/root/.npm \
    npm install --omit=dev
# /root/.npm is the npm cache directory.
# With a cache mount, npm only downloads packages not already in the cache.
# On subsequent builds, even fresh package installs are dramatically faster.

# CI pipeline script — GitHub Actions, GitLab CI, or any runner:
GIT_SHA=$(git rev-parse --short HEAD)
IMAGE="acmecorp/payment-api"
CACHE_IMAGE="${IMAGE}:cache"

# Build with registry cache — import previous cache, export new cache:
docker buildx build \
  --cache-from type=registry,ref=${CACHE_IMAGE} \
  --cache-to   type=registry,ref=${CACHE_IMAGE},mode=max \
  --target production \
  --tag ${IMAGE}:${GIT_SHA} \
  --push \
  .
# --cache-from  → pull cached layers from the registry before building
#                 CI runner reuses the same layers as the previous run
# --cache-to    → push updated cache back to the registry after building
#                 mode=max caches all layers, not just the final stage
# --push        → push the final image to the registry in the same command

# First CI run (cold cache): 94 seconds — downloads everything
# Second CI run (warm cache, code change only): 8 seconds
# Second CI run (warm cache, no change): 3 seconds

# Base image choices — same Node.js runtime, very different sizes:
FROM node:18              # 991MB — Debian full, all tools
FROM node:18-slim         # 245MB — Debian slim, fewer packages
FROM node:18-alpine       #  91MB — Alpine Linux, minimal
FROM node:18-alpine AS b
FROM gcr.io/distroless/nodejs18-debian11  # 164MB — no shell, no package manager

# For Node.js: node:18-alpine is the standard production choice.
# For Python: python:3.11-slim (not alpine — C extension builds need glibc).
# For Go:     distroless/static (binary needs nothing — not even a runtime).

# Combining RUN instructions — each RUN creates a layer:
# SLOW (three layers, package cache stays in image):
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# FAST (one layer, cache deleted in the same instruction that created it):
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*
# --no-install-recommends  → skip suggested packages — often 50-200MB of extras
# rm -rf /var/lib/apt/lists → delete the package index downloaded by apt-get update
#                             if deleted in a SEPARATE RUN, the index layer persists
#                             must be in the SAME RUN to actually reduce image size

# Starting point — measure the baseline:
time docker build --no-cache -t payment-api:before .
# Result: 11m 18s  |  Image size: 1.41 GB

# Step 1 — add .dockerignore:
echo "node_modules\n.git\n.env*\ncoverage\ndist" > .dockerignore
time docker build --no-cache -t payment-api:step1 .
# Result: 10m 02s  |  Build context: 847MB → 2.4MB  (-76s from context transfer)

# Step 2 — reorder COPY instructions (package.json before source):
# Edit Dockerfile: move COPY package*.json ./ before COPY . .
# (Subsequent builds with code-only change — cache now hits on npm install)
time docker build -t payment-api:step2 .
# Result: 1m 54s   |  npm install served from cache  (-8m 08s)

# Step 3 — multi-stage build (discard TypeScript compiler):
# Separate builder and production stages in Dockerfile
time docker build --target production -t payment-api:step3 .
# Result: 1m 44s   |  Image size: 1.41GB → 94MB  (-10s from smaller push)

# Step 4 — enable BuildKit + parallel stages:
DOCKER_BUILDKIT=1 time docker build --target production -t payment-api:step4 .
# Result: 1m 08s   |  Test and production stages run in parallel  (-36s)

# Step 5 — registry cache in CI:
# Add --cache-from and --cache-to to the CI build command
# Result: 0m 52s   |  Warm cache — only changed layers rebuild  (-16s)

# ─────────────────────────────────────────────────────────
# Before: 11m 18s  |  After: 0m 52s  |  14× faster
# Team of 15, 10 commits/day, 5 days/week:
# Before: 15 × 10 × 5 × 678s = 141.25 hours of CI time per week
# After:  15 × 10 × 5 × 52s  =  10.83 hours of CI time per week
# Saved:  130 hours of engineering wait time per week.