loadout: Instructions file for GitHub Copilot

Dockerfile Engineering Instructions (container image development) 🐳

These instructions define the default engineering approach for writing production-grade Dockerfiles and Docker Compose files for development.

They must remain applicable to:

• Application container images
• Base/foundation images
• Tool wrapper images
• Multi-stage build images
• Development and CI/CD images
• Docker Compose multi-service development environments

They are non-negotiable unless an exception is explicitly documented (with rationale and expiry) in an ADR/decision record.

Cross-references. For Makefile orchestration conventions that build Docker images, see makefile.instructions.md. For shell scripts that wrap Docker commands, see shell.instructions.md. This file focuses on Dockerfile patterns and Docker Compose for development.

Identifier scheme. Every normative rule carries a unique tag in the form [DF-<prefix>-NNN], where the prefix maps to the containing section (for example QR for Quick Reference, STR for Structure, FROM for Base Image, ARG for Build Arguments, ENV for Environment Variables, RUN for Run Instructions, COPY for Copy Instructions, META for Metadata, SEC for Security, OPT for Optimisation, CMP for Compose). Use these identifiers when referencing, planning, or validating requirements.

---

0. Quick reference (apply first) 🧠

This section exists so humans and AI assistants can reliably apply the most important rules even when context is tight.

• [DF-QR-001] Pin base image versions: never use a literal latest tag anywhere in the Dockerfile, including in ARG defaults; pin to a specific version with digest where possible ([DF-FROM-001], [DF-FROM-002]).
• [DF-QR-002] Instruction order: FROM → ARG → ENV → RUN (install) → COPY → RUN (configure) → VOLUME → EXPOSE → WORKDIR → USER → CMD/ENTRYPOINT → Metadata ([DF-STR-001]).
• [DF-QR-003] Multi-line RUN with set -ex: start RUN blocks with set -ex or set -ex; for debugging and fail-fast behaviour ([DF-RUN-001], [DF-RUN-002]).
• [DF-QR-004] Build dependencies pattern: define, install, use, then purge build dependencies in a single RUN layer ([DF-RUN-004]–[DF-RUN-006]).
• [DF-QR-005] Clean up in every RUN: remove temp files, package manager caches, and build artefacts at the end of each RUN ([DF-RUN-007]).
• [DF-QR-006] Metadata at the end: place OCI-compliant LABEL instructions at the very end of the Dockerfile ([DF-META-001]–[DF-META-003]).
• [DF-QR-007] Use mise.toml for pinning: define image versions in mise.toml's [_.docker]/[tools] tables and reference them through an ARG ..._VERSION default, for reproducibility ([DF-FROM-003]).
• [DF-QR-008] Lint with hadolint: all Dockerfiles must pass hadolint with no errors or warnings ([DF-QG-001]).
• [DF-QR-009] Non-root user: run containers as non-root where possible ([DF-SEC-001]).
• [DF-QR-010] Minimal layers: combine related commands to reduce layer count and image size ([DF-OPT-001]).
• [DF-QR-011] Docker Compose for development: use compose.yaml with healthchecks, secrets, custom networks, and Compose Watch for hot-reload ([DF-CMP-001]–[DF-CMP-030]).
• [DF-QR-012] Integrity and least privilege: verify downloaded artefacts and lock down ownership/permissions at build time ([DF-SEC-009]–[DF-SEC-011]).