Installing SOVRGNnet

From a bare machine to a working chat network. Ten minutes, most of it waiting.

What you need A computer that stays on — an old laptop, a Raspberry Pi 5, a mini PC, a spare desktop. About 4 GB of memory. That's the whole list. No domain name, no Cloudflare account, no credit card, nothing to sign up for.

The short version

git clone https://github.com/Formicaria/SOVRGNnet.cc.git sovrgnnet
cd sovrgnnet
./install.sh

If git isn't installed, sudo apt install git first. If Docker isn't installed, the script notices and offers to do it.

The one question it asks

Everything else is generated for you. This is the only decision that's actually yours:

How should people reach your SOVRGNnet?

  1  Just me, on this network
  2  Friends over the internet — no account, no domain
  3  My own domain, through Cloudflare
  4  My own domain, my own certificates

1 — Just this network

Nothing leaves your house. You get an address like http://192.168.1.50:3000 that anyone on your wifi can open. Good for trying it, good for a household.

2 — Friends over the internet, no account needed

You get a real https:// address in about a minute, with no signup anywhere and nothing touched on your router. It runs over a Cloudflare Quick Tunnel — an outbound connection from your machine, so there's no port forwarding and your home IP stays private.

The catch, stated plainly: the address is random and changes every time you restart. That's the price of needing no account. It suits a weekend, a group of friends, or trying the thing out with real people. For something permanent, option 3.

Run sovrgnnet url any time to see the current address.

3 — Your own domain, through Cloudflare

A permanent address like chat.yourname.com. Needs a free Cloudflare account and a domain you own. In the Cloudflare dashboard: Zero Trust → Networks → Tunnels → Create a tunnel → Cloudflared, point a public hostname at http://app:3000, then paste the token the dashboard gives you when the installer asks.

Full production setup — including Matrix federation delegation — is in DEPLOYMENT.md.

4 — Your own domain, your own certificates

For people already running a reverse proxy. Put cert.pem and key.pem in ./ssl/ and uncomment the TLS block at the bottom of nginx.conf.

Without Docker: the LXC install

There's a second installer that uses no Docker at all — PostgreSQL, Conduit, Kubo, and the app as ordinary systemd services. On Proxmox this is the lighter option: an LXC container shares the host kernel, so you skip both the VM overhead and the Docker layer.

# inside a fresh Debian or Ubuntu container, as root
apt update && apt install -y git
git clone https://github.com/Formicaria/SOVRGNnet.cc.git /opt/sovrgnnet
/opt/sovrgnnet/scripts/install-lxc.sh

Same question, same result. Afterwards sovrgnnet is on your PATH and behaves identically to the Docker install — it detects which one you have and translates.

Give the container 4 GB of memory Building the frontend is the peak, and 1 GB won't survive it. Creating the container and the rest of the details are in LXC.md.

Your first account

Open the address the installer printed and sign up with an email and password. The email is just a username — nothing is sent anywhere and no outside service is involved. The first account becomes the admin.

Then:

Click + on the left to create a server.
Click the invite icon at the top to get a shareable link.
Send it to someone. They sign up and land in your server.

What the installer did

Worth knowing, even though you didn't have to do any of it:

Generated a session secret, a database password, and a Matrix registration token — written to .env with permissions 600.
Started PostgreSQL, a Conduit Matrix homeserver, and an IPFS node, all bound to loopback where they should be.
Built the app and started it. It creates its own database tables on first boot — there's no migration step to run, now or after an update.
Left federation turned off, so your homeserver talks to nobody until you decide otherwise.

Re-running is safe ./install.sh keeps the secrets it already generated and backs up your previous settings. Use it to change how people reach you without disturbing any accounts or messages.

One setting to get right the first time

MATRIX_SERVER_NAME is written into every Matrix user and room ID the moment it's created. Changing it later orphans all existing chat history — there's no migration that fixes it.

The installer picks sovrgn.local for a private instance, or matrix.yourdomain.com if you gave it a domain. If you think you'll want a domain eventually, it's worth deciding before your first login rather than after your first hundred messages.

When it doesn't work

What you see	What to do
The address doesn't load	`sovrgnnet status`. Just started? Give it a minute. Otherwise `sovrgnnet logs`.
`permission denied` talking to Docker	Your user isn't in the docker group yet. Log out and back in.
Friends can't connect (option 2)	The address changed on restart. `sovrgnnet url`.
Port already in use	Something else on that machine holds 3000 or 80. Stop it, or use a different machine.
Killed during the build	Out of memory. Give it 4 GB, or add swap.

Still stuck? Open an issue with the output of sovrgnnet status. A failing install is a bug in the installer, not something you did wrong.

Back ← Documentation Next Running it →