Backup

Everything Companion keeps is in the data directory (/data in the container). A backup is a copy of that directory.

What is in it

companion.db        users, tenants, encrypted credentials, settings, sync state
master.key          the key that encrypts the credentials and the HTTPS private key
tenants/<key>/mpl_logs/<YYYY-MM>/     stored message logs, one directory per month
tenants/<key>/artifacts/artifacts.db  artifacts and their history

Keep master.key with every backup

The database cannot be used without the key it was written with: a server started with a key that does not match refuses to start. If you set COMPANION_MASTER_KEY instead of using the file, keep that value safe in the same way.

What cannot be fetched again after a loss: message logs older than 30 days, and the artifact history. Tenant connections can be entered again, and the current state of the artifacts is synced again from the tenant.

The simple way: stop and copy

Stop the container, copy the directory (or snapshot the volume), and start it again. Log sync catches up by itself: nothing is missed while the tenant still has the logs.

docker stop pizug-companion
docker run --rm -v pizug_companion:/data -v /backup:/backup busybox tar czf /backup/companion-$(date +%F).tar.gz -C /data .
docker start pizug-companion

While the server runs

Do not copy database files of a running server with cp or tar: a copy taken in the middle of a write can be unusable. Two commands write consistent copies while the server runs. Run them in the running container:

# one month of message logs of one tenant, as a complete, verified directory
docker exec pizug-companion /companion export --tenant prod --period 2026-09 --out /data/export/prod-2026-09

# the artifacts and their history of one tenant, as one file (.zst = compressed)
docker exec pizug-companion /companion export --tenant prod --artifacts --out /data/export/prod-artifacts.db.zst

companion verify DIR checks an exported or archived month against its manifest.

Months that are closed no longer change, so they can be copied as files at any time. Only the current month needs export. If you use an archive directory, every archived month there is complete and verifiable on its own.

Restore

1. Stop the container.
2. Put the directory back, master.key included.
3. Start a version that is the same as, or newer than, the one that wrote the backup.

To restore only the artifact history of a tenant, decompress the exported file and put it back as tenants/<key>/artifacts/artifacts.db while the server is stopped.

Moving to another server

Stop the container, copy the data directory to the new host, and start the same image there. Stored message logs stay readable by every future version.