Backup and Restore

Backup and Restore

This repo ships no backup mechanism. There is no backup service in docker-compose.yml, no scheduled job, no dump script, and no retention setting anywhere in the repo. What follows is operator guidance built only on what the Compose file actually creates.

What state exists

State	Where	Back it up?
All ingested fleet data	Docker named volume postgres_data, mounted at /var/lib/postgresql/data in the postgres container	Yes — this is the only durable data
Secrets and stack config	.env on the host, next to docker-compose.yml	Yes — losing DB_PASSWORD locks you out of the volume above
Application code and schema	The container images and schema/init.sql in git	No — reproducible from the tag

api and web are stateless. Nothing else in the stack writes to a volume.

With the default Compose project name the volume is reportmate_postgres_data. Confirm before you script anything against it:

docker volume ls --filter name=postgres_data

Backing up the database

The straightforward approach is a logical dump taken through the running container. Nothing publishes port 5432, so run pg_dump inside it:

docker compose exec -T postgres pg_dump -U reportmate -Fc reportmate > reportmate-$(date +%F).dump

Store that alongside a copy of .env, in a location that is not the appliance itself. Both files are sensitive: the dump contains your whole inventory, and .env contains every secret the stack uses.

Schedule it with cron or a systemd timer on the host — that scheduling is yours to write; the repo provides none.

Restoring

Restore into a stack whose database has been initialised but holds no data you want to keep.

Bring the stack down and discard the existing volume:

docker compose down -v

Restore the same .env you backed up, then start only Postgres so nothing writes while you load:

docker compose up -d postgres

Wait for it to report healthy in docker compose ps, then load the dump:

docker compose exec -T postgres pg_restore -U reportmate -d reportmate --clean --if-exists < reportmate-2026-06-01.dump

Then start the rest:

docker compose up -d

Restoring onto a different tag

The API applies its own migrations and index/settings creation at startup, so restoring an older dump under a newer image tag is the expected upgrade path rather than a special case. Restoring a newer dump under an older image is not supported — migrations do not run backwards. See Upgrading.

Volume snapshots

Copying the postgres_data volume directory wholesale is only safe with the postgres container stopped, and the copy is tied to that Postgres major version. Prefer pg_dump. If you snapshot the appliance VM instead, snapshot it powered off for the same reason.