From 7cb33c5519dbb6b575afe103c187e1a1d398530a Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 9 Apr 2025 16:49:18 +0300 Subject: [PATCH] Add support for easily installing the Matrix RTC stack, without the Element Call frontend (#4242) --- CHANGELOG.md | 24 ++++++++ docs/configuring-playbook-element-call.md | 29 +++++++-- ...onfiguring-playbook-livekit-jwt-service.md | 4 +- docs/configuring-playbook-livekit-server.md | 2 +- docs/configuring-playbook-matrix-rtc.md | 59 +++++++++++++++++++ docs/configuring-playbook.md | 8 ++- group_vars/matrix_servers | 18 +++--- .../matrix-element-call/defaults/main.yml | 9 +++ 8 files changed, 132 insertions(+), 21 deletions(-) create mode 100644 docs/configuring-playbook-matrix-rtc.md diff --git a/CHANGELOG.md b/CHANGELOG.md index efe68fa44..84b1dd658 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,27 @@ +# 2025-04-09 + +## Element Call frontend installation is now optional + +Because all Element clients (Element Web and Element X mobile) now embed and use their own Element Call frontend application (and not the one hosted via the playbook), it makes little sense for the playbook to self-host the Element Call frontend for you. Setting up the frontend requires an additional hostname (DNS setup) and it won't be used by Element clients anyway, so **we now recommend not installing the Element Call frontend**. + +💡 A reason you may wish to continue installing the Element Call frontend (despite Matrix clients not making use of it), is if you need to use it standalone - directly via a browser (without a Matrix client). + +The playbook now lets you [Decide between Element Call vs just the Matrix RTC stack](./docs/configuring-playbook-element-call.md#decide-between-element-call-vs-just-the-matrix-rtc-stack). + +If you've already installed Element Call (via `matrix_element_call_enabled: true`), you can switch to installing just the [Matrix RTC (Real-Time Communication) stack](./docs/configuring-playbook-matrix-rtc.md) (all supporting services **without the Element Call frontend**) by: + +1. Adjusting your `vars.yml` configuration like this: + +```diff +-matrix_element_call_enabled: true ++matrix_rtc_enabled: true +``` + +2. [Re-running the playbook](./docs/installing.md) with the `setup-all` Ansible tag (e.g. `just setup-all`) + +3. Getting rid of the `call.element.example.com` DNS record + + # 2025-03-15 ## Element Call support diff --git a/docs/configuring-playbook-element-call.md b/docs/configuring-playbook-element-call.md index 87677b546..109d0f400 100644 --- a/docs/configuring-playbook-element-call.md +++ b/docs/configuring-playbook-element-call.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later # Setting up Element Call (optional) -The playbook can install and configure [Element Call](https://github.com/element-hq/element-call) for you. +The playbook can install and configure [Element Call](https://github.com/element-hq/element-call) and its supporting components that are part of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md). Element Call is a native Matrix video conferencing application developed by [Element](https://element.io), designed for secure, scalable, privacy-respecting, and decentralized video and voice calls over the Matrix protocol. Built on MatrixRTC ([MSC4143](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)), it utilizes [MSC4195](https://github.com/hughns/matrix-spec-proposals/blob/hughns/matrixrtc-livekit/proposals/4195-matrixrtc-livekit.md) with [LiveKit Server](configuring-playbook-livekit-server.md) as its backend. @@ -16,18 +16,33 @@ See the project's [documentation](https://github.com/element-hq/element-call) to ## Prerequisites - A [Synapse](configuring-playbook-synapse.md) homeserver (see the warning below) -- [Federation](configuring-playbook-federation.md) being enabled for your Matrix homeserver (federation is enabled by default, unless you've explicitly disabled it), because [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) currently [requires it](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3562#issuecomment-2725250554) ([relevant source code](https://github.com/element-hq/lk-jwt-service/blob/f5f5374c4bdcc00a4fb13d27c0b28e20e4c62334/main.go#L135-L146)) -- Various experimental features for the Synapse homeserver which Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) (automatically done when Element Call is enabled) -- A [LiveKit Server](configuring-playbook-livekit-server.md) (automatically installed when Element Call is enabled) -- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when Element Call is enabled) +- The [Matrix RTC (Real-Time Communication) stack](configuring-playbook-matrix-rtc.md) - A client compatible with Element Call. As of 2025-03-15, that's just [Element Web](configuring-playbook-client-element-web.md) and the Element X mobile clients (iOS and Android). > [!WARNING] > Because Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) a few experimental features in the Matrix protocol, it's **very likely that it only works with the Synapse homeserver**. +## Decide between Element Call vs just the Matrix RTC stack + +All clients that can currently use Element Call (Element Web and Element X on mobile) already embed the Element Call frontend within them. +These **clients will use their own embedded Element Call frontend**, so **self-hosting the Element Call frontend by the playbook is largely unnecessary**. + +💡 A reason you may wish to continue installing the Element Call frontend (despite Matrix clients not making use of it), is if you need to use it standalone - directly via a browser (without a Matrix client). + +The playbook makes a distiction between enabling Element Call (`matrix_element_call_enabled`) and enabling the Matrix RTC Stack (`matrix_rtc_enabled`). Enabling Element Call automatically enables the Matrix RTC stack. Because installing the Element Call frontend is now unnecessary, **we recommend only installing the Matrix RTC stack, without the Element Call frontend**. + +| Description / Variable | Element Call frontend | [LiveKit Server](configuring-playbook-livekit-server.md) | [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) | +|------------------------|-----------------------|----------------|---------------------| +| Description | Static website that provides the Element Call UI (but often embedded by clients) | Scalable, multi-user conferencing solution based on WebRTC | A helper component that allows Element Call to integrate with LiveKit Server | +| Required for Element Call to function | No | Yes | Yes | +| `matrix_element_call_enabled` | ✅ Installed | ✅ Installed | ✅ Installed | +| `matrix_rtc_enabled` | ❌ Not Installed, but usually unnecessary | ✅ Installed | ✅ Installed | + +All documentation below assumes that you've decided to install Element Call and not just the Matrix RTC stack. + ## Decide on a domain and path -By default, Element Call is configured to be served on the `call.element.example.com` domain. +By default, the Element Call frontend is configured to be served on the `call.element.example.com` domain. If you'd like to run Element Call on another hostname, see the [Adjusting the Element Call URL](#adjusting-the-element-call-url-optional) section below. @@ -48,6 +63,8 @@ In addition to the HTTP/HTTPS ports (which you've already exposed as per the [pr Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml +# Enable the Element Call frontend UI to allow standalone use of Element Call. +# Enabling this also auto-enables the Matrix RTC stack. matrix_element_call_enabled: true ``` diff --git a/docs/configuring-playbook-livekit-jwt-service.md b/docs/configuring-playbook-livekit-jwt-service.md index 55bf3682f..f206c329a 100644 --- a/docs/configuring-playbook-livekit-jwt-service.md +++ b/docs/configuring-playbook-livekit-jwt-service.md @@ -8,9 +8,9 @@ SPDX-License-Identifier: AGPL-3.0-or-later The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service/) for you. -This is a helper component that allows [Element Call](configuring-playbook-element-call.md) to integrate with [LiveKit Server](configuring-playbook-livekit-server.md). +This is a helper component which is part of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) that allows [Element Call](configuring-playbook-element-call.md) to integrate with [LiveKit Server](configuring-playbook-livekit-server.md). -💡 LiveKit JWT Service is automatically installed and configured when [Element Call](configuring-playbook-element-call.md) is enabled, so you don't need to do anything extra. +💡 LiveKit JWT Service is automatically installed and configured when either [Element Call](configuring-playbook-element-call.md) or the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) is enabled, so you don't need to do anything extra. Take a look at: diff --git a/docs/configuring-playbook-livekit-server.md b/docs/configuring-playbook-livekit-server.md index 94282daa0..afc514fc7 100644 --- a/docs/configuring-playbook-livekit-server.md +++ b/docs/configuring-playbook-livekit-server.md @@ -11,7 +11,7 @@ The playbook can install and configure [LiveKit Server](https://github.com/livek LiveKit Server is an open source project that provides scalable, multi-user conferencing based on WebRTC. It's designed to provide everything you need to build real-time video audio data capabilities in your applications. -💡 LiveKit Server is automatically installed and configured when [Element Call](configuring-playbook-element-call.md) is enabled, so you don't need to do anything extra. +💡 LiveKit Server is automatically installed and configured when either [Element Call](configuring-playbook-element-call.md) or the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) is enabled, so you don't need to do anything extra. The [Ansible role for LiveKit Server](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server) is developed and maintained by [the MASH (mother-of-all-self-hosting) project](https://github.com/mother-of-all-self-hosting). For details about configuring LiveKit Server, you can check them via: - 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-livekit-server/blob/main/docs/configuring-livekit-server.md) online diff --git a/docs/configuring-playbook-matrix-rtc.md b/docs/configuring-playbook-matrix-rtc.md new file mode 100644 index 000000000..fae94f497 --- /dev/null +++ b/docs/configuring-playbook-matrix-rtc.md @@ -0,0 +1,59 @@ + + +# Setting up the Matrix RTC stack (optional) + +The playbook can install and configure the Matrix RTC (Real-Time Communication) stack. + +The Matrix RTC stack is a set of supporting components ([LiveKit Server](configuring-playbook-livekit-server.md) and [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md)) that allow the new [Element Call](configuring-playbook-element-call.md) audio/video calls to function. + +💡 If you only plan on doing audio/video calls via Matrix client (which typically embed the Element Call frontend UI within them), you only need to install the Matrix RTC stack and don't necessarily need to install [Element Call](configuring-playbook-element-call.md). See the [Decide between Element Call vs just the Matrix RTC stack](configuring-playbook-element-call.md#decide-between-element-call-vs-just-the-matrix-rtc-stack) section of the [Element Call documentation](configuring-playbook-element-call.md) for more details. + +## Prerequisites + +- A [Synapse](configuring-playbook-synapse.md) homeserver (see the warning below) +- [Federation](configuring-playbook-federation.md) being enabled for your Matrix homeserver (federation is enabled by default, unless you've explicitly disabled it), because [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) currently [requires it](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3562#issuecomment-2725250554) ([relevant source code](https://github.com/element-hq/lk-jwt-service/blob/f5f5374c4bdcc00a4fb13d27c0b28e20e4c62334/main.go#L135-L146)) +- Various experimental features for the Synapse homeserver which Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) (automatically done when Element Call is enabled) +- A [LiveKit Server](configuring-playbook-livekit-server.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack)) +- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when [Element Call or the Matrix RTC stack is enabled](#decide-between-element-call-vs-just-the-matrix-rtc-stack)) +- A client compatible with Element Call. As of 2025-03-15, that's just [Element Web](configuring-playbook-client-element-web.md) and the Element X mobile clients (iOS and Android). + +> [!WARNING] +> Because Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) a few experimental features in the Matrix protocol, it's **very likely that it only works with the Synapse homeserver**. + +## Adjusting the playbook configuration + +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: + +```yaml +# Enable the Matrix RTC stack. +# This provides all supporting services for Element Call, without the Element Call frontend. +matrix_rtc_enabled: true +``` + +## Adjusting firewall rules + +In addition to the HTTP/HTTPS ports (which you've already exposed as per the [prerequisites](prerequisites.md) document), you'll also need to open ports required by [LiveKit Server](configuring-playbook-livekit-server.md) as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section. + +## Installing + +After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records) and [adjusting firewall rules](#adjusting-firewall-rules), run the playbook with [playbook tags](playbook-tags.md) as below: + + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` + +`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +## Usage + +Once installed, Matrix clients which support Element Call (like [Element Web](configuring-playbook-client-element-web.md) and Element X on mobile (iOS and Android)) will automatically use the Matrix RTC stack. + +These clients typically embed the Element Call frontend UI within them, so installing [Element Call](configuring-playbook-element-call.md) is only necessary if you'd like to use it standalone - directly via a browser. \ No newline at end of file diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 3a105cb0c..58cea52b9 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -237,11 +237,13 @@ Services that help you in administrating and monitoring your Matrix installation Various services that don't fit any other categories. -- [Setting up Element Call](configuring-playbook-element-call.md) — a native Matrix video conferencing application (optional) +- [Setting up Element Call](configuring-playbook-element-call.md) — a native Matrix video conferencing application, built on top of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) (optional) -- [Setting up LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (optional) +- [Setting up LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) - a component of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) (optional) -- [Setting up LiveKit Server](configuring-playbook-livekit-server.md) (optional) +- [Setting up LiveKit Server](configuring-playbook-livekit-server.md) - a component of the [Matrix RTC stack](configuring-playbook-matrix-rtc.md) (optional) + +- [Setting up Matrix RTC](configuring-playbook-matrix-rtc.md) (optional) - [Setting up Synapse Auto Invite Accept](configuring-playbook-synapse-auto-accept-invite.md) diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index dff558b85..5dd0d9f5a 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -4609,9 +4609,9 @@ matrix_client_element_enable_presence_by_hs_url: |- matrix_client_element_jitsi_preferred_domain: "{{ matrix_server_fqn_jitsi if jitsi_enabled else '' }}" -matrix_client_element_features_feature_video_rooms: "{{ matrix_element_call_enabled }}" -matrix_client_element_features_feature_group_calls: "{{ matrix_element_call_enabled }}" -matrix_client_element_features_feature_element_call_video_rooms: "{{ matrix_element_call_enabled }}" +matrix_client_element_features_feature_video_rooms: "{{ matrix_rtc_enabled }}" +matrix_client_element_features_feature_group_calls: "{{ matrix_rtc_enabled }}" +matrix_client_element_features_feature_element_call_video_rooms: "{{ matrix_rtc_enabled }}" matrix_client_element_features_feature_oidc_native_flow: "{{ matrix_authentication_service_enabled }}" matrix_client_element_element_call_enabled: "{{ matrix_element_call_enabled }}" @@ -4934,7 +4934,7 @@ matrix_synapse_ext_media_repo_enabled: "{{ matrix_media_repo_enabled }}" matrix_synapse_report_stats: "{{ matrix_synapse_usage_exporter_enabled }}" matrix_synapse_report_stats_endpoint: "{{ (('http://' + matrix_synapse_usage_exporter_identifier + ':' + matrix_synapse_usage_exporter_container_port | string + '/report-usage-stats/push') if matrix_synapse_usage_exporter_enabled else '') }}" -matrix_synapse_experimental_features_msc3266_enabled: "{{ matrix_element_call_enabled }}" +matrix_synapse_experimental_features_msc3266_enabled: "{{ matrix_rtc_enabled }}" matrix_synapse_experimental_features_msc3861_enabled: "{{ matrix_authentication_service_enabled and not matrix_authentication_service_migration_in_progress }}" matrix_synapse_experimental_features_msc3861_issuer: "{{ matrix_authentication_service_http_base_container_url if matrix_authentication_service_enabled else '' }}" @@ -4944,9 +4944,9 @@ matrix_synapse_experimental_features_msc3861_account_management_url: "{{ matrix_ matrix_synapse_experimental_features_msc4108_enabled: "{{ matrix_authentication_service_enabled and not matrix_authentication_service_migration_in_progress }}" -matrix_synapse_experimental_features_msc4140_enabled: "{{ matrix_element_call_enabled }}" +matrix_synapse_experimental_features_msc4140_enabled: "{{ matrix_rtc_enabled }}" -matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_element_call_enabled }}" +matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_rtc_enabled }}" # Disable password authentication when delegating authentication to Matrix Authentication Service. # Unless this is done, Synapse fails on startup with: @@ -6140,7 +6140,7 @@ matrix_static_files_file_matrix_client_property_m_tile_server_map_style_url: "{{ # See: https://github.com/etkecc/synapse-admin/pull/126 matrix_static_files_file_matrix_client_property_cc_etke_synapse_admin_auto: "{{ matrix_synapse_admin_configuration if matrix_homeserver_implementation == 'synapse' else {} }}" -matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_enabled: "{{ matrix_element_call_enabled }}" +matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_enabled: "{{ matrix_livekit_jwt_service_enabled }}" matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_auto: |- {{ ( @@ -6297,7 +6297,7 @@ matrix_element_call_config_livekit_livekit_service_url: "{{ matrix_livekit_jwt_s # # ######################################################################## -livekit_server_enabled: "{{ matrix_element_call_enabled }}" +livekit_server_enabled: "{{ matrix_rtc_enabled }}" livekit_server_identifier: matrix-livekit-server @@ -6405,7 +6405,7 @@ livekit_server_systemd_required_services_list_auto: | # # ######################################################################## -matrix_livekit_jwt_service_enabled: "{{ matrix_element_call_enabled and livekit_server_enabled }}" +matrix_livekit_jwt_service_enabled: "{{ matrix_rtc_enabled and livekit_server_enabled }}" matrix_livekit_jwt_service_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}" diff --git a/roles/custom/matrix-element-call/defaults/main.yml b/roles/custom/matrix-element-call/defaults/main.yml index 66d3cf24a..f5ab28310 100644 --- a/roles/custom/matrix-element-call/defaults/main.yml +++ b/roles/custom/matrix-element-call/defaults/main.yml @@ -11,6 +11,15 @@ matrix_element_call_enabled: false +# Controls whether the Element Call stack (various services around Element Call, without the Element Call frontend itself) are to be installed. +# This affects enablement of other services around Element Call. +# +# By default, we enable the rest of the stack when Element Call itself is enabled, +# but people may wish to enable the stack by itself and avoid installing the Element Call frontend. +# This is useful to do, because self-hosting the Element Call frontend is mostly useless, because +# various clients tend to embed and preferusing their own embedded Element Call frontend, instead of a self-hosted one. +matrix_rtc_enabled: "{{ matrix_element_call_enabled }}" + # renovate: datasource=docker depName=ghcr.io/element-hq/element-call matrix_element_call_version: v0.9.0