dockerfile

Dockerfile

Goal

Create Dockerfiles that are secure, reproducible, and useful as the canonical local CI build. Prefer multi-stage builds unless the user explicitly asks for a single-stage file.

Decision Order

1. Identify the final runtime artifact.
2. If the output is a single static binary, aim for a scratch final image.
3. If the output needs an interpreter, shared libraries, package files, or runtime dependencies, aim for an Alpine final image such as python:<version>-alpine, node:<version>-alpine, or plain alpine.
4. If Alpine is incompatible with required native dependencies, explain why and choose the smallest appropriate runtime base.
5. Keep build tools, test tools, package managers, and source code out of the final image unless they are required at runtime.

Required Container Policy

• Add ARG UID=10001 and ARG GID=10001 in every stage that creates or owns files used by the runtime image.
• Run the final container as non-root with USER ${UID}:${GID} or a named user created from those args.
• Ensure every file used by the final executable is owned by the runtime UID/GID. Prefer COPY --chown=${UID}:${GID} for final-stage copies.
• For scratch, use numeric USER ${UID}:${GID} and copy only required files: the static binary, CA certificates when outbound TLS is needed, and any minimal config/data files the binary actually reads.
• For Alpine runtime images, create the user/group from UID and GID, then copy application files with that owner.
• Set a narrow WORKDIR; do not run from filesystem root.
• Use exec-form ENTRYPOINT or CMD.

Build And Test Pattern

• Use a dedicated build stage for compilation, dependency installation, and generated artifacts.
• Add a test stage when the project has a clear test command. Examples: go test ./..., cargo test --locked, npm test, pytest.
• Make the default Docker build exercise tests when practical by having the production stage depend on the tested artifact path, or document: docker build --target test ..
• Keep the Dockerfile sufficient for local CI verification so GitHub Actions can usually be a simple docker build plus optional image push.
• Use BuildKit cache mounts when they improve repeat builds and the project already assumes BuildKit.