Add Element Call, LiveKit Server and JWT Service integrations for Element Call functionality

docs/configuring-playbook-element-call.md

@@ -0,0 +1,64 @@
+# Setting up Element Call (optional)
+
+The playbook can install and configure [Element Call](https://github.com/vector-im/element-call) for you.
+
+Element Call is a WebRTC-based video and voice calling platform that integrates with Matrix clients such as Element Web. It provides secure, decentralized communication with support for video calls, audio calls, and screen sharing.
+
+See the project's [documentation](https://github.com/vector-im/element-call) to learn more.
+
+## Decide on a domain and path
+
+By default, Element Call is configured to be served on the Matrix domain (`call.DOMAIN`, controlled by the `matrix_element_call_hostname` variable).
+
+This makes it easy to set it up, **without** having to adjust your DNS records manually.
+
+If you'd like to run Element Call on another hostname or path, use the `matrix_element_call_hostname` and `matrix_element_call_path_prefix` variables.
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
+
+Ensure that the following DNS names have a public IP/FQDN:
+- `call.example.com`
+- `sfu.example.com`
+- `sfu-jwt.example.com`
+
+## Adjusting the playbook configuration
+
+NOTE: Enabling Element Call will automatically enable the [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) and Livekit Server services.
+
+
+Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
+
+```yaml
+matrix_element_call_enabled: true
+```
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+
+## Usage
+
+Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md). When the Element Call service is installed, the `/.well-known/matrix/client` file is also updated. A new `org.matrix.msc4143.rtc_foci` section is added to point to your LiveKit JWT service URL (e.g., `https://matrix.example.com/lk-jwt-service`).
+
+Additionally, the `/.well-known/element/element.json` file is created to help Element clients discover the Element Call URL (e.g., `https://call.example.com`).
+
+## Required Firewall and Port Forwarding Rules
+
+To ensure the services function correctly, the following firewall rules and port forwarding settings are required:
+
+LiveKit:
+
+- Forward UDP ports 50100:50120 to the Docker instance running LiveKit.
+- Forward TCP port 7881 to the Docker instance running LiveKit.
+
+Element Call:
+
+- Forward TCP port 443 to the server running Traefik (for Element Call).
+
+Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services.
+
+## Additional Information
+
+Refer to the Element Call documentation for more details on configuring and using Element Call.

docs/configuring-playbook-jwt-service.md

@@ -0,0 +1,40 @@
+# Setting up JWT Service (optional)
+
+The playbook can install and configure [LiveKit JWT Service](https://github.com/element-hq/lk-jwt-service) for you.
+
+LK-JWT-Service is currently used for a single reason: generate JWT tokens with a given identity for a given room, so that users can use them to authenticate against LiveKit SFU.
+
+See the project's [documentation](https://github.com/element-hq/lk-jwt-service/) to learn more.
+
+## Decide on a domain and path
+
+By default, JWT Service is configured to be served:
+
+- on the Matrix domain (`matrix.example.com`), configurable via `matrix_livekit_jwt_service_hostname`
+- under a `/lk-jwt-service` path prefix, configurable via `matrix_livekit_jwt_service_path_prefix`
+
+This makes it easy to set it up, **without** having to adjust your DNS records manually.
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_livekit_jwt_service_enabled: true
+```
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+
+## Usage
+
+Once installed, a new `org.matrix.msc4143.rtc_foci` section is added to the Element Web client to point to your JWT service URL (e.g., `https://matrix.example.com/lk-jwt-service`).
+
+## Additional Information
+
+Refer to the LiveKit JWT-Service documentation for more details on configuring and using JWT Service.

docs/configuring-playbook-livekit-server.md

@@ -0,0 +1,55 @@
+# Setting up LiveKit (optional)
+
+The playbook can install and configure [LiveKit](https://github.com/livekit/livekit) for you.
+
+LiveKit 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.
+
+See the project's [documentation](https://github.com/livekit/livekit) to learn more.
+
+## Decide on a domain and path
+
+By default, LiveKit is configured to be served on the Matrix domain (`sfu.example.com`, controlled by the `livekit_server_hostname` variable).
+
+This makes it easy to set it up, **without** having to adjust your DNS records manually.
+
+If you'd like to run Livekit on another hostname or path, use the `livekit_server_hostname` variable.
+
+## Adjusting DNS records
+
+If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server.
+
+Ensure that the following DNS names have a public IP/FQDN:
+- `sfu.example.com`
+
+## Adjusting the playbook configuration
+
+Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+livekit_server_enabled: true
+
+# Set a secure key for LiveKit authentication
+livekit_server_dev_key: 'your-secure-livekit-key'
+```
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the [installation](installing.md) command: `just install-all` or `just setup-all`
+
+## Usage
+Once installed, and in conjunction with Element Call and JWT Service, Livekit will become the WebRTC backend for all Element client calls.
+
+## Required Firewall and Port Forwarding Rules
+
+To ensure the services function correctly, the following firewall rules and port forwarding settings are required:
+
+LiveKit:
+
+- Forward UDP ports 50100:50200 to the Docker instance running LiveKit.
+- Forward TCP port 7881 to the Docker instance running LiveKit.
+
+Ensure these ports are open and forwarded appropriately to allow traffic to flow correctly between the services.
+
+## Additional Information
+
+Refer to the Livekit documentation for more details on configuring and using Livekit.

docs/configuring-playbook.md

@@ -212,6 +212,12 @@ Services that help you in administrating and monitoring your Matrix installation
 
 Various services that don't fit any other categories.
 
+- [Setting up the Element Call server](configuring-playbook-element-call.md) (optional)
+
+- [Setting up the LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (optional)
+
+- [Setting up the Livekit server](configuring-playbook-livekit-server.md) (optional)
+
 - [Setting up Synapse Auto Invite Accept](configuring-playbook-synapse-auto-accept-invite.md)
 
 - [Setting up synapse-auto-compressor](configuring-playbook-synapse-auto-compressor.md) for compressing the database on Synapse homeservers

group_vars/matrix_servers

@@ -440,6 +440,12 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': 'matrix-pantalaimon.service', 'priority': 4000, 'groups': ['matrix', 'pantalaimon']}] if matrix_pantalaimon_enabled else [])
     +
+    ([{'name': 'matrix-element-call.service', 'priority': 4000, 'groups': ['matrix', 'element-call']}] if matrix_element_call_enabled else [])
+    +
+    ([{'name': 'matrix-livekit-jwt-service.service', 'priority': 3500, 'groups': ['matrix', 'livekit-jwt-service']}] if matrix_livekit_jwt_service_enabled else [])
+    +
+    ([{'name': (livekit_server_identifier + '.service'), 'priority': 3000, 'groups': ['matrix', 'livekit-server']}] if livekit_server_enabled else [])
+    +
     ([{'name': 'matrix-registration.service', 'priority': 4000, 'groups': ['matrix', 'registration', 'matrix-registration']}] if matrix_registration_enabled else [])
     +
     ([{'name': 'matrix-sliding-sync.service', 'priority': 1500, 'groups': ['matrix', 'sliding-sync']}] if matrix_sliding_sync_enabled else [])
@@ -4455,7 +4461,7 @@ keydb_arch: |-
 #
 ######################################################################
 
-valkey_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) }}"
+valkey_enabled: "{{ matrix_synapse_workers_enabled or (matrix_hookshot_enabled and matrix_hookshot_experimental_encryption_enabled) or matrix_element_call_enabled }}"
 
 valkey_identifier: matrix-valkey
 
@@ -4523,6 +4529,14 @@ 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_oidc_native_flow: "{{ matrix_authentication_service_enabled }}"
+
+matrix_client_element_element_call_enabled: "{{ matrix_element_call_enabled }}"
+matrix_client_element_element_call_url: "{{ matrix_element_call_public_url if matrix_element_call_enabled else '' }}"
+
 ######################################################################
 #
 # /matrix-client-element
@@ -5941,8 +5955,18 @@ 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_auto: |-
+  {{
+    (
+      [{'type': 'livekit', 'livekit_service_url': matrix_livekit_jwt_service_public_url}] if matrix_livekit_jwt_service_enabled else []
+    )
+  }}
+
 matrix_static_files_file_matrix_server_property_m_server: "{{ matrix_server_fqn_matrix_federation }}:{{ matrix_federation_public_port }}"
 
+matrix_static_files_file_element_element_json_property_call_widget_url: "{{ matrix_element_call_public_url if matrix_element_call_enabled else '' }}"
+
 matrix_static_files_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
 
 matrix_static_files_self_check_hostname_matrix: "{{ matrix_server_fqn_matrix }}"
@@ -6049,3 +6073,126 @@ traefik_certs_dumper_ssl_dir_path: "{{ traefik_ssl_dir_path if traefik_enabled e
 # /traefik_certs_dumper                                                #
 #                                                                      #
 ########################################################################
+
+
+########################################################################
+#                                                                      #
+# matrix-element-call                                                  #
+#                                                                      #
+########################################################################
+
+matrix_element_call_enabled: false
+
+matrix_element_call_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
+matrix_element_call_version: "latest"  # Default version; can be overridden in host_vars
+
+matrix_element_call_hostname: "call.{{ matrix_domain }}"  # Default hostname; should be overridden in host_vars if different
+matrix_element_call_path_prefix: "/"  # Path prefix for Element Call
+matrix_element_call_base_path: "{{ matrix_base_data_path }}/element-call"  # Base path for storing Element Call-related files
+matrix_element_call_container_image: "ghcr.io/element-hq/element-call:{{ matrix_element_call_version }}"
+matrix_element_call_container_image_name_prefix: ghcr.io/
+matrix_element_call_container_image_registry_prefix: ghcr.io/
+matrix_element_call_container_image_force_pull: true
+
+# Docker network configuration for Element Call
+matrix_element_call_container_network: "{{ matrix_addons_container_network }}"
+matrix_element_call_container_additional_networks: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_element_call_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
+
+# Traefik Configuration for Element Call
+matrix_element_call_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_element_call_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_element_call_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_element_call_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+########################################################################
+#                                                                      #
+# /matrix-element-call                                                 #
+#                                                                      #
+########################################################################
+
+########################################################################
+#                                                                      #
+# livekit-server                                                       #
+#                                                                      #
+########################################################################
+
+livekit_server_enabled: "{{ matrix_element_call_enabled }}"
+
+livekit_server_identifier: matrix-livekit-server
+
+livekit_server_uid: "{{ matrix_user_uid }}"
+livekit_server_gid: "{{ matrix_user_gid }}"
+
+livekit_server_base_path: "{{ matrix_base_data_path }}/livekit-server"
+
+livekit_server_hostname: "sfu.{{ matrix_domain }}"
+
+livekit_server_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
+
+livekit_server_container_network: "{{ matrix_addons_container_network }}"
+livekit_server_container_additional_networks_auto: "{{ [matrix_playbook_reverse_proxyable_services_additional_network] if (livekit_server_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [] }}"
+
+livekit_server_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+livekit_server_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+livekit_server_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+livekit_server_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+livekit_server_config_keys_auto: |-
+  {{
+    {}
+    | combine(
+      {matrix_livekit_jwt_service_environment_variable_livekit_key: matrix_livekit_jwt_service_environment_variable_livekit_secret}
+      if matrix_livekit_jwt_service_enabled else {}
+    )
+  }}
+
+########################################################################
+#                                                                      #
+# /livekit-server                                                      #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# matrix-livekit-jwt-service                                           #
+#                                                                      #
+########################################################################
+
+matrix_livekit_jwt_service_enabled: "{{ matrix_element_call_enabled and livekit_server_enabled }}"
+
+matrix_livekit_jwt_service_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
+matrix_livekit_jwt_service_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_livekit_jwt_service_path_prefix: "/lk-jwt-service"
+
+matrix_livekit_jwt_service_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm64'] }}"
+
+matrix_livekit_jwt_service_container_network: "{{ matrix_addons_container_network }}"
+
+matrix_livekit_jwt_service_container_additional_networks_auto: |
+  {{
+    (
+      ([matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_livekit_jwt_service_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else [])
+      +
+      ([livekit_server_container_network] if livekit_server_enabled and (matrix_livekit_jwt_service_environment_variable_livekit_url == livekit_server_websocket_container_url and livekit_server_container_network != matrix_livekit_jwt_service_container_network) else [])
+    ) | unique
+  }}
+
+matrix_livekit_jwt_service_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_livekit_jwt_service_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_livekit_jwt_service_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_livekit_jwt_service_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+matrix_livekit_jwt_service_environment_variable_livekit_url: "{{ livekit_server_websocket_container_url }}"
+
+matrix_livekit_jwt_service_environment_variable_livekit_key: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'lk.key', rounds=655555) | to_uuid }}"
+
+matrix_livekit_jwt_service_environment_variable_livekit_secret: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'lk.secret', rounds=655555) | to_uuid }}"
+
+########################################################################
+#                                                                      #
+# /matrix-livekit-jwt-service                                          #
+#                                                                      #
+########################################################################