Running a Matrix Homeserver with Synapse and Element
- Created 2021-01-06
- 2021-01-22 - Added some info on Jitsi (Or rather, explained the lack of info)
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…
(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.
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
/var/synapse to a new disk for safety.
You will also need to install
py3-psycopg2 if you want
to use Postgre instead of SQLite. HINT: You do.
# pkg_add synapse postgresql-server py3-psycopg2
The following is straight out of
As root (or _synapse), go into /var/synapse, then use doas -u _synapse /usr/local/bin/python3.8 -m synapse.app.homeserver
-c /var/synapse/homeserver.yaml –generate-config
–server-name matrix.example.com –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
database settings. You may also wish to edit:
web_client_location- If you intend to install Element or another web client
use_presence- If your server seems slow
listeners- If you intend to have synapse serve https on its own
limit_remote_rooms- If you have trouble with joining large rooms
enable_registration- If you want others to be able to use your server
Again, read through the whole document to be sure. The first two options,
admin_contact are pretty self-explanatory.
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
/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 example.com && mv /etc/ssl/example.com.pem /etc/ssl/example.com.crt && 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.json, and edit it to suit your environment. It should look something like this:
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
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 jitsi.riot.im. 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 #element-android:matrix.org 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 #synapse:matrix.org 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.