@@ -215,0 +394,4 @@
+By default, TURN credentials require client authentication. To allow unauthenticated access:
+
+```toml
+turn_allow_guests = true

@@ -215,0 +302,4 @@
+
+```
+{
+    servers {

@@ -90,3 +96,3 @@
 ### 3. Telling clients where to find LiveKit
 
-To tell clients where to find LiveKit, you need to add the address of your `lk-jwt-service` to the `[global.matrix_rtc]` config section using the `foci` option.
+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.

@@ -100,6 +106,12 @@ foci = [
 ]
 ```
 
+If you configure Continuwuity via environment variables, use the following:

@@ -134,1 +146,4 @@
 
+    **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

@@ -135,0 +147,4 @@
+    **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
+    - Use appropriate container hostnames (`lk-jwt-service` and `livekit`) instead of `127.0.0.1` in the Caddyfile

@@ -442,1 +396,4 @@
 
+### 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:

@@ -475,0 +457,4 @@
+
+Other:
+
+- [Matrix VOIP and LiveKit][sspaeth-matrix-voip] - Community member deep dive on current VOIP solutions on Matrix

@@ -475,0 +464,4 @@
+## Appendix
+
+### Additional TURNS-over-443 configuration
+

@@ -475,0 +465,4 @@
+
+### 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.

@@ -475,0 +482,4 @@
+turn:
+  enabled: true
+
+  # note: the TLS port will always be advertised as :443

@@ -462,2 +428,2 @@
-- [Community guide with overview of LiveKit's mechanisms](https://tomfos.tr/matrix/livekit/)
-- [Community guide using systemd](https://blog.kimiblock.top/2024/12/24/hosting-element-call/)
+- [Element Call self-hosting documentation from element-hq][element-call-selfhosting]
+- [Community guide with overview of LiveKit's mechanisms][tom-livekit-guide]

@@ -475,0 +485,4 @@
+  # note: the TLS port will always be advertised as :443
+  tls_port: 5349
+
+  # optional: configure an extra UDP port on :3478

@@ -475,0 +507,4 @@
+  # "3478:3478/udp" # (optional UDP port)
+```
+
+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.

@@ -467,2 +442,2 @@
-- [MSC4143 - MatrixRTC proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)
-- [MSC4195 - LiveKit proposal](https://github.com/matrix-org/matrix-spec-proposals/pull/4195)
+- [MSC4143 - MatrixRTC proposal][MSC4143]
+- [MSC4195 - LiveKit proposal][MSC4195]

@@ -475,0 +499,4 @@
+```
+
+```yaml
+### add these ports to livekit's docker-compose ###

@@ -475,0 +509,4 @@
+
+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.

@@ -475,0 +532,4 @@
+}
+
+# livekit stuff
+https://livekit.example.com {

@@ -475,0 +548,4 @@
+<details>
+<summary>Using an external TURN server (coturn)</summary>
+
+Before continuing, make sure coturn's `min-port` and `max-port` do not overlap with LiveKit's port range:

@@ -475,0 +556,4 @@
+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.

@@ -475,0 +558,4 @@
+
+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.
+
+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.

@@ -475,0 +573,4 @@
+      secret: "COTURN_SECRET"
+```
+
+Restart LiveKit, coturn, and Caddy-l4 to apply these changes.

@@ -475,0 +577,4 @@
+
+</details>
+
+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".

@@ -1,36 +1,95 @@
 # Setting up TURN/STUN
 
-[TURN](https://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT) and [STUN](https://en.wikipedia.org/wiki/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 a component in many calling systems. Matrix uses them directly for legacy calls and indirectly for MatrixRTC via Livekit.

@@ -4,2 +3,3 @@
+[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.
 
-Continuwuity recommends using [Coturn](https://github.com/coturn/coturn) as your TURN/STUN server, which is available as a Docker image or a distro package.
+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.

@@ -7,3 +15,3 @@
 ## Installing Coturn
 
-### Configuration
+### 1. Domain

@@ -24,3 +35,3 @@
 :::
 
-#### Port Configuration
+If you want to enable TURN-over-TLS (TURNS), add the appropriate cert/key paths to your `coturn.conf` by adding the following lines:

@@ -27,0 +41,4 @@
+pkey=/etc/letsencrypt/coturn.example.com.key
+```
+
+The cert and key must be encoded in PEM format and are readable by the coturn user.

@@ -27,0 +43,4 @@
+
+The cert and key must be encoded in PEM format and are readable by the coturn user.
+
+Check out the [`turnserver.conf`][turnserver-conf] example for all coturn options.

@@ -27,0 +49,4 @@
+
+### 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).

@@ -27,0 +57,4 @@
+Create a `docker-compose.yml` file as follows and run `docker compose up -d`:
+
+```yaml
+version: '3'

@@ -31,3 +78,3 @@
 - `49152-65535` (UDP): Media relay ports
 
-If you're also running LiveKit, you'll need to avoid port conflicts. Configure non-overlapping port ranges:
+You will need to allow them through your firewall. If you use UFW, the commands are:

@@ -34,0 +87,4 @@
+ufw allow 49152-65535/udp
+```
+
+::: tip For LiveKit users

@@ -39,2 +98,4 @@
 ```
 
+```bash
+# With ufw

@@ -74,2 +109,3 @@
+### 5. Security Recommendations
 
-For security best practices, see Synapse's [Coturn documentation](https://element-hq.github.io/synapse/latest/turn-howto.html), which includes important firewall and access control recommendations.
+For Coturn hardening and security best practices, see Synapse's [Coturn documentation][synapse-coturn-guide],

@@ -146,3 +143,3 @@
 ### Testing Credentials
 
-Verify that Continuwuity is correctly serving TURN credentials to clients:
+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).

@@ -182,1 +173,3 @@
-4. Look for successful `relay` candidates in the results
+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"

@@ -186,3 +181,3 @@
 ## Troubleshooting
 
-### Clients can't connect to TURN server
+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`.

@@ -196,0 +192,4 @@
+  - 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=<desired-public-ip>` to fix this issue.

@@ -215,0 +225,4 @@
+
+### 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.

@@ -29,19 +29,12 @@ we can't cross-build static binaries - contributions are welcome here.