Skip to main content

Upgrade and backup

Applies to: SimpleTwo 0.9.x · Checked: 20.09.2026

1. The order​

Coordinator first, roles second. Role binaries live inside the coordinator's image: until it is upgraded, "redeploy the role" installs the version you already have.

Step 1. The coordinator — a new image tag:

cd /opt/simpletwo
sed -i 's|:v[0-9.]*$|:v0.9.240|' .env      # only the tag changes
docker compose pull && docker compose up -d
curl -fsS http://127.0.0.1/healthz
curl -fsS https://<address>/v1/version

Step 2. The roles — Redeploy on each host in the console. Roles can be done one at a time: installation follows the same description as the first time, and repeating it breaks nothing.

Step 3. Clients update themselves: macOS from the update feed, the stores their own way, the APK from the download page. There is no need to chase the fleet; the console shows who is still on what.

A green job and a running container are not a working service

A deploy is not finished until the service answered /healthz and /v1/version reported the version you were deploying. This is not belt-and-braces: half of all "mysterious" investigations start with production running the previous version while everybody looks at the new one.

2. Rollback​

The same file with the previous tag; earlier images stay in the registry.

sed -i 's|:v[0-9.]*$|:v0.9.239|' .env && docker compose up -d

Roles roll back the same way — Redeploy after the coordinator is rolled back.

A rollback does not restore data. If the version changed the database schema, rolling back returns the code and not the rows: that is a case for restoring from a copy, not for moving a tag.

3. What to copy​

Four things, and the first two are not one:

WhatWhereWith what
The coordinator's data volumethe coordinator hostcontrol-plane database, certificates, published builds
The master key filethe coordinator host, outside the data volumethe only thing that opens an encrypted database
The Postgres databasesthe postgres host or your clusterscheduled pg_dump
Object storage / attachmentsthe s3 role, external storage or the messaging diskyour storage's own tools; with the drive role the simpletwo-drive bucket is the largest thing backed up (files)
The key and the data go to different places

A copy of the data volume without the key file will not open. A copy of the data volume together with the key, kept in one place, means one stolen copy is both the data and the key to it. So the key lives outside the data directory and is copied separately, with its own access. The recovery sheet printed when encryption was enabled is a third copy of the same truth, and it belongs where the organisation keeps paper secrets.

4. Restore​

The reverse of installation:

  1. bring up a coordinator of the version the copy was taken from and restore the data volume;
  2. put the key file back at its old path (ST_KEYSTORE_PATH) — before the services start;
  3. restore the Postgres databases;
  4. restore object storage;
  5. redeploy the roles from the console — they will take the current description;
  6. verify with a whole scenario rather than one /healthz: sign in, a message to a second device, a one-to-one call, a meeting with an external participant, the tunnel.
A copy on the same disk is not a copy

Until there is external storage, the minimum is a daily copy to another host and a weekly export off-site. And test the restore once, at launch, not on the day it is needed: an untested copy is an assumption, not a backup.

5. What updates itself​

WhatHow
Let's Encrypt certificatesrenewed automatically; on failure there is a backoff and an "issue now" button
Built-in routing listsrefreshed with the product version, until you edit them
The macOS clientfrom the update feed
OS packagesunattended-upgrades on hosts where it is enabled

Next​