Setting up Matrix Synapse on Fedora

howto matrix synapse fedora

2025-02-18

I wanted to install a Matrix service for my family. While matrix-synapse is packaged in Fedora, there's scant documentation regarding what to do next after installing the package.

First, you need to generate a configuration file:

$ generate_config --server-name your.domain.here --config-dir=/etc/synapse/ --report-stats=no > /tmp/homeserver.yaml
$ sudo mv /tmp/homeserver.yaml /etc/synapse

There's a bit of extra configuration, which is in /etc/sysconfig/synapse, which allows you to set the memory limit for the Synapse server. Read and amend this as necessary.

Next, generate some keys:

$ generate_signing_key > /tmp/your.domain.here.signing.key
$ mv /tmp/your-domain-here.signing.key > /etc/synapse

Review the contents of /etc/synapse/homeserver.yaml. You'll note the references to DATADIR, which is /var/lib/synapse/DATADIR/ by default.

Now, it's time to start the service:

$ sudo systemctl start synapse.service
$ sudo systemctl status synapse.service

You should now have Synapse running happily, but it'll only be listening for traffic on the loopback network adaptor.

Follow the instructions for setting up a reverse-proxy to the service. I used nginx, and you probably should too. For me, this also involved setting up a SSL certificate with certbot, but your specific installation might not be the same as mine. Any generic 'SSL with Nginx' instructions should work correctly.

Finally, it's time to setup a user on your instance. We need to generate a shared secret:

$ cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
some-random-output-here

Add that to your /etc/synapse/homeserver.yaml file as:

registration_shared_secret: some-random-output-here

Finally, setup a new user:

$ register_new_matrix_user -c /etc/synapse/homeserver.yamlhttp://localhost:8008  
New user localpart [admin]:    
Password:    
Confirm password:    
Make admin [no]: yes  
Sending registration request...  
Success!

You should now be able to login to your Matrix server using the client of your choice.