containerization-guidelines

name	containerization-guidelines
description	Invoke BEFORE writing any Dockerfile or containerizing an app for deployment. Language-agnostic image-build conventions — multi-stage builds, non-root, layer caching, healthcheck, and hadolint tooling.

Containerization Guidelines

Follow these before writing any Dockerfile or packaging an app into an image. Language-agnostic; adapt the build/run commands to the app's stack.

Base image

• Pin by digest or exact tag — never latest. FROM node:22.11-slim@sha256:....
• Smallest image that works: -slim / -alpine for runtimes, distroless or scratch for static binaries. Don't ship a full OS to run one binary.
• Use Context7 MCP for current Dockerfile syntax, base-image tags, and docker build/BuildKit flags — never rely on training data.

Multi-stage build

• Separate builder (compilers, dev deps, source) from the final runtime stage. Copy only the built artifact + runtime deps forward.
• Name stages (AS builder) and COPY --from=builder. Final stage carries no toolchain, no source, no dev dependencies.
• One concern per stage; don't split further than build vs runtime unless a real cache win exists.

Layer caching — order matters

• Copy dependency manifests and install deps BEFORE copying source, so code changes don't bust the dep layer: COPY package.json package-lock.json ./ → RUN install → COPY . ..
• Chain related RUN commands with && and clean caches in the same layer (apt-get ... && rm -rf /var/lib/apt/lists/*). A separate cleanup layer saves nothing.
• Pin dependency versions via lockfile; use the deterministic install (npm ci, pip install -r, go mod download).

Non-root & security

• Create and switch to an unprivileged user: RUN adduser -D app → USER app. Never run as root in the final stage.
• COPY --chown=app:app so files aren't root-owned. Read-only where possible.
• No secrets in layers or ENV — pass at runtime (--secret, mounted files, orchestrator secrets). ARG/ENV values persist in history.
• .dockerignore excludes .git, node_modules, secrets, local env files, build output — keeps context small and secrets out.

Runtime config

• WORKDIR set explicitly. EXPOSE the app port (documentation).
• Prefer exec-form ENTRYPOINT ["..."] / CMD ["..."] — shell form breaks signal handling (PID 1 won't get SIGTERM). Add an init (--init / tini) only if the app spawns children and won't reap them.
• HEALTHCHECK hitting a real readiness endpoint, with sensible --interval/--timeout/--retries.
• Config via ENV with safe defaults; nothing environment-specific baked into the image.

Architecture

• Keep the Dockerfile focused and readable; one image = one concern. Split into multiple Dockerfiles rather than one branching mega-file.
• Comments minimal — explain why (a non-obvious flag, a cache trick), never what.

Tooling — run before done

• Lint: hadolint Dockerfile (fix every warning or justify with an inline # hadolint ignore=DLxxxx).
• Build clean: docker build -t app:test . — must succeed with no warnings.
• Verify: run the image, confirm it starts as non-root (docker run --rm app:test id) and the healthcheck passes.

Laziness

• Official/verified base images over hand-rolled ones. Multi-stage over manual artifact juggling. BuildKit cache mounts (RUN --mount=type=cache) over custom cache scripts.
• No base image bigger than the job needs, no stage that doesn't earn a cache boundary, no tool in the final image the app doesn't run.