Backup and upgrade

What to back up, how to restore, and how to move to a new release.

What to back up

What	Where	Why
Database	volume `mariadb-data`	everything Polaris knows
Application key	`storage/app/.app_key` in volume `polaris-storage`	decrypts satellite secrets, TOTP secrets, channel settings
Storage	volume `polaris-storage`	archived reports, report logos
`.env`	next to `docker-compose.yml`	configuration and passwords

A consistent database dump while Polaris runs:

docker compose exec -T mariadb sh -c 'mariadb-dump --single-transaction -u root -p"$MARIADB_ROOT_PASSWORD" "$MARIADB_DATABASE"' | gzip > polaris-$(date +%F).sql.gz

Satellites need no backup: they are disposable. Their /data volume only holds plans (synced again) and results not yet uploaded.

Restore

Restore .env and the polaris-storage volume (with .app_key).
Start only MariaDB, import the dump.
docker compose up -d. The web container migrates the schema if the dump is older than the image.

Upgrade

docker compose pull
docker compose up -d

Migrations run on start of the web container (POLARIS_AUTO_MIGRATE). Set it to false to run docker compose exec web php artisan migrate --force yourself.
Read the release notes for changes of .env variables; configuration always lists the current set.
Upgrade satellites by starting the new Pulsar image with the same volume and variables. The satellite list marks satellites running another version.
Upgrade the documentation image to the same version.