Do not auto-enable Coturn by default

With everything moving to Matrix RTC and Element X on mobile not supporting legacy calls, most people probably don't need Coturn auto-enabled.
2026-02-28 01:43:10 +00:00 · 2026-02-21 17:10:42 +02:00
parent f1d1c50106
commit 1718181ff4
9 changed files with 61 additions and 53 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,27 @@
 # 2026-02-21

+## (BC Break) coturn is no longer auto-enabled by default
+
+By default, the [coturn](./docs/configuring-playbook-turn.md) TURN server component is no longer enabled for every deployment.
+
+This reduces resources and attach surface for deployments which:
+
+- either don't need calls at all
+- or use the modern [Matrix RTC](docs/configuring-playbook-matrix-rtc.md)/[Element Call](docs/configuring-playbook-element-call.md) stack.
+
+Coturn is still auto-enabled when [Jitsi](./docs/configuring-playbook-jitsi.md) is enabled (`jitsi_enabled: true`), because Jitsi still depends on TURN for legacy Matrix integration.
+
+Additionally, Coturn (when enabled) now defaults to using automatic IP detection of your server's external IP address, instead of assuming your Ansible inventory (`ansible_host`) points to a public address and using it for configuring `coturn_turn_external_ip_address`.
+
+To restore the old behavior (needed for legacy call setups), add the following configuration to your `vars.yml`:
+
+```yml
+coturn_enabled: true
+
+# If you'd like explicit control over the external IP address (like before), keep this too.
+coturn_turn_external_ip_address: "{{ ansible_host }}"
+```
+
 ## LiveKit TURN TLS is now automatically fronted by playbook-managed Traefik

 For deployments that use the playbook-managed Traefik reverse-proxy, LiveKit TURN over TCP is now SSL-terminated at Traefik and passed as plain TCP to LiveKit (`turn.external_tls = true`) by default.
--- a/README.md
+++ b/README.md
@@ -74,7 +74,7 @@ Services that run on the server to make the various parts of your installation w
 | Name | Default? | Description | Documentation |
 | ---- | -------- | ----------- | ------------- |
 | [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) |
-| [coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
+| [coturn](https://github.com/coturn/coturn) | ❌ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) |
 | [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) |
 | [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) |
 | [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) |
--- a/docs/configuring-playbook-jitsi.md
+++ b/docs/configuring-playbook-jitsi.md
@@ -18,6 +18,9 @@ SPDX-License-Identifier: AGPL-3.0-or-later

 The playbook can install and configure the [Jitsi](https://jitsi.org/) video-conferencing platform for you.

+Because Jitsi still requires a TURN server, enabling Jitsi
+automatically enables coturn (`coturn_enabled: true`) unless you explicitly disable it.
+
 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.
--- a/docs/configuring-playbook-turn.md
+++ b/docs/configuring-playbook-turn.md
@@ -13,34 +13,48 @@ SPDX-License-Identifier: AGPL-3.0-or-later

 # Configuring a TURN server (optional, advanced)

-By default, this playbook installs and configures the [coturn](https://github.com/coturn/coturn) as a TURN server, through which clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks. It also configures the Synapse chat server by default, so that it points to the coturn TURN server installed by the playbook. If that's okay, you can skip this document.
+By default, the [coturn](https://github.com/coturn/coturn) TURN server component is enabled automatically only when [Jitsi](configuring-playbook-jitsi.md) is enabled. If you're not using Jitsi, coturn is not enabled by default.

-If you'd like to stop the playbook installing the server, see the section [below](#disabling-coturn) to check the configuration for disabling it.
+If you explicitly need coturn while not using Jitsi, enable it with:
+
+```yaml
+coturn_enabled: true
+```
+
+and configure its IP-related settings in the section below.
+
+If you'd like coturn to stay disabled even when Jitsi is enabled, or if you prefer to use an external TURN provider, see [disabling coturn](#disabling-coturn) section below.
+
+When Coturn is not enabled, homeservers (like Synapse) would not point to TURN servers and *legacy* audio/video call functionality may fail. If you're using [Matrix RTC](configuring-playbook-rtc.md) (for [Element Call](configuring-playbook-element-call.md)), you likely don't have a need to enable coturn.
+
+## Adjusting firewall rules
+
+To ensure Coturn functions correctly, the following firewall rules and port forwarding settings are required when coturn is enabled:
+
+- `3478/tcp`: STUN/TURN over TCP
+- `3478/udp`: STUN/TURN over UDP
+- `5349/tcp`: TURN over TCP
+- `5349/udp`: TURN over UDP
+- `49152-49172/udp`: TURN/UDP relay range
+
+💡 Docker configures the server's internal firewall for you. In most cases, you don't need to do anything special on the host itself.

 ## Adjusting the playbook configuration

 ### Define public IP manually (optional)

-In the `hosts` file we explicitly ask for your server's external IP address when defining `ansible_host`, because the same value is used for configuring coturn.
-
-If you'd rather use a local IP for `ansible_host`, add the following configuration to your `vars.yml` file. Make sure to replace `YOUR_PUBLIC_IP` with the pubic IP used by the server.
+If you enable coturn (either via Jitsi or manually), we recommend that you configure the public IP addresses of your server in the `vars.yml` file:

 ```yaml
-coturn_turn_external_ip_address: "YOUR_PUBLIC_IP"
+# You can define multiple IP addresses if your server has multiple external IP addresses
+coturn_turn_external_ip_addresses: ["YOUR_PUBLIC_IP"]
 ```

-If you'd like to rely on external IP address auto-detection (not recommended unless you need it), set an empty value to the variable. The playbook will automatically contact an [echoip](https://github.com/mpolden/echoip)-compatible service (`https://ifconfig.co/json` by default) to determine your server's IP address. This API endpoint is configurable via the `coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable.
+If you'd like to rely on external IP address auto-detection (not recommended unless you need it), avoid configuring this variable. The playbook will automatically contact an [echoip](https://github.com/mpolden/echoip)-compatible service (`https://ifconfig.co/json` by default) to determine your server's IP address. This API endpoint is configurable via the `coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable.

 >[!NOTE]
 > You can self-host the echoip service by using the [Mother-of-All-Self-Hosting (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook. See [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/echoip.md) for the instruction to install it with the playbook. If you are wondering how to use it for your Matrix server, refer to [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/setting-up-services-on-mdad-server.md) for the overview.

-If your server has multiple external IP addresses, the coturn role offers a different variable for specifying them:
-
-```yaml
-# Note: coturn_turn_external_ip_addresses is different than coturn_turn_external_ip_address
-coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']
-```
-
 ### Change the authentication mechanism (optional)

 The playbook uses the [`auth-secret` authentication method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L186-L199) by default, but you may switch to the [`lt-cred-mech` method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L178) which [some report](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3191) to be working better.
@@ -119,14 +133,14 @@ Take a look at:

 ## Disabling coturn

-If, for some reason, you'd like for the playbook to not install coturn (or to uninstall it if it was previously installed), add the following configuration to your `vars.yml` file:
+Coturn is only enabled by default when [Jitsi](configuring-playbook-jitsi.md) is enabled. In most instances, you don't need to explicitly disable it.
+
+To force the playbook to not install Coturn (even when Jitsi is enabled), add the following configuration to your `vars.yml` file:

 ```yaml
 coturn_enabled: false
 ```

-In that case, Synapse would not point to any coturn servers and audio/video call functionality may fail.
-
 ## Installing

 After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -311,10 +311,6 @@ You can disable some not-so-important services to save on memory.
 # Disabling this will prevent email-notifications and other such things from working.
 exim_relay_enabled: false

-# You can also disable this to save more RAM,
-# at the expense of audio/video calls being unreliable.
-coturn_enabled: false
-
 # This makes Synapse not keep track of who is online/offline.
 #
 # Keeping track of this and announcing such online-status in federated rooms with
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@@ -57,12 +57,7 @@ We will be using `example.com` as the domain in the following instruction. Pleas

  - `80/tcp`: HTTP webserver
  - `443/tcp` and `443/udp`: HTTPS webserver
-  - `3478/tcp`: STUN/TURN over TCP (used by [coturn](./configuring-playbook-turn.md))
-  - `3478/udp`: STUN/TURN over UDP (used by [coturn](./configuring-playbook-turn.md))
-  - `5349/tcp`: TURN over TCP (used by [coturn](./configuring-playbook-turn.md))
-  - `5349/udp`: TURN over UDP (used by [coturn](./configuring-playbook-turn.md))
  - `8448/tcp` and `8448/udp`: Matrix Federation API HTTPS webserver. Some components like [Matrix User Verification Service](configuring-playbook-user-verification-service.md#open-matrix-federation-port) require this port to be opened **even with federation disabled**.
-  - the range `49152-49172/udp`: TURN over UDP
  - potentially some other ports, depending on the additional (non-default) services that you enable in the **configuring the playbook** step (later on). Consult each service's documentation page in `docs/` for that.

 ---------------------------------------------
--- a/examples/hosts
+++ b/examples/hosts
@@ -1,6 +1,3 @@
-# We explicitly ask for your server's external IP address, because the same value is used for configuring coturn.
-# If you'd rather use a local IP here, make sure to set up `coturn_turn_external_ip_address`.
-#
 # To connect using a non-root user (and elevate to root with sudo later),
 # replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username ansible_become=true ansible_become_user=root`.
 # If sudo requires a password, either add `ansible_become_password=PASSWORD_HERE` to the host line
@@ -18,4 +15,4 @@
 # to the host line below.

 [matrix_servers]
-matrix.example.com ansible_host=<your-server's external IP address> ansible_ssh_user=root
+matrix.example.com ansible_host=<your-server's domain name or IP address> ansible_ssh_user=root
--- a/examples/vars.yml
+++ b/examples/vars.yml
@@ -52,19 +52,3 @@ devture_systemd_docker_base_ipv6_enabled: true
 # Changing this value subsequently requires manual work.
 # The value used here must be shorter than 100 characters.
 postgres_connection_password: ''
-
-# By default, we configure coturn's external IP address using the value specified for `ansible_host` in your `inventory/hosts` file.
-# If this value is an external IP address, you can skip this section.
-#
-# If `ansible_host` is not the server's external IP address, you have 2 choices:
-# 1. Uncomment the line below, to allow IP address auto-detection to happen (more on this below)
-# 2. Uncomment and adjust the line below to specify an IP address manually
-#
-# By default, auto-detection will be attempted using the `https://ifconfig.co/json` API.
-# Default values for this are specified in `coturn_turn_external_ip_address_auto_detection_*` variables in the coturn role
-# (see `roles/galaxy/coturn/defaults/main.yml`).
-#
-# If your server has multiple IP addresses, you may define them in another variable which allows a list of addresses.
-# Example: `coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']`
-#
-# coturn_turn_external_ip_address: ''
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -3497,7 +3497,9 @@ matrix_rageshake_container_labels_traefik_tls_certResolver: "{{ traefik_certReso
 #
 ######################################################################

-coturn_enabled: true
+# Coturn is enabled by default only when Jitsi is enabled because Jitsi still
+# depends on legacy TURN integration for compatibility.
+coturn_enabled: "{{ jitsi_enabled | bool }}"

 coturn_identifier: matrix-coturn

@@ -3513,11 +3515,6 @@ coturn_container_image_registry_prefix_upstream: "{{ matrix_container_global_reg

 coturn_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}"

-# We make the assumption that `ansible_host` points to an external IP address, which may not always be the case.
-# Users are free to set `coturn_turn_external_ip_address` to an empty string
-# to allow auto-detection (via an echoip service) to happen at runtime.
-coturn_turn_external_ip_address: "{{ ansible_host }}"
-
 # By default, we use the official public instance.
 coturn_turn_external_ip_address_auto_detection_echoip_service_url: https://ifconfig.co/json