content/blog/2022-11-07-self-hosting-matrix.org

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