Upgrade and undo

Upgrade your instance to a newer release from the owner dashboard, undo the last upgrade, and what happens when a step fails.

With the Compose stack, you upgrade Metis Suite from the owner dashboard. The updater service (the part of the stack that changes which release runs) does the work for you:

1. It downloads the release you choose.
2. It stops the app and takes a snapshot of the database, when your instance supports it (see below). A snapshot is a full copy of the database at that moment.
3. It runs preflight, the check that runs before the app starts. Preflight applies the new release’s changes to your database, then checks your settings.
4. It switches the app to the new release and waits until it answers.

If any step fails, the updater puts the snapshot back, if it took one, and switches to the release you had.

Releases install forward only. The dashboard offers only releases that are newer than the one you run. To go back, use Undo last upgrade. It returns to the release you had before your last upgrade, with the database as it was in the snapshot.

The Updates page exists only when the updater is connected, which the Compose stack does for you. On hosts that build from source, the page does not appear: update by deploying the new version there.

Snapshots need the bundled database

The updater can take a snapshot only when your instance uses the bundled database server. The bootstrap script sets this up unless you choose Turso.

If your databases are on Turso, or on a database server you run yourself (as in Install with Docker Compose), then:

• Upgrades still work, but there is no snapshot, and an upgrade cannot be undone.
• The Undo row on the Updates page reads Not available, and the page says “The database is not this stack’s sqld, so the updater cannot snapshot it and an upgrade cannot be undone. Back up the database before upgrading.”
• Back up your databases before every upgrade. See Backups.

See what is available

Open Dashboard, System, Updates.

• Running release shows the release every service of your instance runs.
  • The badge reads Up to date or Update available. When the images are not pinned to a release, there is no badge.
  • The Version row shows the version. If the images are not pinned to a release, it shows Not a pinned release instead, and upgrading pins them.
  • The Undo row shows the Undo last upgrade button when there is an upgrade to undo. Otherwise it reads None, or Not available when your instance cannot take snapshots.
• Releases lists the releases that are newer than the one you run, up to 10, newest first. The newest one is marked Latest. Each one has an Upgrade button, and a Release notes toggle when the release has notes.
  • If no newer release exists, the card says “No newer release is published.”
  • If your images are not pinned to a release, the card lists every published release, up to 10.

Read the release notes first

Click Release notes under a release to read what changed in it. Read the Upgrade notes section first, when the notes have one. It says what you need to do besides clicking Upgrade, such as running the bootstrap script again before you upgrade. See Releases that need the bootstrap script.

If you skip releases, read the notes of every release between yours and the one you install.

Upgrade

Pick the release

Click Upgrade next to the release you want. You can pick any listed release, not only the latest.

Confirm

The dialog says “The app restarts on that release. Open pages reconnect once it is ready.” Enter your authenticator code and click Upgrade. To use a backup code, click Use a backup code instead first.

Watch the progress

The Last upgrade card shows the move from the old version to the new one, and these steps:

1. Pull the release
2. Stop the app and snapshot the database
3. Run preflight and migrate the database
4. Switch the app
5. Wait until it is ready

Without snapshots, step 2 is not shown.

While the app restarts, the page says “The app is restarting. This page reconnects on its own once the new release answers.”

Reload

When the card shows Succeeded, a pop-up message says “Now running” with the new version, and the card says “Reload the page to use” that version. Reload the page to use the new release.

Only one upgrade or undo runs at a time. The buttons are turned off while one runs.

While an upgrade runs, your instance is offline for a while:

• With snapshots, the app stops at the snapshot step and comes back when the new release is ready. A large database takes longer to copy.
• Without snapshots, your current release keeps working while preflight runs. The app is offline only while it switches to the new release.

Undo the last upgrade

Undo last upgrade returns your instance to the release it ran before your last upgrade. It also puts back the database snapshot taken just before that upgrade, for both the app database and the AI memory database.

Everything written to the database after the snapshot is lost. That includes settings you changed, accounts and workspaces people created, and mail they scheduled.

Mail, events and files at the providers your users connected stay as they are. Undo does not reverse what your instance did at those providers after the upgrade, such as mail it sent. Scheduled work that ran after the upgrade is due again in the restored database and runs again soon after the undo. A scheduled message that was sent after the upgrade is sent a second time, and a scheduled workflow that ran since then runs once more. Snoozed messages whose wake time passed after the upgrade wake again.

The button appears only when all of these are true:

• Your instance uses the bundled database server, so it can take snapshots.
• Your last successful upgrade kept its snapshot.
• Before that upgrade, the Version row showed a release number, not Not a pinned release.
• You still run the release that upgrade installed.

To undo:

Check what you will lose

Under Running release, the page says which release undo returns to, and the date and time of the snapshot: “Everything written since then is lost.”

Confirm

Click Undo last upgrade. The dialog names the release and the snapshot time, and says the upgrade cannot be undone again. Enter your authenticator code and click Undo. To use a backup code, click Use a backup code instead first.

Watch the progress

The Last undo card shows these steps:

1. Pull the previous release
2. Stop the app and restore the database snapshot
3. Switch the app
4. Wait until it is ready

The app is offline until the last step finishes.

Reload

When the card shows Succeeded, a pop-up message says “Now running” with the previous version, and the card says “Reload the page to use” that version. Reload the page.

Undo works once. After it, the Undo row reads None until your next upgrade.

There is only ever one undo. Each successful upgrade replaces the snapshot, so you can undo only your most recent successful upgrade. A failed upgrade does not change it.

The snapshot is kept in /opt/metis-suite/.updater-snapshot/ on the server. Leave that folder alone if you want to keep the undo. If you delete it, the undo is gone.

The undo is recorded in the Audit log as Instance upgrade undone, with the two versions and the owner who started it. It also shows in your own Security activity. The row is written once the undo has succeeded and the Updates page loads again. If you closed the page during the undo, it is written the next time you open Updates. See Owner dashboard.

When a step fails

The card shows Failed, and a pop-up message says “The upgrade failed” or “The undo failed”. A note says what the updater did, and the error is shown below it. When preflight failed, the error includes the end of its output, which names the database change that failed.

In these examples, you ran 1.1.0 and upgraded to 1.2.0.

Needs attention

The card shows Needs attention when the updater could not get back to a working state:

• An upgrade failed, and switching back or starting your release again failed too.
• An undo failed partway.
• The updater stopped in the middle of an upgrade or undo.

When a snapshot exists, the error names the folder in /opt/metis-suite/.updater-snapshot/ that holds it. Do not delete that folder: it is the copy of your database from before the upgrade.

Check the stack on the server: which images .env pins, that the database server and the app are running, and the app’s log:

sudo grep _IMAGE= /opt/metis-suite/.env
sudo docker compose --project-directory /opt/metis-suite ps
sudo docker compose --project-directory /opt/metis-suite logs app

The updater is not answering

If the page shows The updater is not answering, the updater service is not running. Check it with:

sudo docker compose --project-directory /opt/metis-suite ps updater

Errors in the dialog

Releases that need the bootstrap script

Upgrades from the dashboard change only the app’s images. They never update the updater itself or the Compose file. A release’s Upgrade notes say when it needs either.

To pick up a new updater or Compose file, run the bootstrap script again. It updates the updater, downloads the Compose file of the release it installs, and pins every image to that release: the newest one, or the one in METIS_VERSION.

A bootstrap run is also an upgrade, but a different kind:

• It takes no snapshot, and it cannot be undone. Back up first. See Backups.
• Preflight still applies the release’s database changes.
• If the run moves your instance to a different release, it ends any undo that was waiting. The Undo row then reads None.

Going back further

Once a release has changed your database, an older release cannot run on it. If you pin older images, with METIS_VERSION on a bootstrap run or by editing .env, preflight refuses the database and the app does not start. The preflight log says the database has changes “which this release does not ship: a newer release migrated it.” To recover, pin that newer release again, or a newer one.

To go back, you have two ways:

• Undo last upgrade, while it is offered.
• Restore a database backup you took before the newer release, together with that older release. See Backups.