How-to guide
Upgrade Sovrain
Build a newer Sovrain image, back up, and replace the running container, knowing what changes on start and how to go back.
This guide replaces a running Sovrain node with a newer version built from newer source. In the examples the old
image is sovrain:2026-11-17 and the new one sovrain:2026-12-01.
A node serves its region alone, so nobody can sign in to the organizations on it while it restarts. On the landing node, registration stops as well. Plan the upgrade for a quiet time. Why there is no second node to take over: About running Sovrain yourself.
Before you start
- Update your checkout of the Sovrain source tree to the version you want.
- Have a place to put a backup of the volume.
Upgrade the node
Build the new image from the root of the source tree, while the old node keeps running:
docker build -f internal-apps/idp/Dockerfile -t sovrain:2026-12-01 .Stop the node and remove the container. The volume stays.
docker stop --time 60 sovrain && docker rm sovrainSovrain finishes requests in flight for up to 30 seconds and then sends queued emails for up to 10, so give it more than Docker’s default of 10 seconds.
While the node is stopped, back up the volume. This copy is your only way back. See Back up the data volume.
Start the new image with the same volume and the same environment file:
docker run -d --name sovrain --restart unless-stopped \ -p 443:8443 \ -v sovrain-data:/data \ --env-file /etc/sovrain/sovrain.env \ --health-cmd 'curl -fsS http://localhost:8080/ready || exit 1' \ --stop-timeout 60 \ sovrain:2026-12-01Keep
IDP_MEKandIDP_CSRF_SECRETunchanged. With another master key the node does not start; with another CSRF secret, forms people have open stop working.Watch the start:
docker logs -f sovrain docker exec sovrain curl -s http://localhost:8080/readyThe TLS certificate is kept on the volume, so the node serves HTTPS again as soon as it is up.
Sign in to an organization and open its admin area to check that it works.
If the new version does not start
Sovrain updates the node database node.sqlite before it serves anything, and each organization’s database the first
time it is opened. If the node database cannot be updated, the node does not start; if an organization’s database
cannot, that organization cannot be opened while the others keep working. The log names the change that failed. Go
back as below.
Never run two containers on one volume: only one process may update a database at a time. If a node was killed while
it updated its node database, every start fails with
the changelog lock stayed taken for 30 s, held by idp-rust (pid …). Restore the backup from step 3, as described in
Restore a node from a backup.
What Sovrain checks when it updates a database: Schema updates.
Go back to the previous version
Sovrain does not undo schema changes, and an older version is not made to run on a database a newer version has changed. To go back:
- Stop and remove the new container.
- Restore the backup from step 3, as described in Restore a node from a backup.
- Start the old image,
sovrain:2026-11-17, with the same environment file.
Everything that happened between the backup and the rollback is lost.
If you run several regions
Upgrade one node at a time; each region is unavailable only while its own node restarts. Upgrade every node in the same maintenance window: no compatibility between nodes of different versions is promised. See Add a region.