diff --git a/CHANGELOG.md b/CHANGELOG.md index efe68fa44..3467e8eb0 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 wish to use it standalone - directly via a browser. + +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). + +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: + +1. Adjusting your `vars.yml` configuration like this: + +```diff +-matrix_element_call_enabled: true ++matrix_element_call_stack_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..a72ed8a71 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 ([LiveKit Server](configuring-playbook-livekit-server.md) and [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md)) for you. 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. @@ -18,21 +18,42 @@ See the project's [documentation](https://github.com/element-hq/element-call) to - 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) +- 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) - 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 + +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. + +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**. + +| 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 | + + ## Decide on a domain and path -By default, Element Call is configured to be served on the `call.element.example.com` domain. +💡 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. @@ -48,11 +69,18 @@ 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 -matrix_element_call_enabled: true +# 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 ``` ### 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/group_vars/matrix_servers b/group_vars/matrix_servers index dff558b85..ac522e586 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_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_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_element_call_stack_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_element_call_stack_enabled }}" -matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_element_call_enabled }}" +matrix_synapse_experimental_features_msc4222_enabled: "{{ matrix_element_call_stack_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_element_call_stack_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_element_call_stack_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..ea36338fe 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_element_call_stack_enabled: "{{ matrix_element_call_enabled }}" + # renovate: datasource=docker depName=ghcr.io/element-hq/element-call matrix_element_call_version: v0.9.0