Sovrain
  1. Documentation
  2. Self-hosting

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 with IDP_MEK is not the MEK this data was encrypted with. Keep IDP_CSRF_SECRET as 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

  1. Stop and remove the container:

    docker stop --time 60 sovrain && docker rm sovrain
    
  2. Empty 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'
    
  3. Start the node with the same environment file and the same docker run command as in step 6 of Run Sovrain with Docker.

  4. Watch the start:

    docker logs -f sovrain
    docker exec sovrain curl -s http://localhost:8080/ready
    

    The TLS certificate is part of the backup, so the node serves HTTPS again as soon as it is up.

  5. Sign in to an organization and open its admin area to check that it works.

Restore on a new server

  1. 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.

  2. Copy the archive to the new server, here into /srv/backups.

  3. 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.gz
    
  4. Start the container with the same docker run command as in step 6 of Run Sovrain with Docker.

  5. Point DNS at the new server. Change the A records of the landing host and the region host, here sso.example.com and eu.sso.example.com, to the new address. On a node that is not the landing node, change only its region host. Organization addresses are CNAME records to the region host and follow it, and an organization’s own domain points at its organization address, so its admins change nothing.

  6. 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_NODE in 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.