How-to guide
Restore a node from a backup
Bring a Sovrain node back from a copy of its data volume, on the same server or on a new one.
This guide brings a Sovrain node back from an archive made as in Back up the data volume:
after a failure, after an upgrade you want to undo, or on a new server. In the examples the volume is
sovrain-data, the container is sovrain and the archive is /srv/backups/sovrain-data-20261117-0330.tar.gz.
Everything that happened after the backup is lost, including organizations created since then.
Before you start
- The node’s environment file, above all its
IDP_MEK. With another master key the node refuses to start withIDP_MEK is not the MEK this data was encrypted with. KeepIDP_CSRF_SECRETas well; with another one, forms people have open stop working. - The Sovrain image of the version that made the backup. A newer version also starts on it and updates the data as in Upgrade Sovrain; an older version is not made to run on data a newer one has changed.
Restore on the same server
Stop and remove the container:
docker stop --time 60 sovrain && docker rm sovrainEmpty the volume and unpack the archive into it:
docker run --rm -v sovrain-data:/data -v /srv/backups:/backup debian:bookworm-slim \ sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/sovrain-data-20261117-0330.tar.gz'Start the node with the same environment file and the same
docker runcommand as in step 6 of Run Sovrain with Docker.Watch the start:
docker logs -f sovrain docker exec sovrain curl -s http://localhost:8080/readyThe TLS certificate is part of the backup, 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.
Restore on a new server
Prepare the server as in Run Sovrain with Docker: Docker, the image from step 3 of that guide, and the old node’s environment file at
/etc/sovrain/sovrain.env.Copy the archive to the new server, here into
/srv/backups.Create the volume and unpack the archive into it:
docker volume create sovrain-data docker run --rm -v sovrain-data:/data -v /srv/backups:/backup debian:bookworm-slim \ tar -C /data -xzf /backup/sovrain-data-20261117-0330.tar.gzStart the container with the same
docker runcommand as in step 6 of Run Sovrain with Docker.Point DNS at the new server. Change the
Arecords of the landing host and the region host, heresso.example.comandeu.sso.example.com, to the new address. On a node that is not the landing node, change only its region host. Organization addresses areCNAMErecords to the region host and follow it, and an organization’s own domain points at its organization address, so its admins change nothing.Keep the old node stopped. Never run two nodes on copies of the same data.
The certificates are part of the backup, so the new server serves HTTPS as soon as DNS points at it.
If you run several regions
- On a new server, keep the node’s name. Set the same
PAAS_NODEin its environment file, connect the server to the private network, and change the node’s private address in the peers file on every node. Nodes read the file again each time they need it, without a restart. See Add a region. - After restoring the landing node, it adopts the addresses of organizations that other regions created since the backup and writes any DNS record that is missing. It does this 10 seconds after the start, then every 6 hours.
- After restoring another node, the landing node still holds the addresses of that region’s organizations created
since the backup. Its next pass releases them and deletes their DNS records. If more than 5 such addresses turn up
in one pass, it releases none, logs an error that begins with the number of addresses and
slugs are listed by no region, and those addresses stay taken.
Every setting mentioned here: Server configuration.