docker

Sub-Skill: Docker / Container Conventions

Purpose: Prevent common container mistakes — busted layer caches, bloated images, insecure defaults, and compose misconfigurations — before they reach CI or production.

---

Rules

Layer Ordering & Cache

1. Dependency layer first. Always install dependencies in a separate layer before copying application source, so a source change does not invalidate the package cache. Reference: ERR-2026-020
2. Copy only what's needed early. Before copying the full source tree, copy only the dependency manifest files (e.g., requirements.txt, package.json, pyproject.toml) so the install layer is cached independently.
3. Minimise layer count. Prefer chaining related RUN commands with && and \ continuations rather than issuing one RUN per command; each RUN creates a new layer.
4. Order by change frequency. Always place instructions that change rarely (OS packages, global tools) before instructions that change often (app source, config files).

Multi-Stage Builds

1. Use multi-stage for compiled artefacts. Always use a builder stage to compile or bundle, then copy only the final artefact into a minimal runtime stage; never ship build toolchains in the production image.
2. Name every stage. Use AS <name> on every FROM line so later stages and docker build --target calls are readable and stable.
3. Pin the runtime base image. Always pin base images to a specific digest or immutable tag (e.g., python:3.12.3-slim) in the runtime stage; never use latest in production Dockerfiles.

Security

1. Run as non-root. Always create a dedicated non-root user and switch to it with USER before the final CMD/ENTRYPOINT; never run application processes as root inside a container.
2. Never embed secrets in image layers. Never pass secrets via ARG or ENV in a Dockerfile; use Docker BuildKit --secret mounts or runtime environment injection instead.
3. Scan images before push. Before pushing any image to a registry, run an image vulnerability scanner (e.g., trivy image, docker scout) and fail the pipeline on critical CVEs.
4. Prefix docker run -v from Git Bash with MSYS_NO_PATHCONV=1. Always prefix docker run -v calls issued from Git Bash or MSYS on Windows with MSYS_NO_PATHCONV=1 to prevent path mangling. Reference: ERR-2026-013