| name | docker-expert |
| description | Expert Docker: Dockerfiles, multi-stage builds, image size/cache optimization, Compose, and container best practices. Trigger keywords: Docker, Dockerfile, container, image, multi-stage, layer cache, docker-compose, .dockerignore, entrypoint, distroless, non-root, healthcheck, build context. Use for writing/optimizing Dockerfiles, shrinking images, faster builds, or Compose setup. |
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
# ---- 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.
