Sovrain
  1. Documentation
  2. Self-hosting

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

  1. 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>, here eu.sso.example.com. A region name matches [a-z][a-z0-9]{0,15}.

  2. Create the DNS records in your zone: an A record for sso.example.com and for eu.sso.example.com, both pointing to the server. Add an AAAA record 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 registers acme, Sovrain itself adds acme.sso.example.com as a CNAME to eu.sso.example.com through the DNS provider’s API.

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

  4. Create the secrets.

    openssl rand -base64 32   # IDP_MEK
    openssl rand -base64 32   # IDP_CSRF_SECRET
    

    IDP_MEK is 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.

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

  6. 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-17
    

    Publish 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://.

  7. Watch the first start. The log is one JSON object per line:

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

    While the first certificate is being issued, /ready answers {"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, /ready answers 503 with an error; see Set up TLS with DNS.

  8. Create the first organization at https://sso.example.com/register, as in Create your organization. Its Data region list shows eu.

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/.idp inside the container instead of on the volume, so docker rm deletes it. Never run it like that with real people.
  • A proxy that terminates TLS in front of Sovrain is not supported. The prod profile 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.