diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx
index 24a15257d..e90bf4b7b 100644
--- a/docs/calls/livekit.mdx
+++ b/docs/calls/livekit.mdx
@@ -95,7 +95,7 @@ You will need to allow ports `7881/tcp` and `50100:50200/udp` through your firew
### 3. Telling clients where to find LiveKit
-To tell clients where to find LiveKit, you need to add your `lk-jwt-service`'s address to the `[global.matrix_rtc] > foci` field of your Continuwuity config file.
+To tell clients where to find LiveKit, you need to add your `lk-jwt-service`'s address to the `foci` field of the `[global.matrix_rtc]` section of your Continuwuity config file.
The variable should be a list of servers serving as MatrixRTC endpoints. Replace the URL with the address you are deploying your instance of lk-jwt-service to:
@@ -146,7 +146,7 @@ All paths should be forwarded to LiveKit by default, with the exception of the f
**Note**: if you run Caddy inside a container (e.g. by following the example [here](../deploying/docker.mdx#caddy-using-caddyfile)) instead of on the host, then:
- - Put these containers on the same bridge network as caddy (by defining `networks: [ caddy ]` in each of the services), and
+ - Put these containers on the same bridge network as Caddy (by defining `networks: [ caddy ]` in each of the services), and
- Use appropriate container hostnames (`lk-jwt-service` and `livekit`) instead of `127.0.0.1` in the Caddyfile
@@ -284,7 +284,9 @@ Start up the services using your usual method - for example `docker compose up -
To test that LiveKit is successfully integrated with Continuwuity, you will need to replicate its [Token Exchange Flow](https://github.com/element-hq/lk-jwt-service#%EF%B8%8F-how-it-works--token-exchange-flow). Follow the steps below while checking Docker logs (`docker compose logs --follow`), in order to help [troubleshooting](#troubleshooting) any issues.
-First, you will need an access token for your current login session. These can be found in your client's settings or obtained via [this website](https://timedout.uk/mxtoken.html).
+First, you will need an access token for your current login session. These can be found in your client's settings or obtained via [this website][starstruck-mxtoken2].
+
+[starstruck-mxtoken2]: https://starstruck.systems/matrix/tools/mxtoken2
Then, using that token, fetch the discovery endpoints for MatrixRTC services:
@@ -396,7 +398,7 @@ After implementing the changes and restarting your compose, `lk-jwt-service` sho
### Incorrect IP address for LiveKit
-By default, LiveKit auto-discovers its public IP address(es), which is reflected in the "Establishing WebRTC connection" section of the connection test page. If these IPs are incorrect, you may want to hardcode your own IP by doing the following:
+By default, LiveKit automatically finds its public IP address(es), which can be seen in the "Establishing WebRTC connection" section of the connection test page. If these IPs are incorrect, you may want to hardcode your own IP by doing the following:
```diff
### in your livekit.yaml ###
@@ -439,8 +441,8 @@ Configurations:
Specifications:
-- [MSC4143 - MatrixRTC proposal][MSC4143]
-- [MSC4195 - LiveKit proposal][MSC4195]
+- [MSC4143 - MatrixRTC – Real-time communication over Matrix][MSC4143]
+- [MSC4195 - MatrixRTC Transport using LiveKit Backend][MSC4195]
[MSC4143]: https://github.com/matrix-org/matrix-spec-proposals/pull/4143
[MSC4195]: https://github.com/matrix-org/matrix-spec-proposals/pull/4195
@@ -465,7 +467,7 @@ Other:
### Additional TURNS-over-443 configuration
-Most of the time, LiveKit [**does not need TURN**][sspaeth-matrix-voip-turn] to function. However, there are situations where clients are in very restrictive networks that disallows non-standard ports and UDP. In these cases, a TURN-over-TLS server on port :443 could be employed to relay traffic for them.
+Most of the time, LiveKit [**does not need TURN**][sspaeth-matrix-voip-turn] to function. However, there are situations where clients may be unable to use nonstandard ports or UDP connections, such as in highly restrictive networks. In such cases, a TURN-over-TLS server on port 443 could relay traffic for the clients.
[sspaeth-matrix-voip-turn]: https://sspaeth.de/2026/04/matrix-voip-and-livekit/#turn
@@ -475,17 +477,19 @@ You can either use LiveKit's built-in TURN server, or integrate LiveKit with [co
Using LiveKit's built-in TURN server
-First, set up LiveKit's built-in TURN server with its own domain - we'll use `livekit-turn.example.com` in our example.
+First, set up LiveKit's built-in TURN server with its own domain - we will use `livekit-turn.example.com` in our example.
```yaml
## add this to `livekit.yaml` ##
turn:
enabled: true
- # note: the TLS port will always be advertised as :443
+ # Note: LiveKit will always advertise its TURNS-TLS port on 443,
+ # so further load balancing is needed to route from 443 back to
+ # the port being configured here
tls_port: 5349
- # optional: configure an extra UDP port on :3478
+ # Optional: configure an extra UDP port
# udp_port: 3478
relay_range_start: 50300
@@ -493,7 +497,7 @@ turn:
domain: livekit-turn.example.com
- # replace these with your actual cert/key files
+ # replace these with your actual certificate and key files
cert_file: /path/to/livekit-turn.example.com.crt
key_file: /path/to/livekit-turn.example.com.key
```
@@ -509,7 +513,7 @@ ports:
Recreate the LiveKit container (with `docker compose up -d livekit`) to apply these changes. Remember to allow the new `50300:50400/udp` ports through your firewall.
-Then, we will configure a route from port 443 of the host back to our `livekit-turn.example.com` service on port 5349. To both **multiplex** this and LiveKit's websocket on the same port, we will use a layer-4 reverse proxy with **SNI routing** capabilities, such as [caddy-l4][caddy-l4] on the host system.
+Then, configure a route from port 443 on the host back to the `livekit-turn.example.com` service on port 5349. To multiplex the service and LiveKit's websocket on the same port, use a layer 4 reverse proxy with SNI routing capabilities, such as [caddy-l4], on the host system.
```
## in your Caddyfile ##
@@ -531,8 +535,8 @@ Then, we will configure a route from port 443 of the host back to our `livekit-t
}
}
-# livekit stuff
-https://livekit.example.com {
+# livekit configuration
+livekit.example.com {
@lk-jwt-service path /healthz /get_token /sfu/get
route @lk-jwt-service {
reverse_proxy 127.0.0.1:8081
@@ -548,7 +552,7 @@ https://livekit.example.com {
Using an external TURN server (coturn)
-Before continuing, make sure coturn's `min-port` and `max-port` do not overlap with LiveKit's port range:
+First, make sure coturn's `min-port` and `max-port` do not overlap with LiveKit's port range:
```ini
# in your coturn.conf
@@ -556,9 +560,9 @@ min-port=50201
max-port=65535
```
-Then, generate a long random secret for LiveKit, and add it to your coturn config under the `static-auth-secret` option. You can add as many secrets as you want, so set a different one for LiveKit to use.
+Then, generate a long random TURN secret for LiveKit, and add it to your coturn config under the `static-auth-secret` option. You can add as many secrets as you want, so set a different one for LiveKit to use.
-After that, refer to the following [**TURN instructions**](./turn#turns-over-443) to set up coturn with TLS, as well as multiplexing with LiveKit's websocket on port 443.
+After that, refer to the following [TURNS-over-443 instructions](./turn#turns-over-443) to set up coturn with TLS, as well as multiplexing with LiveKit's websocket on port 443.
Then configure LiveKit, making sure to replace `COTURN_SECRET` with the one you generated:
@@ -577,4 +581,4 @@ Restart LiveKit, coturn, and Caddy-l4 to apply these changes.
-After finishing configuration, you can run the Testing steps again to check that TURN-over-TLS is working. In the LiveKit connection test page, there should be a green tick saying "Can connect to TURN".
+After you finish configuring the services, you can run the Testing steps again to check that TURNS-over-443 is working. There should now be a green tick in the [LiveKit connection test page][livekit-connection-test] with "Can connect to TURN" to confirm this is set up successfully.
diff --git a/docs/calls/turn.mdx b/docs/calls/turn.mdx
index 56ce3687d..1e462d069 100644
--- a/docs/calls/turn.mdx
+++ b/docs/calls/turn.mdx
@@ -1,8 +1,8 @@
# Setting up TURN/STUN
-[TURN][turn] and [STUN][stun] are used as a component in many calling systems. Matrix uses them directly for legacy calls and indirectly for MatrixRTC via Livekit.
+[TURN][turn] and [STUN][stun] are used as components in many calling systems. Matrix uses them directly for legacy calls and indirectly for MatrixRTC via Livekit.
-Continuwuity recommends using [Coturn][coturn] as your TURN/STUN server, which is available as a Docker image or a distro package. This guide assumes that you are using docker compose for deployment.
+Continuwuity recommends using [coturn][coturn] as your TURN/STUN server, which is available as a Docker image or a distro package. This guide assumes that you are using docker compose for deployment.
:::tip
You can find help setting up TURN/STUN in our MatrixRTC room - [#matrixrtc:continuwuity.org](https://matrix.to/#/%23matrixrtc%3Acontinuwuity.org)
@@ -14,11 +14,11 @@ You can find help setting up TURN/STUN in our MatrixRTC room - [#matrixrtc:conti
## Installing Coturn
-### 1. Domain
+### 1. Set up your domain
Coturn should live on its own domain or subdomain. In this guide we use `coturn.example.com` - this should be replaced with a domain you control.
-### 2. Configuration
+### 2. Configuring coturn
Create a configuration file called `coturn.conf` containing:
@@ -34,14 +34,14 @@ pwgen -s 64 1
```
:::
-If you want to enable TURN-over-TLS (TURNS), add the appropriate cert/key paths to your `coturn.conf` by adding the following lines:
+If you want to enable TURN-over-TLS (TURNS), add the appropriate certificate and key paths to your `coturn.conf` by adding the following lines:
```ini
cert=/etc/letsencrypt/coturn.example.com.crt
pkey=/etc/letsencrypt/coturn.example.com.key
```
-The cert and key must be encoded in PEM format and are readable by the coturn user.
+The cert and key must be encoded in PEM format and must be readable by the coturn user.
Check out the [`turnserver.conf`][turnserver-conf] example for all coturn options.
@@ -49,7 +49,7 @@ Check out the [`turnserver.conf`][turnserver-conf] example for all coturn option
### 3. Running the coturn container
-Next, we will start the Coturn container with the [official image][coturn-image]. **Host networking mode** will be used, as it is better for performance and reduces configuration complexity (see [Coturn Docker docs][coturn-docker-docs] for rationale).
+Next, we will start the Coturn container with the [official image][coturn-image]. **Host networking mode** is used here for better performance and reduced configuration complexity (see [Coturn Docker docs][coturn-docker-docs] for rationale).
[coturn-image]: https://hub.docker.com/r/coturn/coturn
[coturn-docker-docs]: https://github.com/coturn/coturn/blob/master/docker/coturn/README.md#why-so-many-ports-opened
@@ -57,7 +57,6 @@ Next, we will start the Coturn container with the [official image][coturn-image]
Create a `docker-compose.yml` file as follows and run `docker compose up -d`:
```yaml
-version: '3'
services:
coturn:
container_name: coturn
@@ -87,7 +86,7 @@ ufw allow 5349/udp
ufw allow 49152-65535/udp
```
-::: tip For LiveKit users
+:::tip For LiveKit users
If you're also running LiveKit, you'll need configure non-overlapping port ranges to avoid port conflicts:
@@ -108,8 +107,7 @@ This leaves ports `50100-50200` available for LiveKit's default configuration.
### 5. Security Recommendations
-For Coturn hardening and security best practices, see Synapse's [Coturn documentation][synapse-coturn-guide],
-which includes important firewall and access control recommendations.
+For Coturn hardening and security best practices, see Synapse's [Coturn documentation][synapse-coturn-guide], which includes important firewall and access control recommendations.
[synapse-coturn-guide]: https://element-hq.github.io/synapse/latest/setup/turn/coturn.html#configuration
@@ -142,7 +140,9 @@ Restart Continuwuity, and the new changes should now be applied.
### Testing Credentials
-Get an access token for your current login session. These can be found in your client's settings or obtained via [this website](https://timedout.uk/mxtoken.html).
+Get an access token for your current login session. These can be found in your client's settings or obtained via [this website][starstruck-mxtoken2].
+
+[starstruck-mxtoken2]: https://starstruck.systems/matrix/tools/mxtoken2
Then, using that token, verify that Continuwuity is correctly serving TURN credentials to clients:
@@ -172,7 +172,7 @@ Open the [Trickle ICE][trickle-ice] testing page in a browser and then:
1. Copy the URIs and credentials from the response above
2. Paste them into the Trickle ICE testing tool, and click on "Add server"
-3. When finished adding all URIs and credentials, click "Gather candidates"
+3. Once all the URIs and credentials have been added, click "Gather candidates"
If you see `relay` candidates in the results, your TURN/STUN server is working correctly! You should now be able to place and receive legacy calls.
@@ -180,7 +180,7 @@ If you see `relay` candidates in the results, your TURN/STUN server is working c
## Troubleshooting
-To gather debug logs while troubleshooting Coturn, add `verbose` to your `coturn.conf`. You can then view these logs with `docker-compose logs --follow coturn`.
+To gather debug logs while troubleshooting Coturn, add `verbose` to your `coturn.conf`. You can then view these logs with `docker compose logs --follow coturn`.
### Errors with Trickle ICE
@@ -192,7 +192,7 @@ To gather debug logs while troubleshooting Coturn, add `verbose` to your `coturn
- Ensure your `turn_secret` matches coturn's `static-auth-secret`
- Ensure the credentials you obtained from the Testing steps has not expired yet. You can adjust `turn_ttl` in your Continuwuity configuration to increase this, or simply re-request a new one
- Wrong IP address advertised
- - This may be caused by coturn not recognizing its public-facing IP correctly, due to particular network setups. You can configure `external-ip=` to fix this issue.
+ - This may be caused by coturn not recognizing its public-facing IP correctly. You can configure `external-ip=` to fix this issue.
### 404 when calling the turnServer endpoint
@@ -225,9 +225,9 @@ If you instead prefer to use [eturnal][eturnal], you can refer to the guides bel
### TURNS-over-443
-Normally, TURN would work on their default setups. However, there are situations where clients are in very restrictive networks that disallows non-standard ports and UDP. In these cases, a TURN-over-TLS server on port :443 could be employed to relay traffic for them.
+Normally, TURN would work on their default setups. However, there are situations where clients may be unable to use nonstandard ports or UDP connections, such as in highly restrictive networks. In such cases, a TURN-over-TLS (a.k.a. TURNS) server on port 443 could relay traffic for the clients.
-However, port 443 is usually utilized by other HTTPS services. Therefore, one would need to **multiplex** both TURN HTTPS on these ports, and filter packets to them via **SNI routing**.
+However, port 443 is usually utilized by other HTTPS services. Therefore, one would need to **multiplex** both TURNS and HTTPS on these ports, and filter packets to them via **SNI routing**.
Below are examples to multiplex Coturn and [LiveKit](./livekit.mdx) on port 443, using [caddy-l4][caddy-l4] on the host system.