From 10083cec942df9beb7d47eaec9ca88f55a9c8ff8 Mon Sep 17 00:00:00 2001 From: winyadepla Date: Mon, 2 Feb 2026 17:15:26 +0000 Subject: [PATCH 1/4] Update matrix_rtc.md for readability and to remove deprecated livekit option. --- docs/matrix_rtc.md | 48 +++++++++++++++++----------------------------- 1 file changed, 18 insertions(+), 30 deletions(-) diff --git a/docs/matrix_rtc.md b/docs/matrix_rtc.md index 5e71a5e0..34fa4380 100644 --- a/docs/matrix_rtc.md +++ b/docs/matrix_rtc.md @@ -1,8 +1,9 @@ # Matrix RTC/Element Call Setup ## Notes +- This guide assumes that you are using docker compose for deployment. - `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. +- This guide provides example configuration for Caddy, Nginx and Traefik reverse proxies. Others can be used, but the configuration will need to be adapted. ## Instructions ### 1. Set Up DNS @@ -12,37 +13,38 @@ Create a DNS record for `matrix-rtc.yourdomain.com` pointing to your server. 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. +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: matrix-rtc-jwt: image: ghcr.io/element-hq/lk-jwt-service:latest container_name: matrix-rtc-jwt environment: - - LIVEKIT_JWT_PORT=8081 + - LIVEKIT_JWT_BIND=:8080 - LIVEKIT_URL=wss://matrix-rtc.yourdomain.com - - LIVEKIT_KEY=mrtckey - - LIVEKIT_SECRET=mrtcsecret + - LIVEKIT_KEY=MRTCKEY + - LIVEKIT_SECRET=MRTCSECRET - LIVEKIT_FULL_ACCESS_HOMESERVERS=yourdomain.com restart: unless-stopped ports: - - "8081:8081" + - "8081:8080" matrix-rtc-livekit: image: livekit/livekit-server:latest container_name: matrix-rtc-livekit command: --config /etc/livekit.yaml - ports: - - 7880:7880/tcp - - 7881:7881/tcp - - 50100-50200:50100-50200/udp restart: unless-stopped volumes: - ./livekit.yaml:/etc/livekit.yaml:ro + network_mode: "host" + # Uncomment the lines below and comment `network_mode: "host"` above to specify port mappings. +# ports: +# - "7880:7880/tcp" +# - "7881:7881/tcp" +# - "50100-50200:50100-50200/udp" ``` -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. +6. Add the following. `MRTCKEY` and `MRTCSECRET` should be the same as those from compose.yaml. ```yaml port: 7880 bind_addresses: @@ -54,13 +56,12 @@ rtc: use_external_ip: true enable_loopback_candidate: false keys: - mrtckey: "mrtcsecret" + MRTCKEY: MRTCSECRET ``` -7. Close the file. ### 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*** +***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`. 2. Find the line reading `#rtc_transports = []` and replace it with: ```toml @@ -68,7 +69,6 @@ keys: type = "livekit" livekit_service_url = "https://matrix-rtc.yourdomain.com" ``` -3. Close the file. #### 3.2. .well-known served independently ***Follow this step if you serve your .well-known/matrix files directly. Otherwise follow Step 3.1*** @@ -97,14 +97,13 @@ The final file should look something like this: } ``` -3. Close the file. ### 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, 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. +If you use Caddy as your reverse proxy, follow step 5.1. If you use Nginx, follow step 5.2. If you use Traefik, follow step 5.3. #### 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. @@ -115,24 +114,13 @@ matrix-rtc.yourdomain.com { path /sfu/get* /healthz* } handle @jwt_service { - reverse_proxy localhost:8081 { - header_up Host {host} - header_up X-Forwarded-Server {host} - header_up X-Real-IP {remote} - header_up X-Forwarded-For {remote} - header_up X-Forwarded-Proto {scheme} - } + reverse_proxy localhost:8081 } # This is livekit handle { reverse_proxy localhost:7880 { header_up Connection "upgrade" header_up Upgrade {http.request.header.Upgrade} - header_up Host {host} - header_up X-Forwarded-Server {host} - header_up X-Real-IP {remote} - header_up X-Forwarded-For {remote} - header_up X-Forwarded-Proto {scheme} } } } From 648bd8d12a52ac7b61092fb7fe2653c5a4b0caa9 Mon Sep 17 00:00:00 2001 From: winyadepla Date: Mon, 2 Feb 2026 17:22:17 +0000 Subject: [PATCH 2/4] Undo port change for matrix-rtc-jwt --- docs/matrix_rtc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/matrix_rtc.md b/docs/matrix_rtc.md index 34fa4380..fa6bb6d5 100644 --- a/docs/matrix_rtc.md +++ b/docs/matrix_rtc.md @@ -20,14 +20,14 @@ services: image: ghcr.io/element-hq/lk-jwt-service:latest container_name: matrix-rtc-jwt environment: - - LIVEKIT_JWT_BIND=:8080 + - LIVEKIT_JWT_BIND=:8081 - LIVEKIT_URL=wss://matrix-rtc.yourdomain.com - LIVEKIT_KEY=MRTCKEY - LIVEKIT_SECRET=MRTCSECRET - LIVEKIT_FULL_ACCESS_HOMESERVERS=yourdomain.com restart: unless-stopped ports: - - "8081:8080" + - "8081:8081" matrix-rtc-livekit: image: livekit/livekit-server:latest From 5b16c6fcf4ff26a109ee354abdbb1e12f0e06b66 Mon Sep 17 00:00:00 2001 From: winyadepla Date: Mon, 2 Feb 2026 17:25:15 +0000 Subject: [PATCH 3/4] Update matrix_rtc.md to add configuration for the built in Livekit TURN server --- docs/matrix_rtc.md | 61 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 4 deletions(-) diff --git a/docs/matrix_rtc.md b/docs/matrix_rtc.md index fa6bb6d5..56b3a131 100644 --- a/docs/matrix_rtc.md +++ b/docs/matrix_rtc.md @@ -260,14 +260,14 @@ http: 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`: +### External 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. As Coturn allows multiple instances of `static-auth-secret`, it is suggested that the secret used for Livekit is different to that used for tuwunel. +If you have Coturn configured, you can use it as a TURN server for Livekit to improve call reliability. As Coturn allows multiple instances of `static-auth-secret`, it is suggested that the secret used for Livekit is different to that used for Tuwunel. 1. Create a secret for Coturn. It is suggested that this should be a random 64 character alphanumeric string. 2. Add the following line to the end of your `turnserver.conf`. `AUTH_SECRET` is the secret created in Step 1. @@ -284,4 +284,57 @@ static-auth-secret=AUTH_SECRET ``` ### 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). +Livekit includes a built in TURN server which can be used in place of an external option. +It should be noted that this TURN server will only work with Livekit, and is not compatible with traditional Matrix calling. For that, see the section on [TURN](turn.md). + +#### Basic Setup +The simplest way to enable this is to add the following to your `livekit.yaml`: +``` +turn: + enabled: true + udp_port: 3478 + relay_range_start: 50300 + relay_range_end: 65535 + domain: matrix-rtc.yourdomain.com +``` +It is strongly recommended that you use `network_mode: "host"`; however if it is necessary to specify port mappings, the following ports should be added to `matrix-rtc-livekit` in your `compose.yaml`: +``` + - 3478:3478/udp + - 50300-65535:50300-65535/udp +``` + +You will need to allow ports `3478` and `50300:65535/udp` through your firewall. If you use UFW, the commands are: `ufw allow 3478` and `ufw allow 50300:65535/udp`. + +#### Setup With TLS +To enable TLS for the TURN server, the process is slightly more complicated. +Some WebRTC software will not accept certificates provided by Let's Encrypt. It is therefore suggested that you use [ZeroSSL](https://zerossl.com/) as an alternative. + +1. Create a DNS record for e.g. `matrix-turn.yourdomain.com` pointing to your server. +2. Get a certificate for this subdomain. +3. Add the certificates as volumes for `matrix-rtc-livekit` in your `compose.yaml`. +For example: +``` + - ./certs/privkey.pem:/certs/privkey.pem:ro + - ./certs/fullchain.pem:/certs/fullchain.pem:ro +``` +4. Add the following to the bottom of your `livekit.yaml`. The values for `cert_file` and `key_file` should match where these files are mounted in the container. +``` +turn: + enabled: true + udp_port: 3478 + tls_port: 5349 + relay_range_start: 50300 + relay_range_end: 65535 + external_tls: false + domain: matrix-turn.yourdomain.com + cert_file: /certs/fullchain.pem + key_file: /certs/privkey.pem +``` +5. It is strongly recommended that you use `network_mode: "host"`; however if it is necessary to specify port mappings, the following ports should be added to `matrix-rtc-livekit` in your `compose.yaml`: +``` + - 3478:3478/udp + - 5349:5349/tcp + - 50300-65535:50300-65535/udp +``` +5. You will need to allow ports `3478`, `5349` and `50300:65535/udp` through your firewall. If you use UFW, the commands are: `ufw allow 3478`, `ufw allow 5349` and `ufw allow 50300:65535/udp`. +6. Restart the containers. From c4c37d0c3daaeaf6077a3cd54936783f7b152df8 Mon Sep 17 00:00:00 2001 From: winyadepla Date: Mon, 2 Feb 2026 17:29:18 +0000 Subject: [PATCH 4/4] Update matrix_rtc.md for clarity --- docs/matrix_rtc.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/matrix_rtc.md b/docs/matrix_rtc.md index 56b3a131..6bb73c04 100644 --- a/docs/matrix_rtc.md +++ b/docs/matrix_rtc.md @@ -299,6 +299,7 @@ turn: ``` It is strongly recommended that you use `network_mode: "host"`; however if it is necessary to specify port mappings, the following ports should be added to `matrix-rtc-livekit` in your `compose.yaml`: ``` +ports: - 3478:3478/udp - 50300-65535:50300-65535/udp ``` @@ -314,6 +315,7 @@ Some WebRTC software will not accept certificates provided by Let's Encrypt. It 3. Add the certificates as volumes for `matrix-rtc-livekit` in your `compose.yaml`. For example: ``` +volumes: - ./certs/privkey.pem:/certs/privkey.pem:ro - ./certs/fullchain.pem:/certs/fullchain.pem:ro ``` @@ -332,6 +334,7 @@ turn: ``` 5. It is strongly recommended that you use `network_mode: "host"`; however if it is necessary to specify port mappings, the following ports should be added to `matrix-rtc-livekit` in your `compose.yaml`: ``` +ports: - 3478:3478/udp - 5349:5349/tcp - 50300-65535:50300-65535/udp