Sovrain
  1. Documentation
  2. Self-hosting

Tutorial

Try Sovrain on your computer

Build Sovrain, run it in Docker on your own computer without a domain or a mail relay, create an organization and sign in to it.

In this tutorial we run Sovrain in Docker on our own computer, create the organization Acme on it and sign in as its first admin, jane. We use the local profile: Sovrain answers over plain HTTP at http://idp.localhost:8080, needs no domain, no certificates and no mail relay, and writes every email into its log.

It takes about 20 minutes, most of it while the image builds.

The local profile is only for trying Sovrain out. It uses a master key that is written in Sovrain’s source code and it opens developer pages, so never put real people on it.

Before you start

You need:

  • Docker with BuildKit, the default builder since Docker Engine 23 and in Docker Desktop;
  • a checkout of the Sovrain source tree;
  • Chrome or Firefox. Both open every address that ends in .localhost on your own computer, so idp.localhost and acme.idp.localhost work without any DNS setup;
  • port 8080 free on your computer.

Build the image

In a terminal, go to the root of the source tree and run:

docker build -f internal-apps/idp/Dockerfile -t sovrain:try .

The first build compiles Sovrain from source, which takes several minutes. When it has finished, check that the image is there:

docker image ls sovrain

The list shows sovrain with the tag try.

Start Sovrain

Run:

docker run --rm --name sovrain-try \
  -p 127.0.0.1:8080:8080 \
  -e SPRING_PROFILES_ACTIVE=local \
  -e IDP_DATABASE_DIRECTORY=/data \
  -v sovrain-try:/data \
  sovrain:try

The port is published on 127.0.0.1 only, so nobody else on your network reaches it, and the data goes to the Docker volume sovrain-try, which Docker creates now.

Leave this terminal open: Sovrain writes its log here. After a few seconds a line ends with:

idp listening on 0.0.0.0:8080, data in /data

Open a second terminal and ask Sovrain whether it is ready:

curl -s http://localhost:8080/ready

It answers {"ready":true}.

Create the organization

  1. In Chrome or Firefox, open http://idp.localhost:8080. This is the landing host of our installation: the start page with Try it for free and Sign in.
  2. Select Try it for free. The form Create a new organization opens.
  3. Fill in the form:
    • Organization name: Acme
    • Organization URL: acme. The field ends in .idp.localhost, because every organization gets an address one level below the landing host.
    • Data region: local, the only region of this installation.
    • Your email: jane@example.com. Nothing is sent anywhere; we will find the email in the log.
    • Login name: jane
    • Password and Confirm password: a password of at least 8 characters.
  4. Select Create organization.

Your browser may work for a few seconds before the form is sent; this replaces a CAPTCHA. Then Sovrain shows Your organization is ready, with the Organization URL http://acme.idp.localhost:8080 and the Login name jane.

Verify the email from the log

Go back to the first terminal. Sovrain has written the verification email into the log instead of sending it. You see a line with Mail from=noreply@sovrain.local to=jane@example.com subject=Verify your Sovrain email, then the text of the email:

Hi,

To finish creating your account, click this link:

    http://acme.idp.localhost:8080/verify-email?token=…

Copy the link from your terminal and open it in the browser. Sovrain shows Email verified.

Sign in

  1. Select Sign in. The sign-in page of Acme opens, at http://acme.idp.localhost:8080/login.
  2. Enter jane in Email or login name, enter your password and select Sign in.

You land on Jane’s home page, which greets you with Good morning, jane. (or afternoon, or evening). Under Your apps it says No apps yet.

Look at the data

In the second terminal, list what Sovrain has stored on the volume:

docker exec sovrain-try ls /data /data/orgs

Among the files are node.sqlite, the node’s own database, and mek-fingerprint, which ties the data to the master key. In orgs is acme.db: everything about Acme is in this one SQLite file.

Stop Sovrain

Press Ctrl+C in the first terminal. Sovrain logs shutting down: finishing requests in flight and stops, and Docker removes the container. The volume stays: the same docker run command brings Acme back.

When you no longer need it, delete the volume and the image:

docker volume rm sovrain-try
docker image rm sovrain:try

What we did

We built Sovrain from source, ran one node with the local profile, created the organization Acme with its own address below the landing host, verified Jane’s email from the log and signed in as Jane. All of Acme’s data was in one file on the node’s volume.

A real server works the same way, with four differences: the prod profile, HTTPS with certificates Sovrain gets from Let’s Encrypt through your DNS provider, a mail relay that sends the emails, and a master key of your own.

Next steps