Updates

Orbit updates itself from Settings → Orbit updates. Running install.sh again also works: it installs the latest release, or the one in ORBIT_VERSION, and checks the archive against SHA256SUMS, but unlike the console it does not check the signature.

Before it starts

An update only starts after a check with nothing blocking:

Check	Blocks when
Release signature	The release is not signed with the Orbit release key
Upgrade path	The release is not newer than the running version
Free disk	Less than 2 GB free for the download, the backup and the old binaries
Metadata backup	Never blocks; a warning when the last one is older than a day
Running operations	Deployments, backups or other operations are still running
Agent	The server's agent is offline

The console checks again right before starting, and only one update runs at a time.

What an update does

1. Backs up Orbit's data to /var/lib/orbit/backups/metadata/, the same archive orbit backup writes.
2. Downloads the release and verifies it: SHA256SUMS must carry a valid Ed25519 signature from the release key pinned in the running Orbit, and the archive must match its hash. An unsigned, tampered or incomplete release stops here, and nothing on the server has changed.
3. Restarts Orbit on the new version, keeping the previous binaries as orbit.previous and orbit-agent.previous. The console disconnects for a few seconds and reconnects on its own. Applications and databases keep running.
4. Applies the migrations in order, recording each one as it finishes.
5. Verifies the update: the schema, the API, the event stream and the server's agent.

The update can be cancelled while it backs up, downloads and verifies the release, not after.

If the new version never starts, a guard put in place before the restart brings the previous binaries and the pre-update backup back after 3 minutes, starts the previous version, and the console says why the update failed.

If an update is interrupted

If the console is not available, from the server:

sudo orbit status                                # version, installation, running operations
sudo systemctl restart orbit                     # resume: the running update continues from its last step
sudo orbit update rollback                       # put the previous binaries and the pre-update backup back
sudo journalctl -u orbit --since "1 hour ago"

• Resume when the cause was temporary (the server restarted, the disk filled up and was cleared). The update continues where it stopped, and migrations already applied are not applied again.

• Roll back when the release itself is the problem. Rolling back restores the backup taken by this update, so anything changed in Orbit after it started is lost. Applications and their databases are not touched.

• Reinstall a version by hand:

  curl -fsSL https://github.com/getcortexlabs/orbit-releases/releases/latest/download/install.sh | sudo ORBIT_VERSION=<version> sh

What an update does not cover

With one main server, Orbit's console is unavailable while it restarts, and an update cannot protect against losing that server. Keep an off-server copy of orbit backup.