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.1forsso-1and10.8.0.2forsso-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
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
landingon 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 itsIDP_NODE_REGION). Its organizations’ DNS records point toeu.sso.example.com. - Lines whose app name is not the node’s
PAAS_APPare ignored.
Put the same file on both servers, for example at
/etc/sovrain/paas/peers.- Every node carries exactly one
Create the DNS record for the new region host: an
Arecord forus.sso.example.compointing to the new node’s public address.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-2Keep
IDP_BASE_URLthe 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 sameIDP_MEKon every node leaves you one master key to keep safe; each node pins its own volume to the key on its first start.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-17Wait until
/readyshows"nodeCertificate":true, as on the first node.Move the first node onto the peers file. Recreate its container the same way: add
PAAS_APP=sovrainandPAAS_NODE=sso-1to its environment file, removeIDP_NODE_REGION, mount the directory of the peers file, and publish port 8080 on10.8.0.1only. This restart interrupts sign-in on the first node for a moment.Check registration. Open
https://sso.example.com/register. The Data region list now showseuandus, 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.