[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":81,"_72":82,"_35":83},"articles",{"_11":12,"_13":14,"_15":16,"_17":16,"_18":19,"_20":21,"_22":23,"_24":23,"_25":16,"_26":27},"content",[30],"pageable",{"_28":21,"_29":19},"totalElements",1,"totalPages","size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_31":32,"_33":34,"_35":36,"_37":38,"_11":39,"_40":-5,"_41":23,"_42":27,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":52,"_54":55,"_56":57,"_58":59,"_60":52,"_61":55,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71},"id",56,"title","Multi-Stage Builds: Beyond Basics","slug","docker-part-6-multi-stage-builds","excerpt","Advanced multi-stage patterns, secrets, and testing stages","# Docker Compendium Part 6: Multi-Stage Builds - Beyond Basics\n\nMulti-stage builds are Docker's answer to the \"build vs runtime\" dilemma. You've seen the basics - separate build and runtime stages. This article goes deeper: parallel stages, conditional builds, testing stages, and patterns that make complex builds manageable.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| Topic | Advanced multi-stage patterns, testing stages, secrets handling |\n| Complexity | Intermediate-Advanced |\n| Prerequisites | Part 3 (Build Process), Part 5 (Optimization) |\n| Key Insight | Stages are independent build graphs - use them for more than size |\n| Time to Master | 2-3 hours |\n\n---\n\n## 🎯 What You'll Learn\n\n- **Advanced stage patterns** - parallel builds, conditional stages, shared bases\n- **Testing in builds** - test stages, fail-fast builds, coverage extraction\n- **Secrets management** - build-time secrets that never reach images\n- **Dynamic staging** - building different outputs from same Dockerfile\n- **Real-world patterns** - monorepo builds, polyglot applications\n\n---\n\n## 🔥 Production Story: The Leaked Credentials\n\nA security audit found NPM tokens in a production image. The team was confused - they had deleted the `.npmrc` file after npm install.\n\n**The Dockerfile:**\n\n```dockerfile\nFROM node:20\nARG NPM_TOKEN\nRUN echo \"//registry.npmjs.org/:_authToken=${NPM_TOKEN}\" >> ~/.npmrc\nRUN npm install\nRUN rm ~/.npmrc # \"Cleaned up!\"\nCOPY . .\nCMD [\"node\", \"index.js\"]\n```\n\n**The audit finding:**\n\n```bash\n# Extract image layers\ndocker save myapp | tar -xf -\n\n# Find the token in layer 2\ncat abc123/layer.tar | tar -xf - -O root/.npmrc\n# //registry.npmjs.org/:_authToken=npm_SECRETTOKEN123\n```\n\nThe `.npmrc` was deleted in layer 4, but it still existed in layer 2. Docker layers are additive - deletion only hides, never removes.\n\n**The fix using multi-stage:**\n\n```dockerfile\n# Stage 1: Install with secrets (never shipped)\nFROM node:20 AS deps\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n npm install\n\n# Stage 2: Production (no secrets ever present)\nFROM node:20-alpine\nCOPY --from=deps /app/node_modules ./node_modules\nCOPY . .\nCMD [\"node\", \"index.js\"]\n```\n\n**Lesson:** Multi-stage builds aren't just for size reduction - they're a security boundary. Secrets in build stages never reach the final image.\n\n---\n\n## 🧠 Mental Model: Stages as Build Graphs\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ MULTI-STAGE BUILD GRAPH │\n│ │\n│ Traditional view: Linear pipeline │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │build│ → │test │ → │lint │ → │final│ │\n│ └─────┘ └─────┘ └─────┘ └─────┘ │\n│ │\n│ Reality: Directed Acyclic Graph (DAG) │\n│ │\n│ ┌─────────┐ │\n│ │ base │ ← Shared foundation │\n│ └────┬────┘ │\n│ │ │\n│ ├──────────────┬──────────────┐ │\n│ ▼ ▼ ▼ │\n│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │\n│ │ deps │ │ test │ │ lint │ ← Run in parallel! │\n│ └────┬────┘ └────┬────┘ └────┬────┘ │\n│ │ │ │ │\n│ │ ▼ ▼ │\n│ │ ┌─────────┐ ┌─────────┐ │\n│ │ │ report │ │ check │ ← Optional outputs │\n│ │ └─────────┘ └─────────┘ │\n│ │ │\n│ └──────────────┬────────────────── │\n│ ▼ │\n│ ┌─────────┐ │\n│ │ final │ ← Production image │\n│ └─────────┘ │\n│ │\n│ BuildKit builds independent branches in PARALLEL │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n**Key insight:** Stages without dependencies on each other build simultaneously. Design your Dockerfile to maximize parallelism.\n\n---\n\n## 🔬 Deep Dive\n\n### Stage Fundamentals Revisited\n\n```dockerfile\n# Each FROM starts a new stage\nFROM node:20 AS builder # Stage 0, named \"builder\"\nWORKDIR /app\nRUN npm install\n\nFROM node:20 AS tester # Stage 1, named \"tester\"\nWORKDIR /app\nRUN npm test\n\nFROM node:20-alpine # Stage 2, unnamed (final)\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\n```\n\n**Stage properties:**\n- Each stage starts fresh (empty filesystem)\n- Stages can be named (`AS name`) or numbered (0, 1, 2...)\n- Only the final stage becomes the output image\n- `COPY --from=` extracts files from other stages\n- ARG values reset after each FROM\n\n### Parallel Stage Execution\n\nBuildKit automatically parallelizes independent stages:\n\n```dockerfile\n# These run in PARALLEL\nFROM node:20 AS frontend\nWORKDIR /frontend\nCOPY frontend/package*.json ./\nRUN npm ci\nCOPY frontend/ .\nRUN npm run build\n\nFROM python:3.11 AS backend # Parallel with frontend\nWORKDIR /backend\nCOPY backend/requirements.txt .\nRUN pip install -r requirements.txt\nCOPY backend/ .\nRUN python -m pytest\n\nFROM golang:1.21 AS tools # Parallel with frontend AND backend\nWORKDIR /tools\nCOPY tools/ .\nRUN go build -o /bin/migrate ./cmd/migrate\n\n# Final stage waits for all dependencies\nFROM nginx:alpine\nCOPY --from=frontend /frontend/dist /usr/share/nginx/html\nCOPY --from=backend /backend/static /usr/share/nginx/html/api\nCOPY --from=tools /bin/migrate /usr/local/bin/\n```\n\n**Execution timeline:**\n\n```\nTime ────────────────────────────────────────────────────────►\n\nfrontend: [npm ci]──────[build]─────────────────┐\n │\nbackend: [pip install]─[pytest]────────────────┼───┐\n │ │\ntools: [go build]────────────────────────────┼───┼──┐\n │ │ │\nfinal: └───┴──┴─[copy all]\n\nTotal time = max(frontend, backend, tools) + final copy\nNOT: frontend + backend + tools + final (sequential)\n```\n\n### Shared Base Stages\n\nAvoid duplicating common setup:\n\n```dockerfile\n# Shared base with common dependencies\nFROM node:20-alpine AS base\nWORKDIR /app\nRUN apk add --no-cache python3 make g++ # For native modules\n\n# Development dependencies\nFROM base AS deps-dev\nCOPY package*.json ./\nRUN npm ci\n\n# Production dependencies only\nFROM base AS deps-prod\nCOPY package*.json ./\nRUN npm ci --only=production\n\n# Build stage uses dev deps\nFROM deps-dev AS builder\nCOPY . .\nRUN npm run build\n\n# Test stage uses dev deps\nFROM deps-dev AS tester\nCOPY . .\nRUN npm test\n\n# Production uses prod deps + build output\nFROM base AS production\nCOPY --from=deps-prod /app/node_modules ./node_modules\nCOPY --from=builder /app/dist ./dist\nUSER node\nCMD [\"node\", \"dist/index.js\"]\n```\n\n### Testing Stages\n\n**Fail-fast testing:**\n\n```dockerfile\nFROM node:20 AS deps\nCOPY package*.json ./\nRUN npm ci\n\nFROM deps AS test\nCOPY . .\n# Build fails if tests fail\nRUN npm run test\n\nFROM deps AS lint\nCOPY . .\nRUN npm run lint\n\nFROM deps AS typecheck\nCOPY . .\nRUN npm run typecheck\n\n# Only builds if ALL checks pass\nFROM deps AS builder\nCOPY . .\nRUN npm run build\n\nFROM node:20-alpine\nCOPY --from=builder /app/dist ./dist\nCOPY --from=deps /app/node_modules ./node_modules\nCMD [\"node\", \"dist/index.js\"]\n```\n\n**Extract test artifacts:**\n\n```dockerfile\nFROM node:20 AS test\nCOPY . .\nRUN npm ci\nRUN npm test -- --coverage --coverageDirectory=/coverage\n\n# Extract coverage report\nFROM scratch AS coverage\nCOPY --from=test /coverage /\n\n# Usage:\n# docker build --target coverage -o ./coverage-report .\n```\n\n**Conditional test execution:**\n\n```dockerfile\nFROM node:20 AS base\nCOPY package*.json ./\nRUN npm ci\nCOPY . .\n\n# Test stage - runs tests\nFROM base AS test\nRUN npm test\n\n# Build stage - doesn't depend on test\nFROM base AS builder\nRUN npm run build\n\n# Production - can optionally require test\nFROM node:20-alpine AS production\n# If you want tests required, add:\n# COPY --from=test /app/test-passed /tmp/\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n```\n\n```bash\n# Build without tests (faster for dev)\ndocker build --target production .\n\n# Build with tests required (CI)\ndocker build --target test . && docker build --target production .\n```\n\n### Secrets in Multi-Stage Builds\n\n**BuildKit secrets (recommended):**\n\n```dockerfile\n# syntax=docker/dockerfile:1\n\nFROM node:20 AS deps\nWORKDIR /app\nCOPY package*.json ./\n\n# Secret available only during this RUN\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n npm ci\n\n# Production stage - secret never existed here\nFROM node:20-alpine\nWORKDIR /app\nCOPY --from=deps /app/node_modules ./node_modules\nCOPY . .\nCMD [\"node\", \"index.js\"]\n```\n\n```bash\n# Build with secret\ndocker build --secret id=npmrc,src=.npmrc -t myapp .\n```\n\n**SSH agent forwarding:**\n\n```dockerfile\n# syntax=docker/dockerfile:1\n\nFROM golang:1.21 AS builder\nWORKDIR /app\n\n# Clone private repos using SSH\nRUN --mount=type=ssh \\\n git clone git@github.com:company/private-lib.git\n\nCOPY . .\nRUN go build -o /app/server\n\nFROM scratch\nCOPY --from=builder /app/server /server\nCMD [\"/server\"]\n```\n\n```bash\n# Build with SSH forwarding\ndocker build --ssh default -t myapp .\n```\n\n**Stage isolation for secrets:**\n\n```dockerfile\n# Build stage with secrets (discarded)\nFROM node:20 AS build-with-secrets\nARG NPM_TOKEN\nARG AWS_ACCESS_KEY\n\n# These secrets exist in this stage only\nRUN echo \"//registry.npmjs.org/:_authToken=${NPM_TOKEN}\" >> ~/.npmrc\nRUN aws s3 cp s3://private-bucket/config.json ./config.json\nRUN npm ci\n\n# Clean stage - copy only artifacts, not secrets\nFROM node:20-alpine AS production\nWORKDIR /app\n\n# Only node_modules copied, not .npmrc or AWS credentials\nCOPY --from=build-with-secrets /app/node_modules ./node_modules\nCOPY --from=build-with-secrets /app/config.json ./\n\nCOPY . .\nCMD [\"node\", \"index.js\"]\n```\n\n### Dynamic Stage Selection\n\n**Building different outputs:**\n\n```dockerfile\nFROM node:20 AS base\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci\nCOPY . .\n\n# Development image with hot reload\nFROM base AS development\nRUN npm install -g nodemon\nCMD [\"nodemon\", \"src/index.js\"]\n\n# Production optimized\nFROM base AS builder\nRUN npm run build\nRUN npm prune --production\n\nFROM node:20-alpine AS production\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCOPY --from=builder /app/node_modules ./node_modules\nUSER node\nCMD [\"node\", \"dist/index.js\"]\n\n# Debug image with tools\nFROM production AS debug\nUSER root\nRUN apk add --no-cache curl vim strace\nUSER node\n```\n\n```bash\n# Build for different environments\ndocker build --target development -t myapp:dev .\ndocker build --target production -t myapp:prod .\ndocker build --target debug -t myapp:debug .\n```\n\n### Monorepo Patterns\n\n**Shared dependencies:**\n\n```\nmonorepo/\n├── packages/\n│ ├── common/\n│ ├── api/\n│ └── web/\n├── package.json\n└── Dockerfile\n```\n\n```dockerfile\n# syntax=docker/dockerfile:1\n\n# Base with all workspace deps\nFROM node:20 AS base\nWORKDIR /app\nCOPY package*.json ./\nCOPY packages/common/package*.json ./packages/common/\nCOPY packages/api/package*.json ./packages/api/\nCOPY packages/web/package*.json ./packages/web/\nRUN npm ci\n\n# Build common first (dependency for others)\nFROM base AS common-builder\nCOPY packages/common/ ./packages/common/\nRUN npm run build --workspace=packages/common\n\n# Build API (parallel with web)\nFROM base AS api-builder\nCOPY --from=common-builder /app/packages/common/dist ./packages/common/dist\nCOPY packages/api/ ./packages/api/\nRUN npm run build --workspace=packages/api\n\n# Build Web (parallel with api)\nFROM base AS web-builder\nCOPY --from=common-builder /app/packages/common/dist ./packages/common/dist\nCOPY packages/web/ ./packages/web/\nRUN npm run build --workspace=packages/web\n\n# API production image\nFROM node:20-alpine AS api\nWORKDIR /app\nCOPY --from=api-builder /app/packages/api/dist ./dist\nCOPY --from=api-builder /app/node_modules ./node_modules\nCMD [\"node\", \"dist/index.js\"]\n\n# Web production image (static files)\nFROM nginx:alpine AS web\nCOPY --from=web-builder /app/packages/web/dist /usr/share/nginx/html\n```\n\n```bash\n# Build specific service\ndocker build --target api -t myapp-api .\ndocker build --target web -t myapp-web .\n```\n\n### COPY --from External Images\n\nYou can copy from any image, not just build stages:\n\n```dockerfile\nFROM node:20-alpine\n\n# Copy binary from another image\nCOPY --from=busybox:latest /bin/wget /usr/local/bin/wget\n\n# Copy config from official image\nCOPY --from=nginx:alpine /etc/nginx/nginx.conf /etc/nginx/\n\n# Copy tool from utility image\nCOPY --from=aquasec/trivy:latest /usr/local/bin/trivy /usr/local/bin/\n\n# Copy CA certificates (useful for scratch images)\nCOPY --from=alpine:latest /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/\n```\n\n### Build Arguments Across Stages\n\n```dockerfile\n# Global ARG (before first FROM)\nARG NODE_VERSION=20\n\nFROM node:${NODE_VERSION} AS builder\n# ARG must be redeclared after FROM to use\nARG NODE_ENV=production\nENV NODE_ENV=${NODE_ENV}\n\nRUN npm ci\nRUN npm run build\n\nFROM node:${NODE_VERSION}-alpine\n# Must redeclare again for this stage\nARG NODE_ENV=production\nENV NODE_ENV=${NODE_ENV}\n\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n```\n\n```bash\n# Override at build time\ndocker build \\\n --build-arg NODE_VERSION=18 \\\n --build-arg NODE_ENV=development \\\n -t myapp .\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Not Using Named Stages\n\n```dockerfile\n# ❌ Fragile - stage numbers change if you add stages\nFROM node:20\nRUN npm install\n\nFROM node:20\nCOPY --from=0 /app/node_modules ./\n\n# ✅ Robust - names are stable\nFROM node:20 AS deps\nRUN npm install\n\nFROM node:20\nCOPY --from=deps /app/node_modules ./\n```\n\n### Mistake 2: Forgetting ARG Scope\n\n```dockerfile\n# ❌ ARG not available after FROM\nARG VERSION=1.0\nFROM node:20\nRUN echo $VERSION # Empty!\n\n# ✅ Redeclare ARG after FROM\nARG VERSION=1.0\nFROM node:20\nARG VERSION\nRUN echo $VERSION # 1.0\n```\n\n### Mistake 3: Copying More Than Needed\n\n```dockerfile\n# ❌ Copying entire stage\nFROM builder AS deps\nRUN npm ci\n\nFROM node:20-alpine\nCOPY --from=deps /app ./ # Copies everything including source!\n\n# ✅ Copy only what's needed\nFROM node:20-alpine\nCOPY --from=deps /app/node_modules ./node_modules\n```\n\n---\n\n## 🐛 Debug This: The Missing Environment Variable\n\nA developer reports: \"My app works in the build stage but fails in production. Environment variables are missing!\"\n\n```dockerfile\nFROM node:20 AS builder\nARG API_URL=http://localhost:3000\nENV API_URL=${API_URL}\nWORKDIR /app\nCOPY . .\nRUN npm ci\nRUN npm run build # Uses API_URL in build\n\nFROM node:20-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n# Error: API_URL is undefined!\n```\n\n**Why is API_URL missing in the final stage?**\n\n---\n\n**✅ Solution:**\n\nENV variables don't transfer between stages. Each stage is independent.\n\n**The problem:** `ENV API_URL` was set in `builder` stage, but the final stage starts fresh from `node:20-alpine` with no knowledge of the builder's environment.\n\n**Fix 1: Redeclare in final stage:**\n\n```dockerfile\nFROM node:20 AS builder\nARG API_URL=http://localhost:3000\nENV API_URL=${API_URL}\nRUN npm run build\n\nFROM node:20-alpine\nARG API_URL=http://localhost:3000\nENV API_URL=${API_URL}\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n```\n\n**Fix 2: Use runtime configuration:**\n\n```dockerfile\nFROM node:20 AS builder\nARG API_URL\nRUN API_URL=${API_URL} npm run build\n# API_URL baked into build output\n\nFROM node:20-alpine\n# No ENV needed - it's in the built files\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n```\n\n**Fix 3: Configuration file:**\n\n```dockerfile\nFROM node:20 AS builder\nARG API_URL\nRUN echo \"{\\\"apiUrl\\\": \\\"${API_URL}\\\"}\" > config.json\nRUN npm run build\n\nFROM node:20-alpine\nCOPY --from=builder /app/config.json ./\nCOPY --from=builder /app/dist ./dist\nCMD [\"node\", \"dist/index.js\"]\n```\n\n**Key lesson:** Stages share nothing automatically. COPY --from transfers files, not environment.\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Parallel Stage Build\n⭐ Difficulty: Easy | ⏱️ Time: 15 minutes\n\n```dockerfile\n# Create a Dockerfile with parallel stages\n# Stage 1: frontend - npm run build (simulate with sleep 5)\n# Stage 2: backend - pip install (simulate with sleep 5)\n# Stage 3: final - copies from both\n\n# Measure build time to verify parallelism\n# With parallelism: ~5 seconds\n# Without: ~10 seconds\n```\n\n```bash\n# Your Dockerfile here\ncat > Dockerfile << 'EOF'\n# TODO: Create parallel stages\nFROM alpine AS frontend\nRUN sleep 5 && echo \"frontend\" > /frontend.txt\n\nFROM alpine AS backend\nRUN sleep 5 && echo \"backend\" > /backend.txt\n\nFROM alpine\nCOPY --from=frontend /frontend.txt /\nCOPY --from=backend /backend.txt /\nEOF\n\n# Measure\ntime docker build --progress=plain -t parallel-test .\n```\n\n---\n\n### Exercise 2: Test Stage with Artifacts\n⭐⭐ Difficulty: Medium | ⏱️ Time: 20 minutes\n\n```bash\nmkdir test-stage && cd test-stage\n\n# Create test project\ncat > package.json << 'EOF'\n{\n \"scripts\": {\n \"test\": \"echo 'Tests passed!' && mkdir -p coverage && echo 'report' > coverage/report.txt\"\n }\n}\nEOF\n\n# Create Dockerfile with:\n# 1. deps stage - installs dependencies\n# 2. test stage - runs tests, generates coverage\n# 3. coverage stage - exports just the coverage report\n# 4. production stage - final image\n\n# Build and extract coverage:\n# docker build --target coverage -o ./coverage-output .\n```\n\n---\n\n### Exercise 3: Secret Handling\n⭐⭐ Difficulty: Medium | ⏱️ Time: 20 minutes\n\n```bash\nmkdir secrets-test && cd secrets-test\n\n# Create a \"secret\" file\necho \"SECRET_TOKEN=abc123\" > .env.secret\n\n# Create Dockerfile that:\n# 1. Uses BuildKit secret mount to access .env.secret\n# 2. Creates a file that proves secret was accessed\n# 3. Final image should NOT contain the secret\n\n# Verify:\n# 1. Build succeeds\n# 2. docker history shows no secret\n# 3. docker run myapp cat /app/used-secret.txt works\n# 4. docker run myapp cat /.env.secret fails (file doesn't exist)\n```\n\n---\n\n### Exercise 4: Monorepo Multi-Service Build\n⭐⭐⭐ Difficulty: Hard | ⏱️ Time: 30 minutes\n\n```bash\nmkdir -p monorepo/{api,web,shared}\n\n# API service\ncat > monorepo/api/index.js << 'EOF'\nconsole.log(\"API Service\");\nEOF\n\n# Web service\ncat > monorepo/web/index.js << 'EOF'\nconsole.log(\"Web Service\");\nEOF\n\n# Shared library\ncat > monorepo/shared/utils.js << 'EOF'\nmodule.exports = { version: \"1.0.0\" };\nEOF\n\n# Create single Dockerfile that can build:\n# --target api → API service image\n# --target web → Web service image\n# Both should include shared library\n# Use parallel stages where possible\n```\n\n---\n\n### Exercise 5: Complete CI/CD Pipeline Dockerfile\n⭐⭐⭐⭐ Difficulty: Expert | ⏱️ Time: 35 minutes\n\nCreate a comprehensive Dockerfile with these stages:\n\n```\ndeps-base → deps-dev → lint ──┐\n │\n → deps-prod ├─→ build → production\n │\n test ───────────┘\n ↓\n coverage (extractable)\n```\n\nRequirements:\n1. `deps-base`: Install system deps\n2. `deps-dev`: Full dev dependencies\n3. `deps-prod`: Production only\n4. `lint`: ESLint check (fails build if errors)\n5. `test`: Jest tests (fails build if tests fail)\n6. `coverage`: Extractable coverage report\n7. `build`: TypeScript compile\n8. `production`: Minimal runtime image\n\n```bash\n# All checks pass:\ndocker build -t myapp:prod .\n\n# Extract coverage:\ndocker build --target coverage -o ./coverage .\n\n# Lint only:\ndocker build --target lint .\n```\n\n---\n\n## 🎤 Senior-Level Interview Questions\n\n### Q1: How do you handle secrets in multi-stage Docker builds?\n\n**Strong Answer:**\n\n\"There are several patterns depending on the use case:\n\n**BuildKit secret mounts (best practice):**\n```dockerfile\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci\n```\nSecret is available during build but never written to any layer. Build with `--secret id=npmrc,src=.npmrc`.\n\n**Stage isolation:**\nEven with ARG, use a separate build stage that's discarded:\n```dockerfile\nFROM node AS build-with-secrets\nARG NPM_TOKEN\nRUN npm ci # Uses token\n\nFROM node AS production\nCOPY --from=build-with-secrets /app/node_modules ./\n# Token never existed in this stage\n```\n\n**SSH forwarding for git:**\n```dockerfile\nRUN --mount=type=ssh git clone git@github.com:private/repo\n```\n\n**What NOT to do:**\n- Don't use ARG for secrets in final stage (visible in history)\n- Don't COPY secret files (persist in layers)\n- Don't delete secrets after use in same stage (still in earlier layer)\n\nThe key principle: secrets should exist only during specific RUN commands, never in any layer that becomes part of the final image.\"\n\n### Q2: Explain how BuildKit parallelizes multi-stage builds.\n\n**Strong Answer:**\n\n\"BuildKit represents the Dockerfile as a directed acyclic graph (DAG) and executes independent branches in parallel.\n\n**How it determines parallelism:**\n1. Parses all stages and their dependencies (COPY --from, FROM...AS)\n2. Builds dependency graph\n3. Stages with no dependencies on each other run concurrently\n\n**Example:**\n```dockerfile\nFROM base AS frontend\nRUN npm build # Takes 30s\n\nFROM base AS backend\nRUN pip install # Takes 30s\n\nFROM alpine AS final\nCOPY --from=frontend /dist /\nCOPY --from=backend /app /\n```\n\nWithout parallelism: 30 + 30 + copy = 61s\nWith parallelism: max(30, 30) + copy = 31s\n\n**Maximizing parallelism:**\n- Keep stages independent when possible\n- Use shared base stages to avoid duplicate work\n- Don't create unnecessary dependencies between stages\n\n**Viewing parallelism:**\n```bash\ndocker build --progress=plain .\n```\nShows which stages run simultaneously.\n\n**Practical impact:** Complex builds with frontend, backend, and tools can see 2-3x speedup. In our CI, we reduced builds from 15 minutes to 5 minutes primarily through parallel stages.\"\n\n### Q3: When would you use multiple FROM stages vs just combining RUN commands?\n\n**Strong Answer:**\n\n\"They solve different problems:\n\n**Multiple stages for:**\n1. **Size reduction** - Build tools not needed at runtime\n2. **Security isolation** - Secrets in build stage only\n3. **Different base images** - Full SDK for build, minimal for runtime\n4. **Parallel builds** - Independent stages run concurrently\n5. **Multiple outputs** - Same Dockerfile, different --target builds\n\n**Combined RUN for:**\n1. **Layer optimization** - Install and clean in one layer\n2. **Cache efficiency** - Logically grouped operations\n3. **Simple linear operations** - No benefit from separation\n\n**Decision framework:**\n\n```\nNeed different base image? → Multi-stage\nHandling secrets? → Multi-stage\nWant parallel builds? → Multi-stage\nBuilding multiple artifacts? → Multi-stage\nJust installing packages? → Combined RUN\nSimple cleanup? → Combined RUN\n```\n\n**Example where both matter:**\n```dockerfile\n# Multi-stage for build/runtime separation\nFROM node AS builder\n# Combined RUN for efficient layer\nRUN npm ci && npm run build && rm -rf node_modules\n\nFROM node:alpine\nCOPY --from=builder /app/dist ./\n```\n\nI use multi-stage as the default for production images and combine RUNs within each stage for optimization.\"\n\n### Q4: How would you structure a Dockerfile for a monorepo with shared dependencies?\n\n**Strong Answer:**\n\n\"Monorepo Dockerfiles need to balance build speed, parallelism, and caching:\n\n**Pattern 1: Shared base with workspace installs:**\n```dockerfile\nFROM node AS base\nCOPY package*.json ./\nCOPY packages/*/package*.json ./packages/\nRUN npm ci --workspace=packages/*\n\nFROM base AS service-a\nCOPY packages/shared ./packages/shared\nCOPY packages/service-a ./packages/service-a\nRUN npm run build --workspace=service-a\n\nFROM base AS service-b\nCOPY packages/shared ./packages/shared\nCOPY packages/service-b ./packages/service-b\nRUN npm run build --workspace=service-b\n```\n\n**Key considerations:**\n\n1. **Layer caching** - Copy package.jsons first, then source\n2. **Shared code** - Build shared libraries first, copy to dependents\n3. **Parallelism** - Independent services build in parallel\n4. **Selective builds** - Use --target to build specific services\n5. **Cache mounts** - Share npm/pip cache across stages\n\n**For very large monorepos:**\n- Consider using Docker buildx bake for coordinated builds\n- Use build matrix in CI for service-specific builds\n- Implement change detection to skip unchanged services\n\n**Production deployment:**\nEach service gets its own minimal image, built from the same Dockerfile with different --target flags. Shared base ensures consistency.\"\n\n### Q5: How do you debug issues in earlier build stages when only the final stage fails?\n\n**Strong Answer:**\n\n\"Several techniques:\n\n**1. Build up to specific stage:**\n```bash\ndocker build --target builder -t debug:builder .\ndocker run -it debug:builder /bin/sh\n```\n\n**2. Add debug output in Dockerfile:**\n```dockerfile\nRUN npm ci && ls -la node_modules/\nRUN npm run build || (cat build.log && exit 1)\n```\n\n**3. Use BuildKit progress output:**\n```bash\nDOCKER_BUILDKIT=1 docker build --progress=plain . 2>&1 | tee build.log\n```\nShows all output including from cached layers.\n\n**4. Extract artifacts from intermediate stage:**\n```dockerfile\nFROM scratch AS debug-artifacts\nCOPY --from=builder /app/build-log.txt /\nCOPY --from=builder /app/node_modules/.package-lock.json /\n```\n```bash\ndocker build --target debug-artifacts -o ./debug-output .\n```\n\n**5. Add a debug stage:**\n```dockerfile\nFROM builder AS debug\nRUN find / -name '*.log' 2>/dev/null\nRUN cat /app/tsconfig.json\nRUN npm ls --depth=0\n```\n\n**6. Override entrypoint:**\n```bash\ndocker run --entrypoint /bin/sh myapp:builder -c 'env && ls -la'\n```\n\n**7. BuildKit cache inspection:**\n```bash\ndocker buildx du --verbose\n```\n\nMy usual flow: build with --progress=plain, identify failing step, build --target to that stage, shell in and investigate.\"\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### Core Concepts\n\n| Concept | Key Point |\n|---------|-----------|\n| Stage independence | Each stage starts fresh, shares nothing automatically |\n| Parallel execution | Independent stages build concurrently |\n| Named stages | Use AS name for maintainability |\n| COPY --from | Only way to transfer files between stages |\n| --target | Build up to specific stage |\n\n### Multi-Stage Patterns\n\n```dockerfile\n# Size reduction\nFROM sdk AS builder → FROM runtime\n\n# Security isolation\nFROM full AS build-with-secrets → FROM clean\n\n# Testing pipeline\nFROM base → tests → lint → build → production\n\n# Multiple outputs\nFROM base → service-a, service-b, service-c (--target)\n\n# Monorepo\nFROM base → shared → parallel services\n```\n\n### What You Can Do Now\n\n1. **Structure builds for parallelism** - Independent stages for speed\n2. **Handle secrets safely** - BuildKit mounts or stage isolation\n3. **Create multi-output Dockerfiles** - One file, many targets\n4. **Debug intermediate stages** - --target and artifact extraction\n\n---\n\n## 📋 Quick Reference\n\n### Stage Syntax\n\n```dockerfile\n# Named stage\nFROM image:tag AS stagename\n\n# Copy from stage\nCOPY --from=stagename /src /dest\n\n# Copy from external image\nCOPY --from=nginx:alpine /etc/nginx /etc/nginx\n\n# Build specific target\ndocker build --target stagename .\n\n# ARG across stages\nARG VERSION # Before first FROM - global\nFROM node\nARG VERSION # Must redeclare in each stage\n```\n\n### BuildKit Secret/SSH\n\n```dockerfile\n# syntax=docker/dockerfile:1\n\n# Secret mount\nRUN --mount=type=secret,id=mysecret,target=/path \\\n command\n\n# SSH mount\nRUN --mount=type=ssh \\\n git clone git@github.com:repo\n\n# Build commands\ndocker build --secret id=mysecret,src=file.txt .\ndocker build --ssh default .\n```\n\n### Debug Commands\n\n```bash\n# Build to specific stage\ndocker build --target stagename -t debug .\n\n# Shell into stage\ndocker run -it --rm debug /bin/sh\n\n# Extract files from stage\ndocker build --target stage -o ./output .\n\n# Verbose build output\ndocker build --progress=plain . 2>&1 | tee build.log\n```\n\n---\n\n## 📅 Review Schedule\n\n| Day | Task | Time |\n|-----|------|------|\n| Day 1 | Review stage isolation principles | 10 min |\n| Day 3 | Do Exercise 1 (parallel stages) | 15 min |\n| Day 7 | Implement testing stage in a project | 25 min |\n| Day 14 | Add BuildKit secrets to a build | 20 min |\n| Day 30 | Refactor a complex Dockerfile with multiple targets | 30 min |\n\n---\n\n## 📚 Series Navigation\n\n| Previous | Current | Next |\n|----------|---------|------|\n| [Part 5: Dockerfile Optimization](docker-part-5-dockerfile-optimization) | **Part 6: Multi-Stage Builds** | [Part 7: Base Image Selection](docker-part-7-base-images) |\n\n**Docker Compendium Series:**\n- [Part 0: How to Use This Series](docker-part-0-how-to-use-this-series)\n- [Part 1: Container Internals](docker-part-1-container-internals)\n- [Part 2: Image Anatomy](docker-part-2-image-anatomy)\n- [Part 3: Build Process Deep Dive](docker-part-3-build-process)\n- [Part 4: Networking Internals](docker-part-4-networking-internals)\n- [Part 5: Dockerfile Optimization Patterns](docker-part-5-dockerfile-optimization)\n- **Part 6: Multi-Stage Builds: Beyond Basics** ← You are here\n- [Part 7: Base Image Selection & Security](docker-part-7-base-images)\n","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:25.435919Z","createdAt","2026-06-10T07:19:25.436519Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",18,"estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Devops","readingTime","seriesId","seriesOrder",6,"author",{"_31":55,"_94":57,"_95":96,"_97":98,"_99":-5,"_100":-5,"_101":-5,"_102":-5,"_103":-5},"category",{"_31":90,"_72":59,"_35":91,"_75":92,"_93":-5},"tags",[78,79,80],"series",{"_31":55,"_72":73,"_35":74,"_75":76,"_77":23},"name","Docker Compendium: From Practitioner to Expert","docker-compendium","description","Master Docker internals, optimization patterns, and production best practices. For developers who use Docker daily but want deeper understanding of what's happening under the hood. Not a beginner series - we assume you can write Dockerfiles and use docker-compose. Learn what namespaces and cgroups really do, why your builds are slow, how to debug containers that crash, and how to run Docker in production like a pro.\n","isActive",{"_31":87,"_72":88,"_35":89},{"_31":84,"_72":85,"_35":86},{"_31":81,"_72":82,"_35":83},228,"Multi-stage","multi-stage",227,"Dockerfile","dockerfile",213,"Docker","docker",7,"devops","Category for Devops","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]