Sovrain
  1. Documentation
  2. Self-hosting

How-to guide

Add a region

Add a second Sovrain node that keeps the data of new organizations in another region, with a peers file and a private network.

This guide adds a node in a second region to a running Sovrain installation, so that people who register an organization can choose to keep its data there. In the examples the first node is sso-1 in region eu, which already runs as in Run Sovrain with Docker, and the new node is sso-2 in region us.

Each region is served by exactly one node, with its own data volume. An organization lives in the region chosen when it was registered and cannot be moved later. A second region adds room and a choice of location, not redundancy: if a node stops, the organizations on it are unavailable. How the nodes share the work, and why: About running Sovrain yourself.

The default path /etc/paas/peers and the variables PAAS_APP, PAAS_NODE come from the hosting platform Sovrain is built for; elsewhere you provide all three yourself, as below.

Before you start

  • A private network between the nodes, such as WireGuard, with a fixed address for each node: here 10.8.0.1 for sso-1 and 10.8.0.2 for sso-2. The nodes call each other over plain HTTP on port 8080 at these addresses, and accept such calls only from the addresses in the peers file. Every node must therefore see the others’ calls coming from those exact addresses, with no proxy or address translation in between, and port 8080 must be reachable on the private network only.
  • Every node uses the same SERVER_PORT (8080 unless you changed it), because a node calls the others on its own port number.
  • A server for the new node, prepared like the first one, with Docker and the Sovrain image of the same version as the first node.

Add the node

  1. Write the peers file. It has one line per node: the app name, the node name, the node’s private address and its tags, separated by spaces. Tags are separated by commas without spaces.

    sovrain sso-1 10.8.0.1 region:eu,landing
    sovrain sso-2 10.8.0.2 region:us
    
    • Every node carries exactly one region:<name> tag, and no two nodes share a region. The name matches [a-z][a-z0-9]{0,15}.
    • Put landing on one node, the first one: it serves the landing host and registration. A node refuses to start when two nodes carry it, and with none, no node offers registration.
    • Keep the first node’s region name as it was (eu, the value of its IDP_NODE_REGION). Its organizations’ DNS records point to eu.sso.example.com.
    • Lines whose app name is not the node’s PAAS_APP are ignored.

    Put the same file on both servers, for example at /etc/sovrain/paas/peers.

  2. Create the DNS record for the new region host: an A record for us.sso.example.com pointing to the new node’s public address.

  3. Write the new node’s environment file. Copy the first node’s file, then remove IDP_NODE_REGION (the peers file now says which region a node serves) and add the node’s identity:

    PAAS_APP=sovrain
    PAAS_NODE=sso-2
    

    Keep IDP_BASE_URL the same on every node: it is the landing URL of the whole installation. The new node also needs the DNS credentials, because it gets its own certificate for *.sso.example.com, and the SMTP settings, because it sends the emails of its organizations. Keeping the same IDP_MEK on every node leaves you one master key to keep safe; each node pins its own volume to the key on its first start.

  4. Start the new node with the directory of the peers file mounted where Sovrain reads it, and port 8080 published on the private address only:

    docker volume create sovrain-data
    docker run -d --name sovrain --restart unless-stopped \
      -p 443:8443 \
      -p 10.8.0.2:8080:8080 \
      -v sovrain-data:/data \
      -v /etc/sovrain/paas:/etc/paas:ro \
      --env-file /etc/sovrain/sovrain.env \
      --health-cmd 'curl -fsS http://localhost:8080/ready || exit 1' \
      --stop-timeout 60 \
      sovrain:2026-11-17
    

    Wait until /ready shows "nodeCertificate":true, as on the first node.

  5. Move the first node onto the peers file. Recreate its container the same way: add PAAS_APP=sovrain and PAAS_NODE=sso-1 to its environment file, remove IDP_NODE_REGION, mount the directory of the peers file, and publish port 8080 on 10.8.0.1 only. This restart interrupts sign-in on the first node for a moment.

  6. Check registration. Open https://sso.example.com/register. The Data region list now shows eu and us, in the order of the peers file.

If registering an organization in us fails with The us region did not confirm the registration, so the organization may have been created., the first node cannot reach sso-2 on 10.8.0.2:8080, or sso-2 sees the call coming from an address that is not 10.8.0.1. The landing node keeps that organization address reserved and frees it in a later pass, once it reaches sso-2; the passes run every 6 hours.

Later changes to the peers file, such as a third region, take effect on running nodes without a restart: a node reads the file again each time it needs it. A node that is not listed in the file refuses to start.

Every setting mentioned here: Server configuration.