diff --git a/docs/configuring-playbook-element-call.md b/docs/configuring-playbook-element-call.md index 694d9225b..dcdeec301 100644 --- a/docs/configuring-playbook-element-call.md +++ b/docs/configuring-playbook-element-call.md @@ -9,32 +9,37 @@ SPDX-License-Identifier: AGPL-3.0-or-later The playbook can install and configure [Element Call](https://github.com/element-hq/element-call) 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](configuring-playbook-livekit-server.md) as its backend. +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. See the project's [documentation](https://github.com/element-hq/element-call) to learn more. +## Prerequisites + +- A [Synapse](configuring-playbook-synapse.md) homeserver (see the warning below) +- 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) + > [!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. +> 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 on a domain and path By default, Element Call is configured to be served on the `call.element.DOMAIN` domain. -If you'd like to run Element Call on another hostname or path, use the `matrix_element_call_hostname` variable. A `matrix_element_call_path_prefix` variable is also available to set a path prefix for the Element Call service, but Element Call does not support running under a sub-path yet. +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 -If you've changed the default hostname, **you may need to adjust your DNS** records accordingly to point to the correct server. +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`. -Ensure that the following DNS names have a public IP/FQDN: -- `call.element.example.com` -- `livekit.example.com` +When setting these values, replace `example.com` with your own. + +All dependency services for Element Call ([LiveKit Server](configuring-playbook-livekit-server.md) and [Livekit JWT Service](configuring-playbook-livekit-jwt-service.md)) are installed and configured automatically by the playbook. By default, these services are installed on a subpath on the `matrix.` domain, so no DNS record adjustments are required for them. ## Adjusting firewall rules -All services are exposed via HTTP/HTTPS as per usual, ports for which you've already opened as described in the [prerequisites](prerequisites.md) document. - -In addition to that, you'll also need to open ports required by LiveKit Server as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section. +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 as described in its own [Adjusting firewall rules](configuring-playbook-livekit-server.md#adjusting-firewall-rules) section. ## Adjusting the playbook configuration @@ -44,11 +49,18 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars. matrix_element_call_enabled: true ``` -💡 Enabling Element Call will automatically: +### Adjusting the Element Call URL (optional) -- enable the [LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) and [Livekit Server](configuring-playbook-livekit-server.md) services +By tweaking the `matrix_element_call_hostname` variable, you can easily make the service available at a **different hostname** than the default one. -- enable a few experimental features in Synapse that Element Call [requires](https://github.com/element-hq/element-call/blob/93ae2aed9841e0b066d515c56bd4c122d2b591b2/docs/self-hosting.md#a-matrix-homeserver) +Example additional configuration for your `vars.yml` file: + +```yaml +matrix_element_call_hostname: "element-call.example.com" +``` + +> [!WARNING] +> A `matrix_element_call_path_prefix` variable is also available and mean to let you configure a path prefix for the Element Call service, but [Element Call does not support running under a sub-path yet](https://github.com/element-hq/element-call/issues/3084). ## Installing @@ -56,4 +68,4 @@ After configuring the playbook and potentially [adjusting your DNS records](#adj ## Usage -Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md). \ No newline at end of file +Once installed, Element Call integrates seamlessly with Matrix clients like [Element Web](configuring-playbook-client-element-web.md) and Element X on mobile (iOS and Android). diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 59fd6b6c4..3a494d083 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -20,6 +20,8 @@ The playbook can install and configure the [Jitsi](https://jitsi.org/) video-con Jitsi is an open source video-conferencing platform. It can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app. +💡 If you're into experimental technology, you may also be interested in trying out [Element Call](configuring-playbook-element-call.md) - a native Matrix video conferencing application. + The [Ansible role for Jitsi](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi) 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 Jitsi, you can check them via: - 🌐 [the role's documentation at the MASH project](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/docs/configuring-jitsi.md) online - 📁 `roles/galaxy/jitsi/docs/configuring-jitsi.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles) diff --git a/docs/configuring-playbook-livekit-jwt-service.md b/docs/configuring-playbook-livekit-jwt-service.md new file mode 100644 index 000000000..55bf3682f --- /dev/null +++ b/docs/configuring-playbook-livekit-jwt-service.md @@ -0,0 +1,18 @@ + + +# Setting up LiveKit JWT Service (optional) + +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). + +💡 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. + +Take a look at: + +- `roles/custom/matrix-livekit-jwt-service/defaults/main.yml` for some variables that you can customize via your `vars.yml` file +- `roles/custom/matrix-livekit-jwt-service/templates/env.j2` for the component's default configuration. \ No newline at end of file diff --git a/docs/configuring-playbook-livekit-server.md b/docs/configuring-playbook-livekit-server.md index 8c1722507..948d24d36 100644 --- a/docs/configuring-playbook-livekit-server.md +++ b/docs/configuring-playbook-livekit-server.md @@ -1,6 +1,6 @@ @@ -11,52 +11,18 @@ The playbook can install and configure [LiveKit](https://github.com/livekit/live 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. +💡 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. -## 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: -- `livekit.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' -``` +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 +- 📁 `roles/galaxy/livekit-server/docs/configuring-livekit-server.md` locally, if you have [fetched the Ansible roles](installing.md#update-ansible-roles) ## Adjusting firewall rules -To ensure the services function correctly, the following firewall rules and port forwarding settings are required: +To ensure LiveKit Server functions correctly, the following firewall rules and port forwarding settings are required: -- `7881/tcp`: ICE/TCP (used by [LiveKit Server](./docs/configuring-playbook-livekit-server.md) for [Element Call](./docs/configuring-playbook-element-call.md)) +- `7881/tcp`: ICE/TCP -- `7882/udp`: ICE/UDP Mux (used by [LiveKit Server](./docs/configuring-playbook-livekit-server.md) for [Element Call](./docs/configuring-playbook-element-call.md)) +- `7882/udp`: ICE/UDP Mux 💡 The suggestions above are inspired by the upstream [Ports and Firewall](https://docs.livekit.io/home/self-hosting/ports-firewall/) documentation based on how LiveKit is configured in the playbook. If you've using custom configuration for the LiveKit Server role, you may need to adjust the firewall rules accordingly. - -## 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. - -## Additional Information - -Refer to the Livekit documentation for more details on configuring and using Livekit. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 3e8fb8861..73b8ad5cf 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -237,11 +237,11 @@ 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 Element Call](configuring-playbook-element-call.md) - a native Matrix video conferencing application (optional) -- [Setting up the LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (optional) +- [Setting up LiveKit JWT Service](configuring-playbook-livekit-jwt-service.md) (optional) -- [Setting up the Livekit server](configuring-playbook-livekit-server.md) (optional) +- [Setting up LiveKit Server](configuring-playbook-livekit-server.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 564a4ef74..6c00e4de5 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -6299,7 +6299,8 @@ livekit_server_gid: "{{ matrix_user_gid }}" livekit_server_base_path: "{{ matrix_base_data_path }}/livekit-server" -livekit_server_hostname: "livekit.{{ matrix_domain }}" +livekit_server_hostname: "{{ matrix_server_fqn_matrix }}" +livekit_server_path_prefix: "/livekit-server" livekit_server_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}" diff --git a/roles/custom/matrix-livekit-server/templates/labels.j2 b/roles/custom/matrix-livekit-server/templates/labels.j2 index a51a1c041..8c3a04b5b 100644 --- a/roles/custom/matrix-livekit-server/templates/labels.j2 +++ b/roles/custom/matrix-livekit-server/templates/labels.j2 @@ -1,6 +1,6 @@ {# SPDX-FileCopyrightText: 2024 wjbeckett -SPDX-FileCopyrightText: 2024 Slavi Pantaleev +SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev SPDX-License-Identifier: AGPL-3.0-or-later #}