---
description: Dockerfile authoring best practices (official)
globs: ["**/Dockerfile", "**/*.dockerfile"]
alwaysApply: true
---

- Multi-stage builds; final stage copies only runtime artifacts (`COPY --from=…`).
- Minimal official/verified base image, version + digest pinned. No `:latest`.
- Order instructions least-changing → most-changing; install deps before copying source.
- Combine related commands into one `RUN`; clean up in the same layer. Sort multi-line args.
- apt: `apt-get update && apt-get install -y --no-install-recommends …`, then `rm -rf /var/lib/apt/lists/*`.
- Prefer `COPY` over `ADD`. Reserve `ADD` for checksummed URLs / tar auto-extraction.
- Exec form for `CMD`/`ENTRYPOINT`; `exec "$@"` so the app is PID 1. Absolute `WORKDIR`.
- Run as non-root `USER` when privileges aren't needed.
- Never bake secrets via `ENV`/`ARG`/`COPY` — use `RUN --mount=type=secret`.
- Add a `.dockerignore`. One concern per container; keep them ephemeral.