Backup and restore

This page covers a Quasar-owned install. A legacy Compose install keeps its secrets in deploy/.env and runs the same commands through Compose.

What holds state

Where	What	Losing it means
The database (quasar-postgres-data, or your own)	Everything: users, apps, hosts, sessions, app access, settings, the apply history.	Total loss.
The managed home root	Users’ saves and installed content.	Users lose their saves.
quasar-machine, on each machine	Generated secrets (QUASAR_SECRET_KEY, the database password), update records, pre-update dumps.	Stored credentials become unreadable; the recovery actor can’t act on that machine.
quasar-control-data	TLS certificate, artwork cache.	A new certificate; clients re-trust.
quasar-agent-data, on each GPU host	The agent’s node secret.	Re-enroll the host with QUASAR_RESET_IDENTITY=1 (details).

The first three matter. The last two regenerate.

Never delete the `quasar-machine` volume

QUASAR_SECRET_KEY can’t be recovered, and there is no command to reset the generated database password. Quasar can’t copy machine state off the machine, so back up the database and the homes.

Backing up the database

With Quasar’s own database, on the first machine:

docker exec quasar-postgres \
  pg_dump -U quasar -Fc quasar > quasar-$(date +%Y%m%d-%H%M).dump

Copy it off the machine. Do this on a schedule, ideally while no sessions are running.

Before an update that migrates the database, the recovery actor also takes a dump into quasar-machine and keeps the last three. If it can’t, the update is refused (backup_failed) and nothing changes. List them with:

docker exec quasar-recovery quasar-recovery restore --list

These stay on the machine, so keep your own copy too.

Your own Postgres: back it up your usual way. Quasar never dumps, restores or resets it. Before a migrating update, the console asks you to confirm a current backup (backup_unconfirmed otherwise).

Backing up saves

The home root is a plain directory:

tar -czf quasar-homes-$(date +%Y%m%d).tar.gz -C /var/lib/quasar homes

It will be large. Back up every host’s root if they differ. For a shared root, test the restore from each GPU host.

Restoring

This returns the first machine to the control plane it ran before a migrating update. A failed update prints the command, filled in:

docker exec quasar-recovery quasar-recovery restore --dump <name> --to <version>

<name> comes from restore --list; <version> is the control-plane version the dump was taken under. The restore verifies the dump, stops the control planes, loads it into a fresh database and starts that version. It is safe to rerun if interrupted. After a success, rerunning is refused; --force-again restores the same dump anyway, discarding everything written since.

With your own database, stop the control plane, restore your backup, then start the matching version:

docker stop quasar-control-plane
# restore your own backup into your database
docker exec quasar-recovery quasar-recovery restore --to <version>

restore only loads the recovery actor’s own dumps, or a Compose install’s dump into a fresh install (Move a Compose install). Loading your own dump into a running owned install is not a documented procedure.

Restore homes separately, then check the health endpoint, that hosts registered, and a real session.

Going back to an earlier release always means restoring a dump taken before the migration. See the hard rule.

Developer restore rehearsal

For contributors, in a disposable environment. It never touches a deployed database:

bash deploy/db-backup-restore-drill.sh

It seeds a database, dumps, restores into another, and checks schema, rows and startup. It proves the mechanism, not your backup: to trust a real dump, restore it into an isolated Postgres and start a control plane against it. See Testing and verification.

The apply history, and what Revert depends on

The database records every platform update, including the image digests each target ran before. Revert needs that record, so restoring an older database loses it: hosts keep running, but the console can’t say what to put them back to.

Each machine also keeps its own update record in quasar-machine:

docker exec quasar-recovery quasar-recovery status

Version compatibility

There is no compatibility matrix. Back up before every upgrade and restore forward; don’t roll back. See Upgrading.