cmc/cleberg.net

  1#+date:        [2022-11-07 Mon 00:00:00]
  2#+title:       Self-Hosting Guide: Matrix Synapse
  3#+description: How to deploy Matrix Synapse on Alpine Linux with Nginx.
  4#+slug:        self-hosting-matrix
  5#+filetags:    :linux:self-hosting:
  6
  7* Synapse
  8
  9If you're reading this, you likely know that [[https://github.com/matrix-org/synapse/][Synapse]] is a popular [[https://matrix.org/][Matrix]] home
 10server software that allows users to run their own Matrix home server.
 11
 12This post is a short guide describing how I was able to get Synapse working in a
 13minimally-usable state on Alpine Linux.
 14
 15* Installation Process
 16
 17** Dependencies
 18
 19First, since there is no Alpine-specific package for Synapse, we need to ensure
 20that Alpine has the required dependencies for the Python-based installation
 21method.
 22
 23#+begin_src sh
 24doas apk -U update
 25doas apk add python3 py3-virtualenv
 26#+end_src
 27
 28Next, we need to set up a Python virtual environment for Synapse:
 29
 30#+begin_src sh
 31mkdir -p ~/synapse && cd ~/synapse
 32virtualenv -p python3 ~/synapse/env
 33source ~/synapse/env/bin/activate
 34pip install --upgrade pip
 35pip install --upgrade setuptools
 36pip install matrix-synapse
 37#+end_src
 38
 39** Running Synapse
 40
 41Once installed, running Synapse is easy. Simply execute the following command,
 42replacing =example.com= with the domain name that will be used with this home
 43server. This will generate the configuration files needed to run the server.
 44
 45#+begin_src sh
 46python -m synapse.app.homeserver \
 47    --server-name example.com \
 48    --config-path homeserver.yaml \
 49    --generate-config \
 50    --report-stats=no
 51#+end_src
 52
 53Once the configuration is generated, we can start up the Synapse server:
 54
 55#+begin_src sh
 56synctl start
 57#+end_src
 58
 59** Configuring Synapse
 60
 61To make any change to Synapse, we need to edit the =YAML= configuration file:
 62
 63#+begin_src sh
 64nano ~/synapse/homeserver.yaml
 65#+end_src
 66
 67For now, we just need to ensure the =server_name= is accurate. However, there
 68are a lot of other configuration options found in the [[https://matrix-org.github.io/synapse/develop/usage/configuration/config_documentation.html][Configuring Synapse]]
 69documentation that can be enabled/disabled at any point.
 70
 71#+begin_src yaml
 72server_name: "example.com"
 73#+end_src
 74
 75Make sure to restart Synapse when you make changes to the configuration:
 76
 77#+begin_src sh
 78synctl restart
 79#+end_src
 80
 81** Nginx Reverse-Proxy
 82
 83To ensure that Synapse is reachable from the public, we need to connect our
 84domain to the Synapse server. In my case, I use a Nginx reverse-proxy for this
 85purpose.
 86
 87To use Nginx, we need to create a reverse-proxy configuration file:
 88
 89#+begin_src sh
 90doas nano /etc/nginx/http.d/example.com.conf
 91#+end_src
 92
 93If you already have TLS (Transport Layer Security) certificates for this domain
 94(=example.com=), you can simply use the SSL (Secure Socket Layer) configuration
 95and point toward your TLS certificates.
 96
 97#+begin_src conf
 98server {
 99    listen 443 ssl http2;
100    listen [::]:443 ssl http2;
101
102    # For the federation port
103    listen 8448 ssl http2;
104    listen [::]:8448 ssl http2;
105
106    server_name example.com;
107
108    location ~ ^(/_matrix|/_synapse/client) {
109        # note: do not add a path (even a single /) after the port in `proxy_pass`,
110        # otherwise nginx will canonicalise the URI and cause signature verification
111        # errors.
112        proxy_pass http://localhost:8008;
113        proxy_set_header X-Forwarded-For $remote_addr;
114        proxy_set_header X-Forwarded-Proto $scheme;
115        proxy_set_header Host $host;
116
117        # Nginx by default only allows file uploads up to 1M in size
118        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
119        client_max_body_size 50M;
120    }
121
122    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
123    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
124    access_log /var/log/nginx/matrix.access.log;
125}
126
127server {
128    if ($host = example.com) {
129        return 301 https://$host$request_uri;
130    }
131
132  server_name example.com;
133  listen 80;
134    return 404;
135}
136#+end_src
137
138If you need to generate TLS certificates (I recommend [[https://certbot.eff.org/][Certbot]]), you'll need a
139more minimal Nginx conf file before you can use the TLS-enabled example above.
140Instead, use this configuration file during the Certbot certificate generation
141process:
142
143#+begin_src conf
144server {
145  server_name example.com;
146  location / {
147      try_files $uri $uri/ =404;
148  }
149  listen 80;
150}
151#+end_src
152
153Once you're done editing the Nginx conf file, restart Nginx:
154
155#+begin_src sh
156doas rc-service nginx restart
157#+end_src
158
159If you still need to generate TLS certificates, run =certbot= now and obtain the
160certificates. Certbot will ask if you want to use a webroot or spin up a
161temporary web server. I *highly* recommend using the temporary web server due to
162the many issues with using a webroot.
163
164You will need to stop Nginx in order to user the temporary web server option
165with Certbot:
166
167#+begin_src sh
168# Stop Nginx so certbot can spin up a temp webserver for cert generation
169doas rc-service nginx stop
170doas certbot certonly -v
171doas rc-service nginx start
172#+end_src
173
174** Open Firewall & Router Ports
175
176If you use a firewall on the server, open the =8448= port for discovery and
177federation, as well as the normal web server ports if you're using a reverse
178proxy. If you want additional services, such as voice calls, you will need to
179read the Synapse documentation to see which ports need to be opened for those
180features.
181
182Here's an example of the Universal Firewall (UFW) software:
183
184#+begin_src sh
185# Matrix port
186doas ufw allow 8448
187# Standard web server ports
188doas ufw allow "Nginx Full"
189#+end_src
190
191Remember to forward any Synapse ports, such as =8448=, =80=, and =443=, in your
192Router from the internet to your server's internet protocol (IP) address.
193
194** Adding Matrix Users
195
196Finally, if you didn't enable public registration in the =homeserver.yaml= file,
197you can manually create users via the command-line:
198
199#+begin_src sh
200cd ~/synapse
201register_new_matrix_user -c homeserver.yaml
202#+end_src
203
204Remember that the format for federated Matrix usernames is
205=@username:example.com= when logging in to client applications.
206
207Once Synapse is running, and you have a username, you are ready to log in to a
208Matrix client and start sending messages, joining rooms, and utilizing your very
209own Matrix server.