Docker best practices

Use when authoring **Dockerfile**s, .dockerignore, image CI, or container runtime config for services in this monorepo.

Images and build stages

• Prefer multi-stage builds: compile or install in a builder stage, copy only artifacts into a minimal runtime image.
• Use small bases for runtime where possible (*-slim, distroless, or static binaries). Keep runtimes pin-aligned with local dev (Node and Rust versions should match engines, rust-toolchain.toml, or CI).
• Order Dockerfile instructions from least to most frequently changing so layer cache helps (dependency manifests before source, shared layers before app-specific).

Build context

• Keep .dockerignore aggressive: exclude VCS metadata, CI config, unrelated apps, build outputs, and secrets. A smaller context means faster builds and fewer accidental leaks into layers.
• Avoid COPY . . without a strong ignore file; prefer explicit COPY lists when the repo layout is stable.

Reproducibility

• Use lockfiles (pnpm-lock.yaml, Cargo.lock) and flags like pnpm install --frozen-lockfile and cargo build --locked in CI and images.
• Pin base image digests in production pipelines when you need byte-stable rebuilds (optional for dev images).