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
.localhoston your own computer, soidp.localhostandacme.idp.localhostwork 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
- 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. - Select Try it for free. The form Create a new organization opens.
- 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.
- Organization name:
- 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
- Select Sign in. The sign-in page of Acme opens, at
http://acme.idp.localhost:8080/login. - Enter
janein 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
- Run Sovrain with Docker on a server of your own.
- About running Sovrain yourself: nodes, regions, the master key and certificates.
- Profiles: what
localchanges compared withprod.