# Running a Matrix Homeserver with Synapse and Element

Created 2021-01-06

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 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](https://github.com/matrix-org/synapse/blob/develop/docs/postgres.md)
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: 

- `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,
`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](https://www.romanzolotarev.com/openbsd/acme-client.html).

**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](mailto:hello@robertdherb.com?subject=Synapse Matrix Config).

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](https://github.com/vector-im/element-web), 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": "https://example.com",`
> `           "server_name": "example.com"`
> `       },`
> `       "m.identity_server": {`
> `           "base_url": "https://vector.im"`
> `       }`
> `   },`


## 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](https://github.com/matrix-org/synapse/blob/develop/docs/postgres.md#porting-from-sqlite)
are located at `/usr/local/share/synapse`.

If you're having trouble, join [#synapse:matrix.org](https://matrix.to/#/#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?](https://matrix.to/#/@rdh:space-j.am). 

If you feel like anything in this document was confusing, or if you get stuck,
please [let me know](mailto:hello@robertdherb.com?subject=Your Matrix Instructions Suck), I would love to clear up the confusion, and will edit this document
for the next person who is having trouble.

matrix.md