Docker Fundamentals: Images, Layers, & Multi-Stage Builds

An OCI (Open Container Initiative) container image is not a monolithic disk archive. It is an ordered stack of immutable, cryptographically hashed (SHA-256) filesystem diff layers composed via UnionFS (Overlay2):

• Immutable Read-Only Layers: Every instruction in a Dockerfile (FROM, COPY, RUN) generates a distinct read-only layer containing only the delta (new files, modified files, or whiteout markers for deleted files).
• Ephemeral Writable Layer (Container Layer): When a container boots, the storage driver mounts all image layers as a unified virtual filesystem (merged) and adds a thin writable layer at the top (upperdir). Any runtime write triggers a Copy-on-Write (CoW) operation.
• Layer Hash Addressability & Deduplication: If five distinct microservices share the same base layer (FROM node:20-slim), the host server downloads and stores that base layer exactly once, saving gigabytes of disk space and network bandwidth.

Docker evaluates build steps sequentially and uses cached layers whenever the instruction and the input files have not changed. A single cache miss invalidates the cache for all subsequent instructions:

Anti-Pattern (Slow Build — Inefficient Cache Use):

dockerfile
Copy
FROM node:20-alpine
WORKDIR /app
COPY . .                  # ❌ Any 1-character code change invalidates cache here!
RUN npm ci                # ❌ Forces npm to re-download 500MB of packages every build
CMD ["node", "server.js"]

Optimized Production Pattern (Fast Build — Smart Layer Caching):

dockerfile
Copy
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./     # ✅ Only invalidates if dependencies change
RUN npm ci --only=production # ✅ Reused from cache on normal source code edits
COPY src/ ./src/          # ✅ Source code copied AFTER dependency caching
USER node
CMD ["node", "src/server.js"]

Essential Dockerfile Rules:

1. Order from Least to Most Frequently Changed: Place package manifests (package.json, go.mod, requirements.txt, pom.xml) and dependency installations before copying application source code.
2. Chain RUN Commands to Minimize Layers: Combine shell operations (apt-get update && apt-get install -y --no-install-recommends pkg && rm -rf /var/lib/apt/lists/*) into a single step so package caches are cleared before the layer commits.
3. Always Include a .dockerignore File: Exclude .git, node_modules, .env, dist, and temporary IDE files from the build context to accelerate transfer speeds to the Docker daemon.

In traditional Docker builds, production containers retain development tools, C compilers, package managers (apt, apk), build headers, and devDependencies, inflating image sizes and multiplying security vulnerabilities (CVEs).

Multi-Stage Builds solve this by creating distinct build environments and copying only the compiled artifacts into a lightweight runtime image:

dockerfile
Copy
# ------------------------------------------------------------------------------
# STAGE 1: Compilation Environment
# ------------------------------------------------------------------------------
FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o /bin/app ./cmd/server

# ------------------------------------------------------------------------------
# STAGE 2: Minimal Production Runtime
# ------------------------------------------------------------------------------
FROM gcr.io/distroless/static-debian12:nonroot
WORKDIR /app
COPY --from=builder /bin/app /app/server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app/server"]

Comparison of Base Images:

• Ubuntu / Debian Base: ~80 - 150 MB. Contains full package managers, curl, bash, glibc. High CVE surface.
• Alpine Linux: ~5 MB. Ultra-lightweight, uses musl libc (can introduce memory fragmentation or compatibility bugs with certain C/C++ Python wheels or Node modules).
• Google Distroless: ~20 MB. Contains strictly your runtime and standard libraries. No shell (/bin/sh), no package manager, preventing attackers from running interactive terminal commands.
• scratch: 0 MB. Empty image, ideal for completely statically compiled Go or Rust binaries.

By default, processes inside a container execute as the root user (UID 0). If an attacker finds a remote code execution (RCE) vulnerability or triggers a container breakout, they inherit root privileges on the underlying host.

Security Hardening Checklist:

1. Never Run as Root: Create a dedicated unprivileged user (USER 10001:10001) or use distroless :nonroot.
2. Drop Linux Capabilities: Strip all default root capabilities and selectively grant only what is required:

   yaml
   Copy
   securityContext:
     allowPrivilegeEscalation: false
     readOnlyRootFilesystem: true
     capabilities:
       drop: ["ALL"]
       add: ["NET_BIND_SERVICE"]

3. Mount Root Filesystem as Read-Only: Prevent malware or unauthorized modifications from writing to disk. Provide an in-memory tmpfs mount for ephemeral scratch space at /tmp.