diff options
Diffstat (limited to 'blog/2022-11-07-matrix-synapse.org')
| -rw-r--r-- | blog/2022-11-07-matrix-synapse.org | 231 |
1 files changed, 124 insertions, 107 deletions
diff --git a/blog/2022-11-07-matrix-synapse.org b/blog/2022-11-07-matrix-synapse.org index 0c0d43f..493957a 100644 --- a/blog/2022-11-07-matrix-synapse.org +++ b/blog/2022-11-07-matrix-synapse.org @@ -1,103 +1,114 @@ -+++ -date = 2022-11-07 -title = "Self-Hosting Matrix Synapse on Alpine Linux" -description = "A short guide on how I was able to get Synapse working on Alpine Linux." -+++ - -## Synpase - -If you're reading this, you likely know that -[Synapse](https://github.com/matrix-org/synapse/) is a popular -[Matrix](https://matrix.org/) 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. - -```sh +#+title: Self-Hosting Matrix Synapse on Alpine Linux +#+date: 2022-11-07 + +** Synpase +:PROPERTIES: +:CUSTOM_ID: synpase +:END: +If you're reading this, you likely know that +[[https://github.com/matrix-org/synapse/][Synapse]] is a popular +[[https://matrix.org/][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 +:PROPERTIES: +:CUSTOM_ID: installation-process +:END: +*** Dependencies +:PROPERTIES: +:CUSTOM_ID: dependencies +:END: +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. + +#+begin_src sh doas apk -U update doas apk add python3 py3-virtualenv -``` +#+end_src Next, we need to set up a Python virtual environment for Synapse: -```sh +#+begin_src sh mkdir -p ~/synapse && cd ~/synapse virtualenv -p python3 ~/synapse/env source ~/synapse/env/bin/activate pip install --upgrade pip pip install --upgrade setuptools pip install matrix-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. - -```sh +#+end_src + +*** Running Synapse +:PROPERTIES: +:CUSTOM_ID: running-synapse +:END: +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. + +#+begin_src sh python -m synapse.app.homeserver \ --server-name example.com \ --config-path homeserver.yaml \ --generate-config \ --report-stats=no -``` +#+end_src Once the configuration is generated, we can start up the Synapse server: -```sh +#+begin_src sh synctl start -``` +#+end_src -### Configuring Synapse +*** Configuring Synapse +:PROPERTIES: +:CUSTOM_ID: configuring-synapse +:END: +To make any change to Synapse, we need to edit the =YAML= configuration +file: -To make any change to Synapse, we need to edit the `YAML` configuration file: - -```sh +#+begin_src sh nano ~/synapse/homeserver.yaml -``` +#+end_src -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](https://matrix-org.github.io/synapse/develop/usage/configuration/config_documentation.html) -documentation that can be enabled/disabled at any point. +For now, we just need to ensure the =server_name= is accurate. However, +there are a lot of other configuration options found in the +[[https://matrix-org.github.io/synapse/develop/usage/configuration/config_documentation.html][Configuring +Synapse]] documentation that can be enabled/disabled at any point. -```yaml +#+begin_src yaml server_name: "example.com" -``` +#+end_src Make sure to restart Synapse when you make changes to the configuration: -```sh +#+begin_src sh synctl restart -``` - -### Nginx Reverse-Proxy +#+end_src -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. +*** Nginx Reverse-Proxy +:PROPERTIES: +:CUSTOM_ID: nginx-reverse-proxy +:END: +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: -```sh +#+begin_src sh doas nano /etc/nginx/http.d/example.com.conf -``` +#+end_src -If you already have TLS certificates for this domain (`example.com`), you can -simply use the SSL configuration and point toward your TLS certificates. +If you already have TLS certificates for this domain (=example.com=), +you can simply use the SSL configuration and point toward your TLS +certificates. -```conf +#+begin_src conf server { listen 443 ssl http2; listen [::]:443 ssl http2; @@ -128,22 +139,23 @@ server { } server { - if ($host = example.com) { - return 301 https://$host$request_uri; - } + if ($host = example.com) { + return 301 https://$host$request_uri; + } server_name example.com; listen 80; - return 404; + return 404; } -``` +#+end_src -If you need to generate TLS certificates (I recommend -[Certbot](https://certbot.eff.org/)), 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: +If you need to generate TLS certificates (I recommend +[[https://certbot.eff.org/][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: -```conf +#+begin_src conf server { server_name example.com; location / { @@ -151,62 +163,67 @@ server { } listen 80; } -``` +#+end_src Once you're done editing the Nginx conf file, restart Nginx: -```sh +#+begin_src sh doas rc-service nginx restart -``` +#+end_src -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. +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: +You will need to stop Nginx in order to user the temporary web server +option with Certbot: -```sh +#+begin_src sh # Stop Nginx so certbot can spin up a temp webserver for cert generation doas rc-service nginx stop doas certbot certonly -v doas rc-service nginx start -``` - -### 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. +#+end_src + +*** Open Firewall & Router Ports +:PROPERTIES: +:CUSTOM_ID: open-firewall-router-ports +:END: +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: -```sh +#+begin_src sh # Matrix port doas ufw allow 8448 # Standard web server ports doas ufw allow "Nginx Full" -``` - -Remember to forward any Synapse ports, such as `8448`, `80`, and `443`, in your -Router from the internet to your server's IP address. +#+end_src -### Adding Matrix Users +Remember to forward any Synapse ports, such as =8448=, =80=, and =443=, +in your Router from the internet to your server's IP address. -Finally, if you didn't enable public registration in the `homeserver.yaml` file, -you can manually create users via the command-line: +*** Adding Matrix Users +:PROPERTIES: +:CUSTOM_ID: adding-matrix-users +:END: +Finally, if you didn't enable public registration in the +=homeserver.yaml= file, you can manually create users via the +command-line: -```sh +#+begin_src sh cd ~/synapse register_new_matrix_user -c homeserver.yaml -``` +#+end_src -Remember that the format for federated Matrix usernames is -`@username:example.com` when logging in to client applications. +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. +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. |