# AGENTS.md — Docker

Dockerfile authoring rules, from Docker's official best practices.

- Use multi-stage builds; ship only runtime artifacts in the final stage (`COPY --from=…`).
- Choose a minimal official/verified base image; pin the version and digest.
- Don't install unnecessary packages.
- Order instructions least-changing → most-changing; install deps before copying source.
- Combine related commands into one `RUN`; clean up in the same layer.
- For apt: `apt-get update && apt-get install -y --no-install-recommends …` in one `RUN`, then `rm -rf /var/lib/apt/lists/*`.
- Sort multi-line arguments alphanumerically.
- Prefer `COPY` over `ADD`; reserve `ADD` for checksummed remote URLs or tar auto-extraction.
- Use exec form for `CMD`/`ENTRYPOINT` (`["bin","arg"]`); `exec "$@"` in entrypoint scripts so the app is PID 1.
- Use absolute `WORKDIR` paths instead of `RUN cd …`.
- Run as a non-root `USER` when privileges aren't needed.
- Never bake secrets via `ENV`/`ARG`/`COPY`; use `RUN --mount=type=secret`.
- Add a `.dockerignore` to exclude `.git`, secrets, and build cruft.
- One concern per container; keep containers ephemeral and stateless.
- Rebuild often with `--pull` to pick up security patches.