Upgrading

A new version arrives as a new signed bundle. It installs beside the current version, carries your data, settings and licence across, and leaves the previous version in place for a rollback. Nothing is downloaded, so updates work air-gapped.

Before you start

Read the release notes for every version between yours and the new one, in particular their Upgrading sections.
Copy the bundle to the server and check its SHA-256 against the one we sent.
The bundle must match the server's CPU: uname -m prints x86_64 or aarch64.
Make sure there is room for a second copy of the images beside the running ones.

Update with one command

From the directory of the installed version, as the account you installed with:

./lawliet update lawliet-docker-<version>-<organisation>.tar.gz
./lawliet status

In order, the command:

takes a database backup, and stops if that fails, because a rollback needs it;
checks there is room and unpacks the new bundle beside the current one;
verifies and loads the new bundle's images while the current version keeps running;
carries across .env, the deployment settings, the TLS certificate and the backups directory;
stops the running stack without touching its volumes and starts the new version from its own directory;
waits for health, then checks that the database is at the schema revision the new bundle carries and that the API reports the new version.

A bundle for the wrong CPU, a damaged image file or a full disk stops the update before the running stack is stopped, so the current version is untouched. If either final check disagrees, the command fails, says which, and points at the routes back.

Run later commands from the new directory; the command prints its path. The lawliet script there is the new bundle's own.

Upload the bundle from the console

Where the person holding the bundle is not the person with shell access, Settings > Platform updates > Install from a file takes the same archive. Uploading only stages it: before anything is written, the manifest's signature and every file in the archive are checked against it. Applying it is still done on the server with ./lawliet update --staged. Upload the archive exactly as you received it; repacking it changes the bytes the manifest describes, and the upload is refused.

Roll back

The previous directory is left in place, with its own images. Start it again and restore the backup the update took before it began:

cd <previous-directory>
./lawliet start
./lawliet restore backups/lawliet-<timestamp>.sql.gz

Going back from 1.5.11.s to 1.5.9.s or 1.5.10.s needs this restore too: 1.5.11.s moves the database schema forward, so the older version cannot simply be started against it.

Applying an older bundle over a newer database is refused on purpose: its backend does not know the newer schema and stops rather than guess. Restoring the backup is the supported route back.

Updating from 1.5.8.s or earlier: if the first update to a bundle with images fails, the old version's command suggests ./lawliet start --build. That needs the internet. Use plain ./lawliet start in the old directory instead; its images are still on the server.

From 1.5.9.s or 1.5.10.s to 1.5.11.s

1.5.11.s includes every 1.5.10.s fix, so a 1.5.9.s installation updates straight to it. Agents stay at 2.1.8.s and need no upgrade.

sudo ./lawliet update lawliet-docker-1.5.11.s-<organisation>.tar.gz
cd <the new directory the update names>
./lawliet status
sudo ./lawliet tls repair          # once, only if start or status warns

The certificate. From 1.5.11.s on, an update checks the certificate when it finishes. An update from 1.5.9.s or 1.5.10.s is run by the installed version's update, which predates that check, so the new version's start and status report the gap instead: certificate does not cover <ip>; run: sudo ./lawliet tls repair. Run it once from the new directory. With agents enrolled it lists them and asks first; give each the new certificate as described in when the server's certificate changes.
The database. Migrations apply automatically on start: each agent's enrolment scheme and clock offset, the remote-deployment checklist, enrolment codes for offline packages, and directory sign-in.
Encryption. The state is kept: an installation behind nginx reads as encryption on, and a plain-HTTP installation reads as off until sudo ./lawliet tls on.
Directory sign-in. The AD_* environment variables used by the earlier Active Directory login are no longer read. Configure directory sign-in in Settings > Authentication.
Going back. The schema moves, so returning to 1.5.9.s or 1.5.10.s means starting the previous directory and restoring the backup the update took; see Roll back.

The agents

Agents are upgraded separately from the server, with signed releases that can be hosted on the server itself. See agent upgrades.