Upgrading

The hard rule

Never run a control-plane image older than the database’s migration version. The control plane migrates Postgres at startup, and an older binary refuses to start against a newer database. A rollback needs both the older image and the database backup taken before the upgrade.

The console enforces this: it never offers a release below the database’s schema, and it always moves the control plane before any agent.

A release that changes the database empties the instance first

An update without a migration doesn’t end sessions. One with a migration drains the whole instance before the control-plane step, unless you tick the box to end sessions now. The confirmation says which case you’re in. Updating a host’s agent always ends that host’s sessions.

Upgrade from the console

This is the only upgrade path for a Quasar-owned install.

1. Read the notes under Admin ▸ Fleet ▸ Releases. The confirmation says whether the release migrates the database.

2. Check the database is covered. With Quasar’s own database, the recovery actor takes a dump first; if it can’t, the update is refused (backup_failed). With your own database, you must tick that you have a current backup (backup_unconfirmed otherwise). See Backup and restore.

3. Press Update Quasar, or Apply on a single host. The confirmation shows how many live sessions are affected.

4. Reload the console when it offers to.

5. Verify: hosts back online under Admin ▸ Fleet ▸ Hosts, then a real session. Container health doesn’t prove video, audio or input.

The control plane updates first, then each eligible host, drained in turn. Each machine’s recovery actor does the replacing; a control plane that never becomes healthy is put back automatically, unless the release migrated the database (see below). Hosts built from source are never offered updates.

Updating Quasar covers channels, eligibility, reverting a host and unattended updates. A legacy Compose install keeps its own by-hand recipe.

Release signatures

Optional, off by default. Quasar always installs the digests the release manifest pins. If you also want each machine to check the manifest’s signature, set these seed inputs (recorded at first install):

Variable	Values
QUASAR_UPDATER_SIGNATURE_MODE	off (default); verify refuses a bad signature but accepts unsigned; require also refuses unsigned releases, edge builds and developer applies.
QUASAR_UPDATER_TRUSTED_KEYS	<key-id>:<base64 public key>, comma-separated.

Change them later on each machine:

docker exec -it quasar-recovery quasar-recovery reconfigure --yes \
  QUASAR_UPDATER_SIGNATURE_MODE=verify QUASAR_UPDATER_TRUSTED_KEYS=<key-id>:<base64 public key>

• A mode with no trusted keys refuses every update.
• The signature is fetched from GitHub directly, without a proxy or private CA. Behind either, leave the mode off.
• Legacy Compose: see Legacy Compose installs.

Signing releases from your own fork and rotating keys are covered in the repository’s docs/upgrading.md.

If the control plane crash-loops after a rollback

Redeploy the newer control-plane image. To go back to the older release, you must also restore the pre-upgrade backup. Don’t hand-edit migration bookkeeping or run down migrations.

A migrating update is never undone automatically. If the new control plane fails to verify, it is left running and the failed attempt prints the command to go back:

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

With your own database, restore your backup first (control plane stopped), then run restore --to <version> alone. See Restoring.

Check the migration version on Quasar’s own database:

docker exec quasar-postgres \
  psql -U quasar -d quasar -c 'SELECT version, dirty FROM schema_migrations;'

On legacy Compose, run the same psql through docker compose -f deploy/docker-compose.yml exec quasar-postgres. dirty=true means a migration failed partway: investigate before upgrading again.

Contributor builds: two lanes

A machine is in one lane at a time.

• Contributor lane: a stack built from source with deploy/redeploy.sh, make redeploy-cp or make rebuild. Never updated from the console; it shows its deploy/redeploy.sh <va|nvidia> <ref> command instead. See GPU and remote workflows.
• Product lane: images built with deploy/build-images.sh, pushed to a registry you control, installed with the seed, and moved with a developer apply.

Developer apply

Admin ▸ Fleet ▸ Releases ▸ Developer apply applies image digests (never tags) to one owned host without publishing a release. It is admin-only, recorded in the apply history, and rolls back an agent that never becomes healthy.

• Images must be in a namespace listed in QUASAR_UPDATER_ALLOWED_NAMESPACES, on both the control plane and the target machine. A host installed with only the default namespace refuses a test registry.
• For a plain-HTTP test registry, set QUASAR_PLATFORM_INSECURE_REGISTRIES. Leave it unset in production.
• Both are seed inputs; change them later with reconfigure in the machine’s recovery actor (on the first machine this briefly restarts the console).
• Signature mode require refuses a developer apply.
• A GPU host takes its node agent, its recovery actor, or both. The first machine takes its control plane, optionally with its recovery actor. A combined host’s node agent is applied on its own.
• A migrating control-plane digest needs the same dump or backup confirmation as a release.

Multiple hosts must stay version-aligned

Upgrade the control plane and every agent as one operation. A permanently mixed fleet isn’t supported. A console fleet update does this in the right order.

Coming from a Compose install

A legacy Compose install isn’t converted in place: install fresh and load its database dump before first start. See Move a Compose install, or Legacy Compose installs to stay put.