Self-Hosting Matrix Synapse on Alpine Linux
833 words ยท 5 minutes
Synpase
If you're reading this, you likely know that Synapse is a popular Matrix home server software that allows users to run their own Matrix home server.
This post is a short guide describing how I was able to get Synapse working in a minimally-usable state on Alpine Linux.
Installation Process
Dependencies
First, since there is no Alpine-specific package for Synapse, we need to ensure that Alpine has the required dependencies for the Python-based installation method.
Next, we need to set up a Python virtual environment for Synapse:
&&
Running Synapse
Once installed, running Synapse is easy. Simply execute the following command, replacing example.com
with the domain name that will be used with this home server. This will generate the configuration files needed to run the server.
Once the configuration is generated, we can start up the Synapse server:
Configuring Synapse
To make any change to Synapse, we need to edit the YAML
configuration file:
For now, we just need to ensure the server_name
is accurate. However, there are a lot of other configuration options found in the Configuring Synapse documentation that can be enabled/disabled at any point.
server_name: "example.com"
Make sure to restart Synapse when you make changes to the configuration:
Nginx Reverse-Proxy
To ensure that Synapse is reachable from the public, we need to connect our domain to the Synapse server. In my case, I use a Nginx reverse-proxy for this purpose.
To use Nginx, we need to create a reverse-proxy configuration file:
If you already have TLS certificates for this domain (example.com
), you can simply use the SSL configuration and point toward your TLS certificates.
server {
443 ssl http2;
[::]:443 ssl http2;
8448 ssl http2;
[::]:8448 ssl http2;
example.com;
location ~ ^(/_matrix|/_synapse/client) {
;
X-Forwarded-For $remote_addr;
X-Forwarded-Proto $scheme;
Host $host;
50M;
}
/etc/letsencrypt/live/example.com/fullchain.pem;
/etc/letsencrypt/live/example.com/privkey.pem;
/var/log/nginx/matrix.access.log;
}
server {
if ($host = example.com) {
301 ;
}
example.com;
80;
404;
}
If you need to generate TLS certificates (I recommend Certbot), you'll need a more minimal Nginx conf file before you can use the TLS-enabled example above. Instead, use this configuration file during the Certbot certificate generation process:
server {
example.com;
location / {
$uri $uri/ =404;
}
80;
}
Once you're done editing the Nginx conf file, restart Nginx:
If you still need to generate TLS certificates, run certbot
now and obtain the certificates. Certbot will ask if you want to use a webroot or spin up a temporary web server. I highly recommend using the temporary web server due to the many issues with using a webroot.
You will need to stop Nginx in order to user the temporary web server option with Certbot:
# Stop Nginx so certbot can spin up a temp webserver for cert generation
Open Firewall & Router Ports
If you use a firewall on the server, open the 8448
port for discovery and federation, as well as the normal web server ports if you're using a reverse proxy. If you want additional services, such as voice calls, you will need to read the Synapse documentation to see which ports need to be opened for those features.
Here's an example of the Universal Firewall (UFW) software:
# Matrix port
# Standard web server ports
Remember to forward any Synapse ports, such as 8448
, 80
, and 443
, in your Router from the internet to your server's IP address.
Adding Matrix Users
Finally, if you didn't enable public registration in the homeserver.yaml
file, you can manually create users via the command-line:
Remember that the format for federated Matrix usernames is @username:example.com
when logging in to client applications.
Once Synapse is running, and you have a username, you are ready to log in to a Matrix client and start sending messages, joining rooms, and utilizing your very own Matrix server.