docker-expert

# Docker Expert > Small, reproducible, non-root, cache-friendly. Order layers from least- to most-changing, build in one stage and ship artifacts from another, and never bake secrets into the image. ## When to Use - Writing or optimizing a Dockerfile. - Reducing image size, speeding builds, or fixing cache busting. - Multi-service local dev with Compose. - Container networking, volumes, signals, or startup issues. ## When NOT to Use - Cluster orchestration, scaling, rollouts, probes → `kubernetes-expert`. - The app code itself → the relevant language skill. - CI pipeline YAML → `github-master`. ## Core Principles ### 1. Small & secure base - Minimal, **pinned** bases: `node:22.4-slim`, `python:3.12-slim`, Alpine, or **distroless** for runtime. Never `:latest` (non-reproducible). - Run as a **non-root** user (`USER`). Copy only what's needed; add a `.dockerignore` (`.git`, `node_modules`, build output, secrets) to shrink the build context and avoid leaking files. ### 2. Cache-efficient layers - Order instructions least- → most-frequently-changing. **Copy dependency manifests and install before copying source**, so editing code doesn't bust the dependency layer. - Combine related `RUN` steps and clean caches **in the same layer** (`apt-get … && rm -rf /var/lib/apt/lists/*`) — a separate cleanup layer doesn't shrink the image. - Use BuildKit cache mounts (`RUN --mount=type=cache`) for package managers; pass secrets via `--mount=type=secret`, never `ARG`/`ENV`. ### 3. Multi-stage builds - Heavy build/compile stage → copy only artifacts into a lean runtime stage. Drops compilers, dev deps, and source from the final image (often 5–20× smaller). ### 4. Correct runtime - One concern per container. Use **exec-form** `CMD`/`ENTRYPOINT` (`["node","server.js"]`) so signals (SIGTERM) reach the process for graceful shutdown; add `--init` or `tini` if your process doesn't reap children. - Add a `HEALTHCHECK`. Configure via env; persist data in volumes, not the writable layer. ## Common Mistakes - **`COPY . .` before installing deps** → every code change reinstalls everything. - **`:latest` / unpinned bases** → irreproducible builds. - **Secrets in `ARG`/`ENV` or layers** → baked into history; use build secrets / runtime env. - **Cleanup in a separate `RUN`** → image doesn't shrink (layers are additive). - **Running as root** → larger blast radius; add a non-root `USER`. - **Shell-form `CMD`** → PID 1 is the shell, signals don't propagate; container won't shut down cleanly. - **No `.dockerignore`** → huge build context, slow builds, leaked files. ## Examples **Multi-stage Node image, cache-friendly, non-root** ```dockerfile # ---- build ---- FROM node:22-slim AS build WORKDIR /app COPY package*.json ./ RUN --mount=type=cache,target=/root/.npm npm ci # cached unless manifests change COPY . . RUN npm run build # ---- runtime ---- FROM node:22-slim WORKDIR /app ENV NODE_ENV=production COPY package*.json ./ RUN npm ci --omit=dev && npm cache clean --force COPY --from=build /app/dist ./dist USER node HEALTHCHECK --interval=30s CMD node -e "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))" CMD ["node", "dist/server.js"] ``` ## See Also - `kubernetes-expert` — deploying these images with probes and resources. - `nodejs-backend-expert` / `go-expert` — the services you containerize. - `security-expert` — image scanning and supply-chain safety. - `github-master` — building/pushing images in CI.