Update files for coturn (#3953)

* Update docs/configuring-playbook-turn.md: add a section for description about installing Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-turn.md and a related file - Edit the introducion based on docs/configuring-playbook-client-element-web.md - Adopt the commont format by creating the section "Adjusting the playbook configuration" - Add the section "Extending the configuration" - Move the section "Disabling Coturn" to the bottom Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Fix capitalization: Coturn → coturn See: https://github.com/coturn/coturn. Note that "coturn" is not capitalized even on the start of a sentence, except some rare cases like on the releases page: https://github.com/coturn/coturn/releases Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2025-01-17 17:19:17 +09:00
parent 96dbb98b37
commit 2773c053d0
15 changed files with 111 additions and 90 deletions
--- a/docs/configuring-playbook-turn.md
+++ b/docs/configuring-playbook-turn.md
@ -1,61 +1,53 @@
-# Adjusting TURN server configuration (optional, advanced)
+# Configuring a TURN server (optional, advanced)

-The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server by default, so that clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks.
+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 Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook.
+If you'd like to stop the playbook installing the server, see the section [below](#disabling-coturn) to check the configuration for disabling it.

-## Disabling Coturn
+## Adjusting the playbook configuration

-If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+### Define public IP manually (optional)

-```yaml
-matrix_coturn_enabled: false
-```
+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.

-In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail.
-
-## Manually defining your public IP
-
-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`, make sure to set up `matrix_coturn_turn_external_ip_address` replacing `YOUR_PUBLIC_IP` with the pubic IP used by the server.
+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.

 ```yaml
 matrix_coturn_turn_external_ip_address: "YOUR_PUBLIC_IP"
 ```

-If you'd like to rely on external IP address auto-detection (not recommended unless you need it), set `matrix_coturn_turn_external_ip_address` to an empty value. 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 `matrix_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), 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 `matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable.

-If your server has multiple external IP addresses, the Coturn role offers a different variable for specifying them:
+If your server has multiple external IP addresses, the coturn role offers a different variable for specifying them:

 ```yaml
 # Note: matrix_coturn_turn_external_ip_addresses is different than matrix_coturn_turn_external_ip_address
 matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']
 ```

-## Changing the authentication mechanism
+### 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.

-To do so, add this override to your configuration:
+To do so, add the following configuration to your `vars.yml` file:

 ```yaml
 matrix_coturn_authentication_method: lt-cred-mech
 ```

-Regardless of the selected authentication method, the playbook generates secrets automatically and passes them to the homeserver and Coturn.
+Regardless of the selected authentication method, the playbook generates secrets automatically and passes them to the homeserver and coturn.

-If you're using [Jitsi](./configuring-playbook-jitsi.md), note that switching to `lt-cred-mech` will remove the integration between Jitsi and your own Coturn server, because Jitsi only seems to support the `auth-secret` authentication method.
+If [Jitsi](configuring-playbook-jitsi.md) is installed, note that switching to `lt-cred-mech` will disable the integration between Jitsi and your coturn server, as Jitsi seems to support the `auth-secret` authentication method only.

-## Using your own external Coturn server
+### Use your own external coturn server (optional)

-If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:
+If you'd like to use another TURN server (be it coturn or some other one), add the following configuration to your `vars.yml` file. Make sure to replace `HOSTNAME_OR_IP` with your own.

 ```yaml
-# Disable integrated Coturn server
+# Disable integrated coturn server
 matrix_coturn_enabled: false

-# Point Synapse to your other Coturn server
+# Point Synapse to your other coturn server
 matrix_synapse_turn_uris:
 - turns:HOSTNAME_OR_IP?transport=udp
 - turns:HOSTNAME_OR_IP?transport=tcp
@ -63,13 +55,42 @@ matrix_synapse_turn_uris:
 - turn:HOSTNAME_OR_IP?transport=tcp
 ```

-If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too. If you do not do it, Jitsi will fall back to an upstream service.
+If you have or want to enable Jitsi, you might want to enable the TURN server there too. If you do not do it, Jitsi will fall back to an upstream service.

 ```yaml
 jitsi_web_stun_servers:
 - stun:HOSTNAME_OR_IP:PORT
 ```
-You can put multiple host/port combinations if you like.

-## Further variables and configuration options
-To see all the available configuration options, check roles/custom/matrix-coturn/defaults/main.yml
+You can put multiple host/port combinations if you'd like to.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the TURN server.
+
+Take a look at:
+
+- `roles/custom/matrix-coturn/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## 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:
+
+```yaml
+matrix_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:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```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.
--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@ -40,7 +40,7 @@ For a more custom setup, see the [Other configuration options](#other-configurat
 - Server components:
  - [Using an external PostgreSQL server](configuring-playbook-external-postgres.md)

-  - [Adjusting TURN server configuration](configuring-playbook-turn.md) (advanced)
+  - [Configuring a TURN server](configuring-playbook-turn.md) (advanced)

  - [Configuring the Traefik reverse-proxy](configuring-playbook-traefik.md) (advanced)

--- a/docs/container-images.md
+++ b/docs/container-images.md
@ -30,7 +30,7 @@ Services that run on the server to make the various parts of your installation w
 | Service | Container image | Default? | Description |
 | ------- | --------------- | -------- | ----------- |
 | [PostgreSQL](configuring-playbook-external-postgres.md) | [postgres](https://hub.docker.com/_/postgres/) | ✅ | Database for Synapse. [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) is also possible. |
-| [Coturn](configuring-playbook-turn.md) | [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) | ✅ | STUN/TURN server for WebRTC audio/video calls |
+| [coturn](configuring-playbook-turn.md) | [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) | ✅ | STUN/TURN server for WebRTC audio/video calls |
 | [Traefik](configuring-playbook-traefik.md) | [Traefik](https://hub.docker.com/_/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](configuring-playbook-own-webserver.md) |
 | [Let's Encrypt](configuring-playbook-ssl-certificates.md) | [certbot/certbot](https://hub.docker.com/r/certbot/certbot/) | ✅ | The [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) |
 | [Exim](configuring-playbook-email.md) | [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) |
--- a/docs/howto-srv-server-delegation.md
+++ b/docs/howto-srv-server-delegation.md
@ -83,17 +83,17 @@ traefik_environment_variables_additional_variables: |
 traefik_certResolver_primary: dns
 ```

-## Adjust Coturn's configuration
+## Adjust coturn's configuration

-The last step is to alter the generated Coturn configuration.
+The last step is to alter the generated coturn configuration.

-By default, Coturn is configured to wait on the certificate for the `matrix.` subdomain using an [instantiated systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates) using the domain name as the parameter for this service. However, we need to serve the wildcard certificate, which is incompatible with systemd, it will try to expand the `*`, which will break and prevent Coturn from starting.
+By default, coturn is configured to wait on the certificate for the `matrix.` subdomain using an [instantiated systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates) using the domain name as the parameter for this service. However, we need to serve the wildcard certificate, which is incompatible with systemd, it will try to expand the `*`, which will break and prevent coturn from starting.

-We also need to indicate to Coturn where the wildcard certificate is.
+We also need to indicate to coturn where the wildcard certificate is.

-⚠️ **Warning** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).
+⚠️ **Warning** : On first start of the services, coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the coturn service (`just start-group coturn`).

-This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically.
+This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the coturn service is setup to restart periodically.

 ```yaml
 # Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
@ -159,7 +159,7 @@ traefik_environment_variables_additional_variables: |
  CF_DNS_API_TOKEN=redacted
  LEGO_DISABLE_CNAME_SUPPORT=true

-# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart Coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
+# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
 matrix_coturn_systemd_required_services_list: ['docker.service']

 # This changes the path of the loaded certificate, while maintaining the original functionality, we're now loading the wildcard certificate.
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@ -48,10 +48,10 @@ 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`: TURN over TCP (used by Coturn)
-  - `3478/udp`: TURN over UDP (used by Coturn)
-  - `5349/tcp`: TURN over TCP (used by Coturn)
-  - `5349/udp`: TURN over UDP (used by Coturn)
+  - `3478/tcp`: TURN over TCP (used by coturn)
+  - `3478/udp`: TURN over UDP (used by coturn)
+  - `5349/tcp`: TURN over TCP (used by coturn)
+  - `5349/udp`: TURN over UDP (used by coturn)
  - `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.