How-to guide
Run Sovrain with Docker
Build the Sovrain image from source and run one node on your own server, with built-in TLS, mail and a data volume.
This guide runs Sovrain on one server of your own, as a single Docker container that serves every organization you
create on it. At the end, Sovrain answers on https://sso.example.com with its own certificate and you can create the
first organization. To try Sovrain on your own computer first, without a domain or a mail relay, follow
Try Sovrain on your computer.
Before you start
You need:
- a Linux server with a public IP address, where nothing else uses port 443;
- Docker with BuildKit, the default builder since Docker Engine 23;
- a domain whose DNS zone is hosted at ClouDNS or OVH, with API credentials for it. Sovrain gets its certificates from Let’s Encrypt with the DNS-01 challenge through one of these two providers; no other provider and no other way of getting certificates is supported;
- an SMTP relay that accepts authenticated mail over implicit TLS, usually on port 465;
- a checkout of the Sovrain source tree.
No ready-made Sovrain image is published; you build it yourself in step 3.
In this guide the landing host is sso.example.com, in the zone example.com, and the region is called eu.
Organizations then get the addresses <slug>.sso.example.com, for example acme.sso.example.com.
Run the node
Choose the names. The landing host is where people register organizations and pick their organization at sign-in. The region host is
<region>.<landing host>, hereeu.sso.example.com. A region name matches[a-z][a-z0-9]{0,15}.Create the DNS records in your zone: an
Arecord forsso.example.comand foreu.sso.example.com, both pointing to the server. Add anAAAArecord only if the container network has IPv6 enabled; with Docker’s default bridge, IPv6 connections reach Sovrain from the bridge’s address, so all IPv6 clients share one rate limit. You do not create records for organizations: when someone registersacme, Sovrain itself addsacme.sso.example.comas aCNAMEtoeu.sso.example.comthrough the DNS provider’s API.Build the image from the root of the source tree, not from the directory that holds the Dockerfile. The binary embeds the theme and the static files from other parts of the tree when it is compiled.
docker build -f internal-apps/idp/Dockerfile -t sovrain:2026-11-17 .Tag the image with something that tells you which source it came from, such as the date or the commit.
Create the secrets.
openssl rand -base64 32 # IDP_MEK openssl rand -base64 32 # IDP_CSRF_SECRETIDP_MEKis the master key: every organization’s keys are wrapped under it. If you lose it, you lose every organization on this node, and a backup of the data does not help. Store a copy now somewhere outside this server, for example in your password manager or a sealed envelope, before you go on. Sovrain pins the data volume to this key on the first start and refuses to start with any other key.Write the environment file, for example
/etc/sovrain/sovrain.env, readable by root only:SPRING_PROFILES_ACTIVE=prod IDP_BASE_URL=https://sso.example.com IDP_NODE_REGION=eu IDP_MEK=<first value from step 4> IDP_CSRF_SECRET=<second value from step 4> IDP_SMTP_HOST=smtp.example.com IDP_SMTP_USERNAME=sovrain@example.com IDP_SMTP_PASSWORD=<relay password> IDP_TLS_DNS_PROVIDER=cloudns IDP_TLS_DNS_ZONE=example.com IDP_TLS_CLOUDNS_AUTH_ID=<ClouDNS sub-user id> IDP_TLS_CLOUDNS_PASSWORD=<ClouDNS sub-user password>For OVH and the other DNS settings, see Set up TLS with DNS. For the mail settings, see Configure outgoing mail.
Start the container:
docker volume create sovrain-data 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-11-17Publish only port 443, mapped to 8443 inside the container, where Sovrain terminates TLS itself. Do not publish port 8080: it serves the same application over plain HTTP, for the health check and for the traffic between nodes, and must never be reachable from the internet. There is no port 80 and no redirect from
http://.Watch the first start. The log is one JSON object per line:
docker logs -f sovrain docker exec sovrain curl -s http://localhost:8080/readyWhile the first certificate is being issued,
/readyanswers{"ready":true,"nodeCertificate":false,"issuing":true}. That takes a minute or more, because Sovrain waits for the DNS record to settle. When it shows"nodeCertificate":true, Sovrain serves HTTPS. If issuance fails,/readyanswers503with anerror; see Set up TLS with DNS.Create the first organization at
https://sso.example.com/register, as in Create your organization. Its Data region list showseu.
Things to know before you go live
- Anyone who can reach the landing host can create an organization. Registration is protected only by a proof of work in the browser and a limit of 10 registration requests an hour per client address. Sovrain has no setting to close it.
- Always set
SPRING_PROFILES_ACTIVE=prod. Without a profile, Sovrain starts without TLS, without mail, with a random CSRF secret and with a development master key that is written in its source code. Data stored that way is not protected by any secret of yours, and it keeps its data in/root/.idpinside the container instead of on the volume, sodocker rmdeletes it. Never run it like that with real people. - A proxy that terminates TLS in front of Sovrain is not supported. The
prodprofile always terminates TLS in the process, so port 443 must reach the container unchanged. - One node, one region. While the container is down or restarting, nobody can sign in to the organizations on it. Why, and what that means for you: About running Sovrain yourself.
- Back up the volume from the first day: Back up the data volume. If you ever need it: Restore a node from a backup.
- Upgrade by building a newer image and replacing the container: Upgrade Sovrain.
Every environment variable with its default: Server configuration.