---
name: dockerfile-review
description: Writes and reviews Dockerfiles for small, reproducible, secure images: pinned bases, multi-stage builds, cache-friendly layer order, non-root user, .dockerignore. Use when the user creates, edits or asks to review a Dockerfile or container image.
---

# Dockerfile Review

Write or review a Dockerfile so the image is small, reproducible, cache-friendly and safe to run. Read the whole Dockerfile, `.dockerignore`, the compose file (if any) and the app's dependency manifests before changing anything.

## Workflow

1. Identify the runtime (Node, Python, Go, Java ...), how the app starts, which port it listens on and which files it needs at runtime.
2. Check each item in the checklist below and note every violation with its line number.
3. Apply fixes with the smallest diff that solves each issue. Keep the existing style and stage names.
4. Build the image and run a smoke test (see Verification). Report the image size before and after if you can measure it.

## Checklist

### Base image
- Pin the tag to a specific version, never `latest`: `node:22.11-slim`, `python:3.12-slim`. For strict reproducibility add the digest (`@sha256:...`) and tell the user it needs periodic updates.
- Prefer slim or distroless variants. Use alpine only when the app has no native dependencies built against glibc (Python wheels and Node native addons often break on musl).
- Use the same base family for build and runtime stages unless a static binary makes that unnecessary.

### Multi-stage builds
- Put compilers, dev dependencies and build tools in a `builder` stage. Copy only the artifacts into the final stage with `COPY --from=builder`.
- The final stage must not contain source code, package manager caches, `.git` or test files unless the app needs them to run.
- Name stages (`FROM node:22.11-slim AS builder`) so the intent is readable.

### Layer cache order
- Copy dependency manifests first, install, then copy the rest of the source:

```dockerfile
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
```

- Combine `apt-get update` and `apt-get install` in one `RUN`, use `--no-install-recommends`, and remove lists in the same layer: `rm -rf /var/lib/apt/lists/*`.
- Order from least to most frequently changing. Put `ARG`/`ENV` that change per build late.

### Reproducible installs
- Node: `npm ci` (or `pnpm install --frozen-lockfile`), never `npm install`.
- Python: install from a lock file; use `pip install --no-cache-dir -r requirements.txt`, and `--require-hashes` when the requirements file contains hashes.
- Go/Rust/Java: build with the lock or vendor files present; do not fetch `latest` tools inside the build.
- Do not run `curl | sh` installers without pinning a version and verifying a checksum.

### Non-root user
- Create a user and switch with `USER` before `CMD`. Numeric ids work better with Kubernetes policies:

```dockerfile
RUN groupadd -g 10001 app && useradd -u 10001 -g app -m app
USER 10001:10001
```

- Make sure the files the app writes to are owned by that user (`COPY --chown=10001:10001`).
- Do not listen on ports below 1024 as non-root; use 8080 and map it outside.

### Secrets and build arguments
- Never put tokens, passwords or keys in `ENV`, `ARG`, `COPY` or `RUN` lines. `ARG` values stay visible in `docker history`.
- For private registries or private packages use BuildKit secrets: `RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci`.
- Never copy `.env`, `*.pem` or cloud credential files into an image. If one was already copied, tell the user to rotate that secret.

### .dockerignore
- It must exist and exclude at least: `.git`, `node_modules`, `.env*`, `*.log`, build output, test artifacts, IDE folders, local virtualenvs.
- A missing `.dockerignore` makes `COPY . .` leak secrets and bust the cache on every edit.

### Runtime hygiene
- Use the exec form for `CMD`/`ENTRYPOINT` (`["node", "server.js"]`) so signals reach the process; add `tini` or `--init` if the app spawns children.
- Add a `HEALTHCHECK` when the image runs outside an orchestrator that has its own probes. Use a tool that exists in the image (do not assume `curl` in a slim image).
- Set `WORKDIR` explicitly. Set `NODE_ENV=production` / `PYTHONUNBUFFERED=1` style variables where relevant.
- Use `EXPOSE` for documentation, and `LABEL` for source and version if the team uses them.

## Verification

```bash
docker build -t app:review .
docker image ls app:review
docker image inspect --format '{{.Config.User}}' app:review   # must not be empty, root or 0
docker history --no-trunc app:review     # look for leaked values
```

If a linter such as `hadolint` is installed, run it and report its findings. Do not install tools without asking.

## Output format

Report back:
1. A list of findings, each as `severity | line | problem | fix`, sorted by severity (security first).
2. The changed Dockerfile or a diff.
3. Build result, image size, and the user the container runs as.
4. Anything you could not verify (for example, no Docker daemon available).

## Pitfalls

- Do not "fix" size by deleting files in a later layer; deleted files still exist in earlier layers. Remove them in the same `RUN`.
- Do not add `--platform` or change architectures unless the user asked.
- Do not remove a `HEALTHCHECK` or a non-root user that the project already has.
- Do not push images or tag to a registry without explicit confirmation.
- A change of base image major version can break the app; build and run it before declaring success.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
