Docker & Containers

Pathrule2 Rules • 2 Memories • 1 Skill

A ready-to-use bundle of rules, memories, and a review checklist for authoring production Dockerfiles. It encodes 2026 best practices: multi-stage builds, non-root minimal runtimes, BuildKit cache mounts, a tight .dockerignore, and meaningful healthchecks so your agent stops generating bloated, root-running images.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

Use multi-stage builds with a minimal non-root runtime

Keep build context small and cache-ordered

Healthchecks must use exec form and match the runtime

docker-containers-review

deploy/

BuildKit and CI cache strategy for fast rebuilds

Rules

Use multi-stage builds with a minimal non-root runtime/roothighstrictEvery production Dockerfile must end in a slim, non-root final stage.

1	Split build and runtime into separate stages so build tools never reach the final image.
2
3	- Build in a full stage (for example `node:22` or `golang:1.24`), then `COPY --from=build` only the artifacts into a minimal final stage like `-slim`, `alpine`, or a `distroless` `:nonroot` image.
4	- Create and switch to a non-root user with an explicit UID and add a `USER` directive before `CMD`; copy artifacts with `COPY --chown` so they are owned correctly.
5	- Pin base images by major version or digest; never ship `latest` to production.

Keep build context small and cache-ordered/roothighadvisoryMaintain a .dockerignore and order layers stable-to-volatile.

1	Order Dockerfile instructions so rarely changing layers come first and the build context stays tiny.
2
3	- Commit a `.dockerignore` that excludes `node_modules`, `.git`, build output, secrets, and local env files so they are never sent to the builder.
4	- Copy the dependency manifest (`package.json`, `go.mod`, `requirements.txt`) and install before `COPY . .`, so a code change does not invalidate the dependency layer.
5	- Use BuildKit cache mounts for package managers, for example `RUN --mount=type=cache,target=/root/.npm npm ci`, with `sharing=locked` for apt.

Memories

Healthchecks must use exec form and match the runtime/rootPick a healthcheck the final image can actually run.

1	Add a `HEALTHCHECK` so the orchestrator knows when the container is ready, but match it to the runtime you shipped.
2
3	- Use the JSON exec form, for example `HEALTHCHECK CMD ["node", "healthcheck.js"]`; the shell form fails on `distroless` images that have no shell.
4	- `curl` and `wget` are absent from `distroless` and minimal images, so ship a tiny in-language probe instead of shelling out.
5	- Tune `--interval`, `--timeout`, `--start-period`, and `--retries` to the service: fast checks for latency-critical APIs, slower checks for background workers.

BuildKit and CI cache strategy for fast rebuilds/deployCombine layer cache, cache mounts, and a registry cache backend.

1	BuildKit is the default builder; layer order plus cache mounts plus a remote cache backend is what cuts CI times by 70 to 85 percent.
2
3	- Layer cache is all-or-nothing per instruction; cache mounts (`--mount=type=cache`) persist a package store across builds so only new deps download when a manifest changes.
4	- In CI, push and pull a registry cache with `--cache-to type=registry` and `--cache-from` so ephemeral runners reuse prior layers.
5	- The dependency-first layout and a tight `.dockerignore` are the two highest-leverage changes; add multi-stage and cache backends on top.

Skills

docker-containers-review/rootPre-merge checklist for any new or changed Dockerfile.

1	---
2	name: docker-containers-review
3	description: Review checklist for production Dockerfiles covering multi-stage builds, non-root runtime, layer caching, .dockerignore, and healthchecks. Run before merging any Dockerfile change.
4	---
5
6	# Docker & Containers review
7
8	- [ ] Dockerfile uses multi-stage builds; the final stage contains only runtime artifacts, no build tools or dev dependencies.
9	- [ ] Base images are pinned by major version or digest, not `latest`.
10	- [ ] A non-root user is created with an explicit UID and a `USER` directive precedes `CMD`/`ENTRYPOINT`.
11	- [ ] Artifacts are copied with `COPY --chown` so the non-root user owns them.
12	- [ ] Dependency manifests are copied and installed before `COPY . .` to preserve the dependency cache layer.
13	- [ ] A `.dockerignore` excludes `node_modules`, `.git`, build output, secrets, and local env files.
14	- [ ] BuildKit cache mounts are used for package managers (with `sharing=locked` for apt).
15	- [ ] A `HEALTHCHECK` is defined in JSON exec form and uses a probe the final image can actually run.
16	- [ ] No secrets are baked into layers via `ARG`/`ENV`; build secrets use `--mount=type=secret`.
17	- [ ] CI build pushes/pulls a registry cache (`--cache-to` / `--cache-from`) for fast rebuilds.

Why this pattern

AI agents tend to emit single-stage, root-running, uncached Dockerfiles that are large, slow to build, and insecure in production.

Built for Backend and platform teams shipping containerized services to production.

Keeps your assistant from:

Single-stage images that bake build tools and dev dependencies into the runtime
Containers that run as root because no USER directive was set
Cache-busting layer order that forces a full dependency reinstall on every code change

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-06-09