Backups that survive a container upgrade
A practical way to capture and restore stateful Docker services.
This note documents a practical approach used in Steppe Infrastructure Notes. The goal is a setup that can be explained, reproduced, and checked from outside the machine.
Back up data, not wishes
A compose file describes how to start a service, not the state inside its volumes. Dump databases with their native tools and copy configuration separately. Avoid storing credentials in the same archive as application data.
docker compose exec -T db pg_dump -U app app > app.sqlUse consistent restore steps
Record image versions, volume names, and the order in which services must start. A restore performed on an empty host exposes assumptions that remain invisible when restoring over an existing installation.
docker compose config --images
docker volume lsProve the restore
Run the application against restored data and perform an actual user-level request. A successful dump command only shows that bytes were written; it says nothing about whether the application can use them.
docker compose up -d
curl -fsS https://service.example/health