pe=cache,target=/root/.npm
npm ci

Copy source and build

COPY tsconfig.json ./ COPY src/ ./src/ RUN npm run build

Runtime stage

FROM node:18.20-slim AS runtime

Non-root execution

RUN groupadd -r appuser && useradd -r -g appuser appuser USER appuser

WORKDIR /app

Copy only production dependencies

COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm
npm ci --omit=dev

Copy build artifacts

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

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

### Step 3: Layer Caching Optimization
Docker caches layers by instruction hash. Order commands from least to most frequently changed:
1. Base image declaration
2. Lockfile copy
3. Dependency installation
4. Configuration files
5. Source code
6. Build commands
7. Runtime artifact copy

Invalidation occurs when a layer's content changes. Placing `COPY . .` early destroys cache reuse. The lockfile-first pattern ensures `npm ci` runs only when dependencies change.

### Step 4: BuildKit Cache & Secret Mounts
Enable BuildKit (`DOCKER_BUILDKIT=1`). Use cache mounts for package managers to avoid downloading identical artifacts across builds:
- `--mount=type=cache,target=/root/.npm`
- `--mount=type=cache,target=/root/.cache/pip`
- `--mount=type=secret,id=github_token`

Cache mounts persist across builds without bloating the image. They are invalidated when the source lockfile changes.

### Step 5: Dependency Pruning & Artifact Cleanup
Remove build tools, test files, documentation, and source maps from the runtime stage. Use `.dockerignore` to prevent unnecessary files from entering the build context:

node_modules dist .env .md .git Dockerfile docker-compose.yml

For TypeScript, exclude `tsconfig.tsbuildinfo`, `*.test.ts`, and `__snapshots__` from the runtime copy.

### Architecture Decisions & Rationale
- **Multi-stage over single-stage**: Isolates build tooling, reduces image size by 60–80%, and prevents accidental exposure of dev dependencies.
- **Distroless vs Alpine**: Distroless removes shells and package managers, shrinking attack surface. Alpine uses musl libc, which breaks native modules expecting glibc. Choose based on runtime compatibility, not size alone.
- **Non-root execution**: Prevents container breakout exploits. Runtime stages must declare `USER` after installing system packages.
- **BuildKit over legacy Docker**: Cache mounts, secret mounts, and parallel stage execution reduce build time by 30–50% without changing Dockerfile syntax.

## Pitfall Guide

### 1. Inverted Layer Order
Copying source code before dependencies invalidates the dependency installation cache on every commit. Fix: Copy `package.json`/`package-lock.json` first, run `npm ci`, then copy source.

### 2. Caching `node_modules` Across Environments
Mounting `node_modules` as a cache volume during `npm ci` causes cross-platform binary mismatches. Fix: Cache only the package manager's download directory (`~/.npm`), not `node_modules`.

### 3. Using Mutable Tags
`FROM node:latest` or `FROM node:18` resolves to unpredictable digests. Fix: Pin to `node:18.20.1-slim` and update via dependency automation (Renovate, Dependabot).

### 4. Leaving Build Artifacts in Runtime
TypeScript compilers, Webpack configs, and test runners remain in single-stage images. Fix: Use multi-stage builds and explicitly copy only `dist/` and `node_modules/` (production).

### 5. Over-Optimizing with `scratch` for Interpreted Runtimes
`scratch` images lack libc, TLS certificates, and DNS resolvers. Node.js/Python require base OS layers. Fix: Use `distroless` or `slim` variants that include minimal runtime dependencies.

### 6. Ignoring Non-Root Execution
Running as root violates CIS Docker benchmarks and enables privilege escalation. Fix: Create a dedicated user, set `USER`, and adjust file ownership before switching contexts.

### 7. Misusing BuildKit Cache Without Invalidation
Cache mounts persist indefinitely, causing stale dependencies when lockfiles update. Fix: Rely on lockfile changes to invalidate cache. Add `--no-cache` for critical security patches.

### Best Practices from Production
- Run `dive` or `docker-slim` during CI to enforce size thresholds.
- Scan images with `trivy` or `grype` before registry push.
- Set `HEALTHCHECK` and `EXPOSE` to improve orchestrator scheduling.
- Use `COPY --chmod=755` for executables to avoid post-build permission fixes.
- Validate musl/glibc compatibility with `ldd` or `patchelf` when switching base images.

## Production Bundle

### Action Checklist
- [ ] Pin base image versions to major.minor.patch and track updates via dependency automation
- [ ] Implement multi-stage builds separating compilation, dependency installation, and runtime
- [ ] Order Dockerfile instructions from least to most frequently changed to maximize layer cache hits
- [ ] Enable BuildKit and use `--mount=type=cache` for package manager downloads
- [ ] Configure `.dockerignore` to exclude source maps, tests, documentation, and local configs
- [ ] Set non-root `USER` and verify file permissions before runtime execution
- [ ] Integrate `trivy` and `dive` into CI to enforce CVE and size thresholds
- [ ] Validate cold start and health check behavior after optimization in staging

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-velocity microservice (Node/TS) | Multi-stage + `slim` base | Balances build speed, compatibility, and size | -40% egress, -30% CI time |
| Security-compliant workload (finance/healthcare) | Multi-stage + `distroless` | Minimal attack surface, no shell/package manager | +5% build complexity, -70% CVEs |
| Legacy monolith with native modules | Multi-stage + Debian `slim` | glibc compatibility, stable ABI | -35% size vs full image, neutral CI time |
| CI/CD bandwidth constrained | Alpine + multi-stage | Smallest footprint, fastest pulls | -60% push time, requires musl validation |

### Configuration Template

**Dockerfile**
```dockerfile
# syntax=docker/dockerfile:1
FROM node:18.20-slim AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:18.20-slim AS runtime

RUN groupadd -r appuser && useradd -r -g appuser appuser
USER appuser
WORKDIR /app

COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
COPY --from=builder /app/dist ./dist

EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

CI Snippet (GitHub Actions)

- name: Build optimized image
  run: |
    docker buildx build \
      --cache-from=type=gha \
      --cache-to=type=gha,mode=max \
      --output=type=docker \
      -t ${{ env.IMAGE_TAG }} .

- name: Scan for vulnerabilities
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.IMAGE_TAG }}
    severity: HIGH,CRITICAL
    exit-code: '1'

Quick Start Guide

1. Audit current image: Run docker images and dive <image> to identify layers contributing to size and CVE density.
2. Add .dockerignore: Exclude node_modules, dist, .env, *.md, and CI configs. Verify context size drops by 40–60%.
3. Refactor to multi-stage: Split build and runtime, pin base image, order lockfiles before source, and enable BuildKit cache mounts.
4. Validate in CI: Push to a staging registry, run trivy, measure push time, and confirm application health checks pass. Iterate until size and CVE thresholds are met.