Skip to content
T1KTheOneKit

docker-volume-discipline

Docker Volume Discipline — Named Volumes for State, Audit Before Prune

Section titled “Docker Volume Discipline — Named Volumes for State, Audit Before Prune”

Rule

Section titled “Rule”
  1. Stateful compose services MUST use named volumes. Any docker-compose service with a persistent data directory (postgres, mysql, mongo, redis, rabbitmq, any DB/queue) MUST mount a named volume (declared under top-level volumes:) or an explicit bind mount for that directory. NEVER rely on the image’s implicit VOLUME — that silently creates an anonymous volume, which is indistinguishable from prune-able waste.
  2. NEVER blanket-prune anonymous volumes. Before removing dangling anonymous volumes (docker volume prune, docker system prune --volumes), audit each one for database fingerprints — PG_VERSION (postgres), ibdata1 (mysql), WiredTiger (mongo), dump.rdb / appendonly.aof (redis) — and EXCLUDE matches. Delete via an explicit docker volume rm <list> of verified-safe volumes, never a blanket prune.
  3. Compose fixes land in the owning repo. Converting a service to named volumes is a change to the owning project’s compose file — branch + PR in that repo. NEVER edit compose files in place on a host machine.

Why: anonymous volumes hide real data behind hex names — a blanket prune has destroyed live database data before. Named-volume example, the audit one-liner, and the conversion procedure: docs/docker-volume-discipline.md (also carries the incident).

Section titled “Related”
  • rules/preview-first-batch.md — smoke-test + confirm gate before bulk deletion
  • rules/kit-wide-fix-discipline.md — fixes land at the source repo, not locally
  • docs/docker-volume-discipline.md — the originating incident in full