From dca100ff164743a494f97901dec9531c1ac48c38 Mon Sep 17 00:00:00 2001 From: winyadepla Date: Thu, 22 Jan 2026 00:36:15 +0000 Subject: [PATCH] Update matrix_rtc.md to include TURN integration and be more in line with other tuwunel documentation --- docs/matrix_rtc.md | 109 ++++++++++++++++++++++++++++----------------- 1 file changed, 69 insertions(+), 40 deletions(-) diff --git a/docs/matrix_rtc.md b/docs/matrix_rtc.md index a941ca1f..a624ff35 100644 --- a/docs/matrix_rtc.md +++ b/docs/matrix_rtc.md @@ -1,29 +1,17 @@ -This is a basic "step by step" guide to setting up Element Call/MatrixRTC for Tuwunel. The aim is to provide the minimum amount of information necessary to get Element Call working, in a way that can be followed by anyone regardless of technical experience. Each step provides a brief description of what it is doing, followed by a suggested command to complete it. -This guide is inspired by [this blog post](https://sspaeth.de/2024/11/sfu/). For further information on setting up Element Call, please refer to that guide. - -***The following is very much based on my own experience of setting up Element Call for Tuwunel. Any amendments or additions are gratefully received.*** - -## Requirements -- A Linux server. -- A working Tuwunel installation. -- Docker and Docker Compose installed on the server. -- A Caddy or Nginx reverse proxy. -- A basic knowledge of how the above components work. +# Matrix RTC/Element Call Setup ## Notes -- My installation is on a Debian server. These instructions should work on other distributions, but I may have missed something. -- I use Caddy as a reverse proxy, and my Nginx knowledge is a bit rusty, so there is a chance that there are errors in the Nginx configuration provided. - `yourdomain.com` is whatever you have set as `server_name` in your tuwunel.toml. This needs to be replaced with the actual domain. It is assumed that you will be hosting MatrixRTC at `matrix-rtc.yourdomain.com`. If you wish to host this service at a different subdomain, this needs to be replaced as well. +- This guide provides example configuration for Caddy and Nginx reverse proxies. Others can be used, but the configuration will need to be adapted. -## 1. Set Up DNS +## Instructions +### 1. Set Up DNS Create a DNS record for `matrix-rtc.yourdomain.com` pointing to your server. -e.g. an `A` record for `matrix-rtc` pointing to `your.server.ip.address`. - -## 2. Create Docker Containers -1. Create a directory for your MatrixRTC setup: `mkdir /opt/matrix-rtc`. -2. Change directory to your new directory: `cd /opt/matrix-rtc`. -3. Create and open a compose.yaml file for MatrixRTC: `nano compose.yaml`. +### 2. Create Docker Containers +1. Create a directory for your MatrixRTC setup e.g. `mkdir /opt/matrix-rtc`. +2. Change directory to your new directory. e.g. `cd /opt/matrix-rtc`. +3. Create and open a compose.yaml file for MatrixRTC. e.g. `nano compose.yaml`. 4. Add the following. `mrtckey` and `mrtcsecret` should be random strings. It is suggested that `mrtckey` is 20 characters and `mrtcsecret` is 64 characters. ```yaml services: @@ -52,9 +40,9 @@ services: volumes: - ./livekit.yaml:/etc/livekit.yaml:ro ``` -4. Close the file: `Ctrl+x`. -5. Create and open a livekit.yaml file: `nano livekit.yaml`. -6. Add the following. `mrtckey` and `mrtcsecret` should be the same as those from the compose.yaml. +4. Close the file. +5. Create and open a livekit.yaml file. e.g. `nano livekit.yaml`. +6. Add the following. `mrtckey` and `mrtcsecret` should be the same as those from compose.yaml. ```yaml port: 7880 bind_addresses: @@ -68,12 +56,12 @@ rtc: keys: mrtckey: "mrtcsecret" ``` -7. Close the file: `Ctrl+x`. +7. Close the file. -## 3. Configure .well-known -### 3.1. .well-known served by Tuwunel +### 3. Configure .well-known +#### 3.1. .well-known served by Tuwunel ***Follow this step if your .well-known configuration is served by tuwunel. Otherwise follow Step 3.2*** -1. Open your tuwunel.toml file: e.g. `nano /etc/tuwunel/tuwunel.toml`. +1. Open your tuwunel.toml file. e.g. `nano /etc/tuwunel/tuwunel.toml`. 2. Find the line reading `#rtc_transports = []` and edit it to be: ```toml rtc_transports = [ @@ -83,11 +71,11 @@ rtc_transports = [ } ] ``` -3. Close the file: `Ctrl+x`. +3. Close the file. -### 3.2. .well-known served independently +#### 3.2. .well-known served independently ***Follow this step if you serve your .well-known/matrix files directly. Otherwise follow Step 3.1*** -1. Open your .well-known/matrix/client file: e.g. `nano /var//www/.well-known/matrix/client`. +1. Open your `.well-known/matrix/client` file. e.g. `nano /var//www/.well-known/matrix/client`. 2. Add the following: ```json "org.matrix.msc4143.rtc_foci": [ @@ -112,17 +100,17 @@ The final file should look something like this: } ``` -3. Close the file: `Ctrl+x`. +3. Close the file. -## 4. Configure Firewall +### 4. Configure Firewall You will need to allow ports `7881/tcp` and `50100:50200/udp` through your firewall. If you use UFW, the commands are: `ufw allow 7881/tcp` and `ufw allow 50100:50200/udp`. -## 5. Configure Reverse Proxy -As reverse proxies can be installed in different ways, I am not giving step by step instructions for this section. +### 5. Configure Reverse Proxy +As reverse proxies can be installed in different ways, step by step instructions are not given for this section. If you use Caddy as your reverse proxy, follow step 5.1. If you use Nginx, follow step 5.2. -### 5.1. Caddy -1. The following needs to be added to your Caddyfile. If you are running Caddy in Docker, replace `localhost` with `matrix-rtc-jwt` in the first instance, and `matrix-rtc-livekit` in the second. +#### 5.1. Caddy +1. Add the following to your Caddyfile. If you are running Caddy in Docker, replace `localhost` with `matrix-rtc-jwt` in the first instance, and `matrix-rtc-livekit` in the second. ``` matrix-rtc.yourdomain.com { # This is matrix-rtc-jwt @@ -154,8 +142,8 @@ matrix-rtc.yourdomain.com { ``` 2. Restart Caddy. -### 5.2. Nginx -1. The following needs to be added to your Nginx configuration: +#### 5.2. Nginx +1. Add the following to your Nginx configuration. If you are running Nginx in Docker, replace `localhost` with `matrix-rtc-jwt` in the first instance, and `matrix-rtc-livekit` in the second. ``` server { listen 443 ssl; @@ -208,8 +196,49 @@ server { ``` 2. Restart Nginx. -## 6. Start Docker Containers -1. Ensure you are in your matrix-rtc directory: `cd /opt/matrix-rtc`. +### 6. Start Docker Containers +1. Ensure you are in your matrix-rtc directory. e.g. `cd /opt/matrix-rtc`. 2. Start containers: `docker compose up -d`. Element Call should now be working. + +## Additional Configuration +### TURN Integration +If you follow this guide, and also set up Coturn as per the tuwunel documentation, there will be a port clash between the two services. To avoid this, the following must be added to your `coturn.conf`: +``` +min-port=50201 +max-port=65535 +``` + +If you have Coturn configured, you can use it as a TURN server for Livekit to improve call reliability. Unfortunately, Livekit does not support using static-auth-secret to authenticate with TURN servers, and you cannot combine credential and auth-secret authentication. Luckily, it is possible to use multiple instances of `static-auth-secret` within you `turnserver.conf`, and you can generate a username and password from the secret as a workaround. + +1. To create a credential for use with Livekit and Coturn, run the following command. AUTH_SECRET should be replaced with a 64 digit alphanumeric string. For more information on the command see [this post](https://wiki.lenuagemagique.com/doku.php?id=unable_to_use_lt-cred-mech_webrtc_and_static-auth-secret_restapi_at_the_same_time). +``` +secret=AUTH_SECRET && \ +time=$(date +%s) && \ +expiry=8640000 && \ +username=$(( $time + $expiry )) && \ +echo username: $username && \ +echo password: $(echo -n $username | openssl dgst -binary -sha1 -hmac $secret | openssl base64) +``` +This should produce output in the following format: +``` +username: USERNAME +password: PASSWORD +``` +2. Add the following line to the end of your `turnserver.conf`. AUTH_SECRET is the same as that used in Step 1. +``` +static-auth-secret=AUTH_SECRET +``` +3. Add the following to the end of the `rtc` block in your `livekit.yaml`. USERNAME and PASSWORD should be replaced with the corresponding values in the output of Step 1. `turn.yourdomain.com` should be replaced with your actual turn domain. +``` + turn_servers: + - host: turn.yourdomain.com + port: 5349 + protocol: tls + username: "USERNAME" + credential: "PASSWORD" +``` + +### Using the Livekit Built In TURN Server +It is also possible to use the built in Livekit TURN server. Getting this to work can be a somewhat involved process, and a TURN server is not usually required for Matrix RTC calls. Consequently, instructions are not provided here at this time. If you would like to configure this, more information can be found [here](https://docs.livekit.io/transport/self-hosting/deployment/#improving-connectivity-with-turn).