Home › Docker › Docker & Compose AGENTS.md

Docker & Compose AGENTS.md

AGENTS.md for containerized projects: lean multi-stage Dockerfiles, Docker Compose for local dev, and image security.

AGENTS.mdDocker

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Docker and Compose

## Commands
- `docker compose up --build -d` · `docker compose logs -f <svc>` · `docker compose down` (no `-v` unless asked)
- Lint: `hadolint Dockerfile` if available. Scan: `docker scout cves <image>` or `trivy image <image>`.

## Dockerfiles
- Multi-stage builds: a `build` stage with dev deps, a small runtime stage (`-slim`, `distroless`, or `alpine` if the stack supports musl).
- Pin base images to a specific version tag (e.g. `node:22.11-slim`), not `latest`.
- Order layers for caching: copy lockfiles, install deps, then copy source. Use `RUN --mount=type=cache` for package caches.
- Maintain `.dockerignore` (`.git`, `node_modules`, `.env`, build output).
- Run as a non-root `USER`. Add a `HEALTHCHECK` or a compose `healthcheck`.
- One process per container; use exec-form `CMD ["node","server.js"]` so signals reach it.
- No secrets in `ENV`, `ARG`, or copied files; use build secrets (`--mount=type=secret`) or runtime env.

## Compose
- File is `compose.yaml`; no top-level `version:` key.
- Services depend with `depends_on: { db: { condition: service_healthy } }`.
- Config through `env_file: .env` (gitignored) with a committed `.env.example`.
- Named volumes for data; bind mounts only for source in dev. Use `develop.watch` for live sync if set up.

## Done
Image builds, `docker compose up` reaches healthy, and the image size is noted in the summary.