Running a Matrix Homeserver with Synapse and Element

Late last year (by which I of course mean a few weeks ago), I decided it was about time I got around to setting up a Discord alternative that my friends and family could use. As of right now, I’m not 100% certain that it’s ready for widespread use, but I think it’s close…

The Why

(You can skip this if you’re not into narratives)

When Discord became the de facto chat application I was nonplussed. It only works with the supplied, proprietary (and might I add, Electron) app, and even has been known to ban users who use alternative clients (which typically don’t work very well anyway)! I would grouse and complain frequently, under the assumption that I couldn’t get anybody to switch just for me, so I might as well just use the chat application du jour. But recently I had an epiphany.

It occurred to me that the biggest use-case I have for Discord is our (almost-) weekly game of Dungeons and Dragons, which has been temporarily and until further notice moved online. And even though all of those players had a Discord account, only one (1) of them ever used it regularly. In fact, two of our players had to be walked through the process of getting Discord sorted out.

So, if they’re not Discord users anyway, maybe I could convince at least this small group to switch. The biggest hurtle was the one other user who was already a big Discord user. But he was excited about the prospect anyway. So I got to work.

The Software

As always, I am using OpenBSD as an operating system. The current version is 6.8 , but if I need to change anything I will update this file.

At this point in the world, synapse is available in pkg, so you will be able to install it rather easily.

NOTE: By default, synapse wants to install to /var/synapse, which is, again by default, not mounted with wxallowed. If you want to install to the default location, you will need to add wxallowed to your fstab. I would recommend moving /var/synapse to a new disk for safety.

You will also need to install postgresql-server and py3-psycopg2 if you want to use Postgre instead of SQLite. HINT: You do.

# pkg_add synapse postgresql-server py3-psycopg2

The Configuration

The following is straight out of /usr/local/share/doc/pkg-readmes/synapse:

As root (or _synapse), go into /var/synapse, then use doas -u _synapse /usr/local/bin/python3.8 -m
-c /var/synapse/homeserver.yaml –generate-config
–server-name –report-stats=no
–generate-keys –keys-directory /var/synapse

NOTE: At this time you do not want to continue with readme because you will cause yourself more work later. Trust me on this one.

Once you’ve done this, set up a basic PostgreSQL database. This is left as an exercise to the reader, but the Synapse documentation seems sane. As always, use your head.

With that out of the way, edit your /var/synapse/homeserver.yaml This file is big, and you’re going to want to read through it to find what you want to edit. At a minimum, you will want to set the server_name, admin_contact, and database settings. You may also wish to edit:

Again, read through the whole document to be sure. The first two options, server_name and admin_contact are pretty self-explanatory. database has a commented out skeleton of how to use Postgre, so comment out all the SQLite options, and uncomment the Postgre options. Add your database user and password, and you’re about ready to go.

# rcctl enable postgresql && rcctl start postgresql

# rcctl enable synapse && rcctl start synapse

Check /usr/local/share/doc/pkg-readmes/synapse again for the instructions on how to register a user. If you didn’t enable_registration earlier, this is how you will add new users. Do not read the section on Configuring with TLS yet.

First, you will need to get some certificates. Thankfully, OpenBSD has an acme client built in that will take care of everything for you. If you are using LetsEncrypt, Add LetsEncrypt to your acme-client.conf.

NOTE: In Roman’s config, he mentions setting up a cronjob to automatically run acme-client. Change that line in your crontab to the following:

0 0 1 * * acme-client && mv /etc/ssl/ /etc/ssl/ && rcctl restart relayd

This is necessary because relayd will only issue the .crt file, but synapse requires the full chain for federation. If you have a better solution to this, please email me.

Now, once again head back to the pkg-readme for instructions on configuring relayd. Start or restart relayd, and provided your services are all running, you should be chatting away!

The Web Client

If you want to enable the web client (useful for those friends of yours who are just kicking the tires, but don’t want to commit to installing anything), download the Element client, and drop it in a folder being served to the web. Copy config.sample.json to config.json, and edit it to suit your environment. It should look something like this:

{ "default_server_config": { "m.homeserver": { "base_url": "", "server_name": "" }, "m.identity_server": { "base_url": "" } },

The Caveats and Addendums

Hosting a Matrix homeserver is not at all like starting a Discord server. There is a lot more upfront work, and once you’ve done that, any users who join your homeserver will not automatically join any rooms. To get around this, there is an option in homeserver.yaml that will automatically add users to a single room. My suggestion is to have this room be unecrypted, with history on, and only admins allowed to post. Make a single post in there with the rules of your server, and a link to the community or set of rooms you want users to join.

If you started with SQLite, and are changing to Postgre, the scripts mentioned in the Synapse documentation are located at /usr/local/share/synapse.

I was recently asked some questions about Jitsi support. I know almost nothing about Jitsi, and am not running my own Jitsi instance. From what I can tell, the workflow for a Jitsi call is mostly run through your client. Since I use Element, my homeserver uses As far as I’m concerned, this is a good enough option for now. To change this, you can edit your config.json in the web or desktop versions, but I have no idea how to change it for Element for Android/iOS. Someone in mentioned configuring it in your .well-known file, but since I’m not concerned or interested in self-hosting Jitsi, you’ll have to figure it out on your own if you want more help.

If you’re having trouble, join to ask for help. The users there are very helpful, though sometimes spread a bit thin, so if they take a while to answer you, or their answers send you to the documentation instead of just giving you the info you need, just understand that they really are trying to be helpful.

Once you’re in Matrix, why not drop me a line?.

If you feel like anything in this document was confusing, or if you get stuck, please let me know, I would love to clear up the confusion, and will edit this document for the next person who is having trouble.

Back to home
All content unless otherwise noted © 2018-2022 Robert D Herb CC-BY-SA
Powered by ssg and OpenBSD
Site Map