docker

name	docker
description	Containerization guidance for multi-stage builds, non-root execution, dockerignore hygiene, layer caching, healthchecks, and secret handling. Use when writing or reviewing Dockerfiles and container images.

Docker

Build minimal, reproducible images that start fast, run as non-root, and separate build-time concerns from runtime behavior.

When to Activate

• Write or refactor a Dockerfile
• Split build and runtime concerns
• Harden a container for production
• Improve Docker build cache performance
• Add container healthchecks
• Review secret handling in image builds
• Shrink image size and attack surface

Base Images and Layering

Use Case	Preferred	Avoid
Production service	Distroless or slim runtime	Full distro with build toolchain
Build stage	Language-specific SDK image	Installing compilers in runtime image
Tiny static binary	scratch when feasible	Heavy general-purpose images

Order	Reason
Copy lockfiles first	Maximizes dependency cache hits
Install dependencies	Expensive step stays cached
Copy source later	Code changes do not bust dependency layer

Runtime Hardening

BAD

FROM python:3.12-slim
WORKDIR /app
COPY . .
CMD ["python", "main.py"]

GOOD

FROM python:3.12-slim AS runtime
WORKDIR /app
RUN useradd --create-home appuser
COPY --chown=appuser:appuser . .
USER appuser
CMD ["python", "main.py"]

Scenario	Rule
Build-time private dependency access	Use ephemeral build secrets if available
Runtime credentials	Inject via environment or secret store
Static secret in Dockerfile	Never do it

Preferred	Avoid
Application-level readiness endpoint	Checking only whether PID exists
Fast, dependency-light command	Heavy scripts that change container state

Ignore List

Always Ignore
.git
node_modules
.venv
test artifacts
local secrets and .env files

BAD

COPY . .
RUN npm install

GOOD

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .

Checklist

• Dockerfile uses multi-stage builds when build tooling is required
• Dependency layers are copied before application source
• Runtime image uses a non-root user
• .dockerignore excludes local junk and secrets
• Secrets are injected at runtime or via build secret facilities
• Healthcheck verifies real service readiness
• Base image is minimal for the workload