Run your own sync server with Docker

In this tutorial you start the Sternway sync server on your own computer with Docker Compose, check that it answers, and create an account on it from the desktop app. Everything runs on one machine, so you can see the whole path before you put a server on the network.

The server stores only encrypted data. It never sees your hosts, passwords, keys or session logs in a form it can read.

What you need

• A computer with Docker and the Docker Compose plugin. Check with docker compose version.
• The Sternway desktop app on the same computer, as in Connect to your first host on the desktop.
• curl, openssl and sha256sum.

The server is published as a container image, ghcr.io/kuscko/sternway-server, with one tag per release. Each release also has a docker-compose.yml that runs that image together with Postgres.

1. Download the Compose file

Make a folder for the server and download the Compose file of the newest release (the version sternway.dev/download shows; the server is published from 0.1.0-alpha.56 on):

mkdir sternway-server && cd sternway-server
VERSION=0.1.0-alpha.56
curl -fLO https://downloads.sternway.dev/$VERSION/docker-compose.yml
curl -fLO https://downloads.sternway.dev/$VERSION/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS

The last command must print docker-compose.yml: OK. If it does not, the file is not the one Sternway published: download it again and do not use it.

2. Write the settings

The Compose file takes its settings from a .env file next to it. Three are needed to start:

• STERNWAY_VERSION: the server version to run, the same as the Compose file’s.
• STERNWAY_SERVER_SECRET: at least 32 random bytes, base64. It encrypts the two-factor secrets the server stores.
• STERNWAY_PUBLIC_URL: the address the server is reached at.

cat > .env <<EOF
STERNWAY_VERSION=$VERSION
STERNWAY_SERVER_SECRET=$(openssl rand -base64 32)
STERNWAY_PUBLIC_URL=http://localhost:8080
EOF
chmod 600 .env
cat .env

It then looks like this, with your own secret:

STERNWAY_VERSION=0.1.0-alpha.56
STERNWAY_SERVER_SECRET=q3V9…(44 characters in all)…=
STERNWAY_PUBLIC_URL=http://localhost:8080

Keep a copy of .env with your other server passwords. The server needs the same secret every time it starts; if it changes, every account that turned on two-factor authentication has to set it up again.

3. Start the server

docker compose pull
docker compose up -d

pull downloads the server image (ghcr.io/kuscko/sternway-server at the version in .env) and Postgres; up -d starts both in the background. The server listens on 127.0.0.1:8080, so only this computer can reach it for now.

4. Check that it answers

curl -sf http://localhost:8080/healthz

The answer looks like {"ok":true,"version":"…"}. If curl prints nothing, wait a few seconds for the database to start and try again, or look at the server’s log:

docker compose logs server

5. Create an account on it

1. In the desktop app, open Settings › Account & Sync and choose Create account.
2. For Server URL type http://localhost:8080. Plain http:// is accepted here because the server is on this same computer; everywhere else Sternway asks for https://.
3. Fill in your email, name and password, and choose Create account.

Settings › Account & Sync now shows your account and Up to date. Your hosts were uploaded to your own server, encrypted.

6. Stop and start it

docker compose stop      # stop, keep everything
docker compose start     # start again

Run these in the folder with docker-compose.yml and .env. The database is kept in a Docker volume, so docker compose down followed by up -d keeps your data too; only docker compose down -v deletes it.

What you did

You downloaded and checked the Compose file, started the published server image and its database, checked the health address, and created an account on the server from the app. The account’s data on the server is ciphertext plus the metadata needed to sync it (ids, revision numbers, times, device names).

Next

Your phone and your other computers cannot reach a server on 127.0.0.1, and the phone only uses https://. To use the server from other devices, Run the sync server covers:

• a TLS reverse proxy in front of it, and telling the server about it;
• backups and upgrades;
• email, single sign-on, passkeys and the licence file.

Every setting is listed in Environment variables.