This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

فارسی · Home

Your own Matrix server, step by step

This guide takes you from a fresh server and a domain name to a working Matrix server with:

• Synapse, the homeserver,
• Element and Sable, two web apps to chat in,
• Element Call and Coturn, for voice and video calls,
• Ketesa, an admin panel in the browser,
• scheduled backups and alerts when something breaks.

It takes about an hour, most of it waiting for the install. You don't need to know Matrix, Docker or Ansible: interzone asks you questions and does the rest.

If international internet is cut where your server is, read this guide and then Blackout mode.

---

1. What you need

• A server (a VPS) running Debian 12 or Ubuntu 22.04/24.04, with at least 2 GB of RAM and 20 GB of disk. The setup in this guide needs about 1.9 GB RAM and 8 GB disk; more room is better.
• A domain name you can add DNS records to, e.g. example.org. Your users' IDs will look like @alice:example.org.
• Your own computer with Linux or macOS (or Windows with WSL, or a phone with Termux). interzone runs here and sets up the server over SSH. It needs git, ssh and python3; it installs Ansible by itself.

Throughout this guide the domain is example.org and the server's address is 192.0.2.1. Use your own.

2. Log in to the server with an SSH key

interzone logs in with a key, not a password. If you don't have a key yet, make one on your computer and copy it to the server:

ssh-keygen -t ed25519            # press enter at each question
ssh-copy-id root@192.0.2.1       # asks for the server's password one last time
ssh root@192.0.2.1 true && echo ok

If the last line prints ok, you're set. Not root? Use your user; interzone will ask for its sudo password.

3. Get interzone

curl -fLo interzone https://itsjustadream.g0th.ir/vvvomit/interzone/releases/download/latest/interzone-linux-amd64
chmod +x interzone
./interzone

On an ARM computer (a Raspberry Pi, or a Mac with Linux), use interzone-linux-arm64. The same files are on GitHub. Later, ./interzone self-update updates it.

You'll see the welcome screen. Press enter to begin.

Getting around: ↑↓ move, ←→ choose, space ticks a box, enter goes to the next field, esc goes back, and ? lists every key of the screen you're on. The mouse works too. ctrl+k jumps to any screen by name.

4. Server: where and how to install

1. Base domain: example.org. Not matrix.example.org: interzone adds the matrix. part itself.
2. Install where? Choose A remote server over SSH with →.
3. Server address: your server's IP or hostname.
4. SSH user, port and private key: the defaults (root, 22, ~/.ssh/id_ed25519) fit if you followed step 2.
5. sudo password: only if the SSH user isn't root.

Further down is Downloads. Leave it on Normal internet unless your server can't reach the outside world; then see Blackout mode.

Then HTTPS certificates. Keep Let's Encrypt (free, automatic) and type an email address for it; Let's Encrypt writes there only if a certificate is about to expire.

Keep pressing enter to the end of the form, or ctrl+n to go straight to the next step.

5. Homeserver: pick a preset

At the top are ready-made presets. Move up to Friends & family: it is exactly this guide's setup. Synapse, Element and Sable, Element Call and Coturn for calls, Ketesa, and MAS for logins (which the Element X phone app needs).

Press enter.

6. Components: check what's ticked

The preset ticked six components. The tabs at the top (←→ to move between them) group all 63 that interzone offers: bridges to Telegram or WhatsApp, bots, monitoring and more. Each says what it does and links to its docs. You can add any later (Components has a guide for each); for now leave it as it is and press enter.

7. Settings: what the components need

• Your admin account: the username is admin and the password was made up for you. Press ctrl+r to see it and write it down. This account is created during the install, and you'll log in with it.
• Coturn › Public IP address: your server's IP, 192.0.2.1 here.
• Addresses: where each web app will live. The defaults are fine: element.example.org, sable.example.org, call.element.example.org.

Press ctrl+n for the next step.

8. DNS records and ports

Review checks the server, DNS and ports before anything is installed. On the first try, the DNS checks fail, because the records don't exist yet:

Press z to see exactly which records to create, and scroll with ↑↓ to the ports:

1. At your domain's DNS provider, add one A record per line, each pointing at your server's IP: matrix, element, sable and call.element. (interzone dns prints the same list.)
2. example.org itself must answer https://example.org/.well-known/matrix/server and /client, so other servers and apps find yours. If nothing else runs on example.org, point it at your server too and tick Serve the base domain under Components › Core services; interzone then serves those files. If you already have a website there, have it serve them (see the playbook's docs/configuring-well-known.md).
3. Firewall: if your provider has a firewall in front of the server, open the ports listed under Ports a firewall in front must let in.

DNS takes a few minutes to spread. Press c to check again until every line is green ✓.

9. Deploy

Press enter. interzone sums up what it's about to do, how long it may take, and which checks still fail:

Press y to install. (esc to go back.)

A first install takes 10–30 minutes. You can watch every step; the bottom box is the playbook's own log. If something fails, the log says why, and the whole log is saved in ~/.config/interzone/last-deploy.log. Fix it and press r to run again: running twice does no harm.

When it's done, interzone checks every service:

10. Log in

Open https://element.example.org, choose Sign in, and log in as @admin:example.org with the password from step 7. Make a room, invite someone, start a call to test Element Call. On a phone, install Element X and sign in with the server name example.org.

The Ketesa admin panel is at https://matrix.example.org/synapse-admin: sign in with the same admin account to see and manage users, rooms and media.

11. Manage your server

From now on, ./interzone opens Manage. Everything you'll need later is here, each with a letter key:

• Add a user (a): make accounts for your friends. Manage users (m) lists them, resets passwords and deactivates accounts.
• Update the server (u): pull the latest playbook and re-run the install. What's new (n) shows what an update would bring first.
• Dashboard: load, memory, disks, certificates and containers.

Backups

Under Backups (s), turn on Back up the database on a schedule. The server then dumps its database every day by itself, even when your computer is off, and keeps the last 7. Press enter to set it up on the server, and ctrl+d now and then to copy the backups to your computer. Restore a backup (e) puts one back.

Alerts

Under Alerts (A), the server checks itself every 5 minutes and tells you when a service fails, the homeserver stops answering, a certificate is about to expire or a disk is almost full, and again when it's fixed.

To get them in a Matrix room:

1. In Element, make an account for the alerts (or use yours) and a room such as #alerts:example.org, and invite the account.
2. Get the account's access token: in Element, Settings › Help & About › Advanced › Access Token. Treat it like a password.
3. Choose Matrix room, fill in the room and the token, and press enter. A test message arrives first.

Prefer your phone? Choose Plain text and put an ntfy topic URL in Send them to.

---

Something went wrong? Press ? for every key, look in ~/.config/interzone/last-deploy.log, or ask in the community room linked in the README.