From cacd8681d113f6ed29514f30528044083c3f2c93 Mon Sep 17 00:00:00 2001 From: Jade Ellis Date: Mon, 16 Feb 2026 02:55:26 +0000 Subject: [PATCH] docs: Update & apply feedback --- docs/calls.mdx | 10 +++---- docs/calls/livekit.mdx | 59 ++++++++++++++++++++++++++++++------------ docs/calls/turn.mdx | 4 +-- 3 files changed, 48 insertions(+), 25 deletions(-) diff --git a/docs/calls.mdx b/docs/calls.mdx index b005e15d..681783ca 100644 --- a/docs/calls.mdx +++ b/docs/calls.mdx @@ -2,16 +2,12 @@ Matrix supports two types of calls: -- Element Call powered by MatrixRTC -- Legacy calls, usually using Jitsi +- Element Call powered by [MatrixRTC](https://half-shot.github.io/msc-crafter/#msc/4143) and [LiveKit](https://github.com/livekit/livekit) +- Legacy calls, sometimes using Jitsi Both types of calls are supported by different sets of clients, but most clients are moving towards MatrixRTC / Element Call. For either one to work correctly, you have to do some additional setup. - For legacy calls to work, you need to set up a TURN/STUN server. [Read the TURN guide for tips on how to set up coturn](./calls/turn.mdx) -- For MatrixRTC to work, you have to set up the LiveKit backend (foci). LiveKit also uses TURN/STUN to increase reliability, so you might want to configure your TURN server first. [Read the LiveKit guide](./calls/livekit.mdx) - -:::warning -Element X is known to not be able to do calls on Continwuity. [Track this bug to get updated when the issue is fixed](https://forgejo.ellis.link/continuwuation/continuwuity/issues/1306) -::: +- For MatrixRTC / Element Call to work, you have to set up the LiveKit backend (foci). LiveKit also uses TURN/STUN to increase reliability, so you might want to configure your TURN server first. [Read the LiveKit guide](./calls/livekit.mdx) diff --git a/docs/calls/livekit.mdx b/docs/calls/livekit.mdx index ee828780..a35434ff 100644 --- a/docs/calls/livekit.mdx +++ b/docs/calls/livekit.mdx @@ -14,7 +14,7 @@ Make sure the DNS record for the (sub)domain you plan to use is pointed to your ### 2. Services -Using LiveKit with matrix requires two services - Livekit itself, and a service (`lk-jwt-service`) that grants Matrix users permission to connect to it. +Using LiveKit with Matrix requires two services - Livekit itself, and a service (`lk-jwt-service`) that grants Matrix users permission to connect to it. You must generate a key and secret to allow the Matrix service to authenticate with LiveKit. `LK_MATRIX_KEY` should be around 20 random characters, and `LK_MATRIX_SECRET` should be around 64. Remember to replace these with the actual values! @@ -27,22 +27,22 @@ docker run --rm livekit/livekit-server:latest generate-keys ```yaml services: - matrix-rtc-jwt: + lk-jwt-service: image: ghcr.io/element-hq/lk-jwt-service:latest - container_name: matrix-rtc-jwt + container_name: lk-jwt-service environment: - LIVEKIT_JWT_BIND=:8081 - LIVEKIT_URL=wss://livekit.example.com - LIVEKIT_KEY=LK_MATRIX_KEY - LIVEKIT_SECRET=LK_MATRIX_SECRET - - LIVEKIT_FULL_ACCESS_HOMESERVERS=yourdomain.com + - LIVEKIT_FULL_ACCESS_HOMESERVERS=example.com restart: unless-stopped ports: - "8081:8081" - matrix-rtc-livekit: + livekit: image: livekit/livekit-server:latest - container_name: matrix-rtc-livekit + container_name: livekit command: --config /etc/livekit.yaml restart: unless-stopped volumes: @@ -78,15 +78,9 @@ 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 the domain address of the LiveKit server to the continuwuity.toml config file. To do so, in the config section `global.well-known`, add (or modify) the option `rtc_focus_server_urls`. +To tell clients where to find LiveKit, you need to add the address of your `lk-jwt-service` to your client .well-known file. To do so, in the config section `global.well-known`, add (or modify) the option `rtc_focus_server_urls`. -The variable should be a vector (i.e. list) of servers serving as MatrixRTC endpoints to serve in the well-known file to the client. - -To add your own matrix-rtc-jwt deployment, add -```toml - { type = "livekit", livekit_service_url = "https://livekit.example.com" }, -``` -to the vector. If it's the only endpoint, the final configuration option will look something like this: +The variable should be a list of servers serving as MatrixRTC endpoints to serve in the well-known file to the client. ```toml rtc_focus_server_urls = [ @@ -94,11 +88,11 @@ rtc_focus_server_urls = [ ] ``` -Remember to replace the URL with the address you are deploying your instance of matrix-rtc-jwt to. +Remember to replace the URL with the address you are deploying your instance of lk-jwt-service to. #### Serving .well-known manually -If you don't let Continuwuity serve your .well-known files, you need to add the following lines to your .well-known/matrix/client file, remembering to replace the URL with your own matrix-rtc-jwt deployment: +If you don't let Continuwuity serve your `.well-known` files, you need to add the following lines to your `.well-known/matrix/client` file, remembering to replace the URL with your own `lk-jwt-service` deployment: ```json "org.matrix.msc4143.rtc_foci": [ @@ -135,6 +129,34 @@ By default, all routes should be forwarded to Livekit with the exception of the - `/healthz` - `/get_token` +
+ Example caddy config + ``` + matrix-rtc.example.com { + + # for lk-jwt-service + @lk-jwt-service path /sfu/get* /healthz* /get_token* + route @lk-jwt-service { + reverse_proxy 127.0.0.1:8080 + } + + # for livekit + reverse_proxy 127.0.0.1:7880 + } + ``` +
+ +
+ Example traefik router + ``` + # on LiveKit itself + traefik.http.routers.livekit.rule=Host(`livekit.example.com`) + # on the JWT service + traefik.http.routers.livekit-jwt.rule=Host(`livekit.example.com`) && (PathPrefix(`/sfu/get`) || PathPrefix(`/healthz`) || PathPrefix(`/get_token`)) + ``` +
+ + ### 6. Start Everything Start up the services using your usual method - for example `docker compose up -d`. @@ -200,3 +222,8 @@ turn: - [LiveKit GitHub](https://github.com/livekit/livekit) - [LiveKit Connection Tester](https://livekit.io/connection-test) - use with the token returned by `/sfu/get` or `/get_token` +- [MatrixRTC proposal](https://half-shot.github.io/msc-crafter/#msc/4143) +- [Synapse documentation](https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md) +- [Community guide](https://tomfos.tr/matrix/livekit/) +- [Community guide](https://blog.kimiblock.top/2024/12/24/hosting-element-call/) +- diff --git a/docs/calls/turn.mdx b/docs/calls/turn.mdx index c3345ffb..ddce4673 100644 --- a/docs/calls/turn.mdx +++ b/docs/calls/turn.mdx @@ -120,7 +120,7 @@ turn_password = "your_password" ``` :::warning -Static credentials are less secure than shared secrets because they don't expire and must be configured in coturn separately. Use shared secret authentication. +Static credentials are less secure than shared secrets because they don't expire and must be configured in coturn separately. It is strongly advised you use shared secret authentication. ::: ### Guest Access @@ -132,7 +132,7 @@ turn_allow_guests = true ``` :::caution -This is not recommended as it allows unauthenticated users to access your TURN server, potentially enabling abuse by bots. All major Matrix clients support authenticated TURN access. +This is not recommended as it allows unauthenticated users to access your TURN server, potentially enabling abuse by bots. All major Matrix clients that support legacy calls *also* support authenticated TURN access. ::: ### Important Notes