diff --git a/CHANGELOG.md b/CHANGELOG.md index 3467e8eb0..84b1dd658 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,17 +4,17 @@ 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 wish to use it standalone - directly via a browser. +💡 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 all of Element Call vs just the Element Call stack](./docs/configuring-playbook-element-call.md#decide-between-all-of-element-call-vs-just-the-element-call-stack). +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 all of Element Call (via `matrix_element_call_enabled: true`), you can switch to "just the Element Call stack" (all supporting services **without the Element Call frontend**) by: +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_element_call_stack_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`) diff --git a/docs/configuring-playbook-element-call.md b/docs/configuring-playbook-element-call.md index a72ed8a71..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) and its supporting components ([LiveKit Server](configuring-playbook-livekit-server.md) and [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md)) 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,44 +16,38 @@ 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 the Element Call stack is enabled) -- The [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (automatically installed when the Element Call stack 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 all of Element Call vs just the Element Call stack +## 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 wish to use it standalone - directly via a browser. +💡 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 Element Call Stack (`matrix_element_call_stack_enabled`). Because installing the Element Call frontend is now unnecessary, **we recommend only installing the Element Call Stack, without the Element Call frontend**. +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_element_call_stack_enabled` | ❌ Not Installed, but usually unnecessary | ✅ 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 -💡 This section is only relevant if you're installing the Element Call frontend. See [Decide between all of Element Call vs just the Element Call stack](#decide-between-all-of-element-call-vs-just-the-element-call-stack). We recommend **not** installing the frontend. - 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. ## Adjusting DNS records -💡 You only need to set up DNS records if you're installing the Element Call frontend. See [Decide between all of Element Call vs just the Element Call stack](#decide-between-all-of-element-call-vs-just-the-element-call-stack). We recommend **not** installing the frontend. - By default, this playbook installs Element Call on the `call.element.` subdomain (`call.element.example.com`) and requires you to create a `CNAME` record for `call.element`, which targets `matrix.example.com`. When setting these values, replace `example.com` with your own. @@ -69,18 +63,13 @@ 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 supporting services, without enabling the Element Call frontend. -matrix_element_call_stack_enabled: true - -# If you'd like the Element Call frontend installed as well, remove the variable definition above -# and uncomment the variable below. -# matrix_element_call_enabled: true +# 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 ``` ### Adjusting the Element Call URL (optional) -💡 This section is only relevant if you're installing the Element Call frontend. See [Decide between all of Element Call vs just the Element Call stack](#decide-between-all-of-element-call-vs-just-the-element-call-stack). We recommend **not** installing the frontend. - By tweaking the `matrix_element_call_hostname` variable, you can easily make the service available at a **different hostname** than the default one. Example additional configuration for your `vars.yml` file: 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 ac522e586..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_stack_enabled }}" -matrix_client_element_features_feature_group_calls: "{{ matrix_element_call_stack_enabled }}" -matrix_client_element_features_feature_element_call_video_rooms: "{{ matrix_element_call_stack_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_stack_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_stack_enabled }}" +matrix_synapse_experimental_features_msc4140_enabled: "{{ matrix_rtc_enabled }}" -matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_element_call_stack_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: @@ -6297,7 +6297,7 @@ matrix_element_call_config_livekit_livekit_service_url: "{{ matrix_livekit_jwt_s # # ######################################################################## -livekit_server_enabled: "{{ matrix_element_call_stack_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_stack_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 ea36338fe..f5ab28310 100644 --- a/roles/custom/matrix-element-call/defaults/main.yml +++ b/roles/custom/matrix-element-call/defaults/main.yml @@ -18,7 +18,7 @@ matrix_element_call_enabled: false # 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_element_call_stack_enabled: "{{ matrix_element_call_enabled }}" +matrix_rtc_enabled: "{{ matrix_element_call_enabled }}" # renovate: datasource=docker depName=ghcr.io/element-hq/element-call matrix_element_call_version: v0.9.0