dockerlisted

# docker An agent writing a container gets the same three things wrong every time: it runs as **root**, it bakes **secrets into layers**, and it copies the whole tree before installing dependencies so the **cache never hits**. All three are mechanical, all three are checkable, none of them require judgment. ## First: which situation is this? **Existing setup → orient before touching anything.** Read `references/runbook.md` § *Inheriting an existing setup*. A working container you find ugly beats a beautiful one that no longer boots, and the odd choices usually encode a constraint you cannot see yet. Run `docker compose config` (the *resolved* file - rarely what the YAML appears to say), then the linter, then **triage**: host-escape grants first, baked secrets second (and **rotate** them - deleting the line does not un-publish the layer), root user third, size and cache last. Do not silently "clean up" a two-year-old Dockerfile as a side effect of an unrelated task. **Cold start → scaffold.** Read `references/scaffold.md`: multi-stage templates for Python/Node/Go, the `.dockerignore` that comes first, dev-vs-prod compose, and how to pick a base image. They already pass the linter. Then, either way: 1. **Write / change it** against the rules below. 2. **Operate it** - `references/runbook.md`: build flags, debugging a running container, decoding exit codes (137 is OOM and looks like nothing at all), fat images, dead caches, reclaiming disk without deleting your dev d