From edf833627e94eb78e27c596c94ef002d60b8726e Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Thu, 25 Dec 2025 10:01:17 +0200 Subject: [PATCH] Add `matrix_coturn_hostname` to allow for the Coturn domain to be different than `matrix_server_fqn_matrix` --- docs/configuring-playbook-turn.md | 17 +++++++++++++++++ group_vars/matrix_servers | 13 ++++++++++--- roles/custom/matrix-coturn/defaults/main.yml | 5 +++++ .../matrix-coturn/tasks/validate_config.yml | 1 + .../matrix-coturn/templates/turnserver.conf.j2 | 2 +- roles/custom/matrix-coturn/vars/main.yml | 8 ++++---- 6 files changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/configuring-playbook-turn.md b/docs/configuring-playbook-turn.md index 9c9b31271..0cce596e5 100644 --- a/docs/configuring-playbook-turn.md +++ b/docs/configuring-playbook-turn.md @@ -49,6 +49,23 @@ Regardless of the selected authentication method, the playbook generates secrets 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. +### Customize the Coturn hostname (optional) + +By default, Coturn uses the same hostname as your Matrix homeserver (the value of `matrix_server_fqn_matrix`, which is typically `matrix.example.com`). + +If you'd like to use a custom subdomain for Coturn (e.g., `turn.example.com` or `t.matrix.example.com`), add the following configuration to your `vars.yml` file: + +```yaml +matrix_coturn_hostname: turn.example.com +``` + +The playbook will automatically: +- Configure Coturn to use this hostname +- Obtain an SSL certificate for the custom domain via Traefik +- Update all TURN URIs to point to the custom domain + +**Note**: Make sure the custom hostname resolves to your server's IP address via DNS before running the playbook. + ### Use your own external coturn server (optional) 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. diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 740f92709..06ccd0952 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -3152,6 +3152,8 @@ matrix_rageshake_container_labels_traefik_tls_certResolver: "{{ traefik_certReso matrix_coturn_enabled: true +matrix_coturn_hostname: "{{ matrix_server_fqn_matrix }}" + matrix_coturn_docker_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_coturn_docker_image_registry_prefix_upstream_default }}" matrix_coturn_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}" @@ -3191,12 +3193,12 @@ matrix_coturn_container_additional_volumes: | ( [ { - 'src': (traefik_certs_dumper_dumped_certificates_path + '/' + matrix_server_fqn_matrix + '/certificate.crt'), + 'src': (traefik_certs_dumper_dumped_certificates_path + '/' + matrix_coturn_hostname + '/certificate.crt'), 'dst': '/certificate.crt', 'options': 'ro', }, { - 'src': (traefik_certs_dumper_dumped_certificates_path + '/' + matrix_server_fqn_matrix + '/privatekey.key'), + 'src': (traefik_certs_dumper_dumped_certificates_path + '/' + matrix_coturn_hostname + '/privatekey.key'), 'dst': '/privatekey.key', 'options': 'ro', }, @@ -3206,7 +3208,7 @@ matrix_coturn_container_additional_volumes: | matrix_coturn_systemd_required_services_list_auto: | {{ - ([traefik_certs_dumper_identifier + '-wait-for-domain@' + matrix_server_fqn_matrix + '.service'] if matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] and traefik_certs_dumper_enabled and matrix_coturn_tls_enabled else []) + ([traefik_certs_dumper_identifier + '-wait-for-domain@' + matrix_coturn_hostname + '.service'] if matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] and traefik_certs_dumper_enabled and matrix_coturn_tls_enabled else []) }} ###################################################################### @@ -5873,6 +5875,11 @@ traefik_systemd_required_services_list: | ([container_socket_proxy_identifier + '.service'] if container_socket_proxy_enabled else []) }} +traefik_additional_domains_to_obtain_certificates_for_auto: | + {{ + ([matrix_coturn_hostname] if (matrix_coturn_enabled and matrix_coturn_tls_enabled and matrix_coturn_hostname != matrix_server_fqn_matrix) else []) + }} + ######################################################################## # # # /traefik # diff --git a/roles/custom/matrix-coturn/defaults/main.yml b/roles/custom/matrix-coturn/defaults/main.yml index d3616f1b5..be86c6c36 100644 --- a/roles/custom/matrix-coturn/defaults/main.yml +++ b/roles/custom/matrix-coturn/defaults/main.yml @@ -18,6 +18,8 @@ matrix_coturn_enabled: true +matrix_coturn_hostname: '' + matrix_coturn_container_image_self_build: false matrix_coturn_container_image_self_build_repo: "https://github.com/coturn/coturn" matrix_coturn_container_image_self_build_repo_version: "docker/{{ matrix_coturn_version }}" @@ -111,6 +113,9 @@ matrix_coturn_container_turn_range_listen_interface: "{{ '' if matrix_coturn_con matrix_coturn_turn_udp_min_port: 49152 matrix_coturn_turn_udp_max_port: 49172 +# Controls the `realm` configuration option +matrix_coturn_realm: "turn.{{ matrix_coturn_hostname }}" + # Controls which authentication method to enable. # # lt-cred-mech likely provides better compatibility, diff --git a/roles/custom/matrix-coturn/tasks/validate_config.yml b/roles/custom/matrix-coturn/tasks/validate_config.yml index 3fe51d9ea..205ce4c58 100644 --- a/roles/custom/matrix-coturn/tasks/validate_config.yml +++ b/roles/custom/matrix-coturn/tasks/validate_config.yml @@ -29,6 +29,7 @@ You need to define a required configuration setting (`{{ item.name }}`). when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0" with_items: + - {'name': 'matrix_coturn_hostname', when: true} - {'name': 'matrix_coturn_turn_static_auth_secret', when: "{{ matrix_coturn_authentication_method == 'auth-secret' }}"} - {'name': 'matrix_coturn_lt_cred_mech_username', when: "{{ matrix_coturn_authentication_method == 'lt-cred-mech' }}"} - {'name': 'matrix_coturn_lt_cred_mech_password', when: "{{ matrix_coturn_authentication_method == 'lt-cred-mech' }}"} diff --git a/roles/custom/matrix-coturn/templates/turnserver.conf.j2 b/roles/custom/matrix-coturn/templates/turnserver.conf.j2 index a969c4f99..73eb9eff1 100644 --- a/roles/custom/matrix-coturn/templates/turnserver.conf.j2 +++ b/roles/custom/matrix-coturn/templates/turnserver.conf.j2 @@ -11,7 +11,7 @@ lt-cred-mech user={{ matrix_coturn_lt_cred_mech_username }}:{{ matrix_coturn_lt_cred_mech_password }} {% endif %} -realm=turn.{{ matrix_server_fqn_matrix }} +realm={{ matrix_coturn_realm }} min-port={{ matrix_coturn_turn_udp_min_port }} max-port={{ matrix_coturn_turn_udp_max_port }} diff --git a/roles/custom/matrix-coturn/vars/main.yml b/roles/custom/matrix-coturn/vars/main.yml index 4391c2853..91932ec85 100644 --- a/roles/custom/matrix-coturn/vars/main.yml +++ b/roles/custom/matrix-coturn/vars/main.yml @@ -7,15 +7,15 @@ matrix_coturn_turn_uris: |- {{ ([ - 'turns:' + matrix_server_fqn_matrix + '?transport=udp', - 'turns:' + matrix_server_fqn_matrix + '?transport=tcp', + 'turns:' + matrix_coturn_hostname + '?transport=udp', + 'turns:' + matrix_coturn_hostname + '?transport=tcp', ] if matrix_coturn_tls_enabled else []) + ([ - 'turn:' + matrix_server_fqn_matrix + '?transport=udp', + 'turn:' + matrix_coturn_hostname + '?transport=udp', ] if (matrix_coturn_container_stun_plain_host_bind_port_udp != '' or matrix_coturn_container_network == 'host') else []) + ([ - 'turn:' + matrix_server_fqn_matrix + '?transport=tcp', + 'turn:' + matrix_coturn_hostname + '?transport=tcp', ] if (matrix_coturn_container_stun_plain_host_bind_port_tcp != '' or matrix_coturn_container_network == 'host') else []) }}