Installing Matrix's Synapse!

We are going to follow the standard instructions for installing Synapse.

Install and Config

$ sudo apt install matrix-synapse

I chose a servername of and enabled anon stat reporting.

Reverse Proxy And Delegation

We want to share this box with other services. The root domain is doing other things, but we want people to be able to get to us via, not So we use delegation. We provide a pointer at The pointer is just a JSON file that tells clients where to go for the real server.



We already serve a site at so we'll add .well-known to it. That site is a Pelican static site, so this is easy.

Frist we add .well-known as a static path in pelicanconf. Then:

$ mkdir -p content/.well-known/matrix
$ echo '{ "m.server": "" }' > content/.well-known/matrix/server
$ push # send all this to our live server

Then we check it with:

$ curl

and see if we get our JSON snippet back. If we do, then it's working.


Now we should do the same for clients:

$ echo '{"m.homeserver": { "base_url": "" }}' > content/.well-known/matrix/client
$ push # send all this to our live server

As above, we can check it with:

$ curl

and see if we get our JSON snippet back. If we do, then it's working.

Reverse Proxy

We are serving our static site with Caddy, so we just need to configure it. We configure Caddy by editing /etc/caddy/Caddyfile to include two new stanzas: {
  reverse_proxy /_matrix/* http://localhost:8008
  reverse_proxy /_synapse/client/* http://localhost:8008
} {
  reverse_proxy http://localhost:8008

Then sudo service caddy reload


We installed via apt-get, but that doesn't include postgres, so let's apt-get it.

# apt install postgresql

From there, we'll follow the official docs.

# su - postgres # change to postgres user
# createuser --pwprompt synapse_user
# createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

Then adjust the database part of /etc/matrix-synapse/homeserver.yaml:

  # The database engine name
  name: "psycopg2"
    user: synapse_user
    password: <PUT PASSWORD HERE from /box/>
    database: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

Other Synapse Config

In /etc/matrix-synapse/homeserver.yaml:

suppress_key_server_warning: true
macaroon_secret_key: <PUT PASSWORD HERE from /box/>
no_tls: true


If sudo service matrix-synapse restart doesn't get you a running server, you might want to run it manually so you can interact with finer control and see the output live.

# cd /var/lib/matrix-synapse
# /usr/bin/python3 -m --config-path=/etc/matrix-synapse/homeserver.yaml --config-path=/etc/matrix-synapse/conf.d/

Running this showed me I was missing the macaroon key, for example.

Add User Account

At this point, you should have a running synapse instance.

Registrations via client are closed to prevent strangers from using the server. I'm not sure how it works. Maybe it's possible that with the registration_shared_key, a remote user could register, but I used the commandline to register myself as a user.

Note that the usual instructions say to use register_new_materix_user but the Debian package prefixes that bin with synapse.

$ synapse_register_new_matrix_user -u james -a -c /etc/matrix-synapse/homeserver.yaml

Try it out!

I fired up nheko and it instantly complained about keys despite my not having given it any login info. Perhaps when I tried (and failed) to login earlier it left some stale data. I deleted ~/.config/nheko/nheko.conf and restarted. It was fine after that.

Matrix ID:
Homeserver address:

If you have to add :8448 after your homeserver address to make it work, the client delegation isn't working. Check the client delegation file and the caddy proxy.


Well, it runs and I can connect a client to it, but... I tried to join a large room or two and it ate 100% CPU and I will never do that again.

It seems like matrix is good for small, unfederated instances or maybe federation if your users never join any large rooms.

And now the server is borked because those large room joins are in the database. Any time I start it up, I synapse tries to sync up with those rooms and eats the CPU again. I can see the rooms in the db:

SELECT room_id FROM current_state_events
WHERE state_key = ''
AND type = ''
AND membership = 'join';

I tried to use synadm to delete those room memberships from the commandline, but it doesn't support that.

I contemplated just removing those rows from the db, but I don't know what that would break.

I guess I could try to figure out how to construct a curl request to delete the room joins via the admin api, but I am out of time on this project.

I could just blow away the database and start over, but I came across some ominous warning that then the rooms I tried to join would forever bar me or something like that. That seems... brittle? Like maybe decentralized, self-hosted systems should assume sometimes people are going to experiment or do a fresh install?

Maybe I need to migrate synapse to another box.

The funniest part about all this is that I keep seeing messages to ask for help in the synapse matrix room, which I cannot reach because my synapse server isn't working.

Ah well, exploring matrix will have to wait for another day!