digitalboard.core/roles/coturn

coturn

Deploys a coturn TURN/STUN server with network_mode: host, optionally accompanied by an acme.sh sidecar that obtains and renews a public TLS certificate via RFC2136 (nsupdate) and restarts coturn on renewal.

This is the recommended pairing for digitalboard.core.talk (Nextcloud Talk HPB).

What it does

• Renders /etc/docker/compose/coturn/docker-compose.yml
• (acme mode) Deploys the TSIG key from playbooks/secrets/{{ inventory_hostname }}/nsupdate.key
• (selfsigned mode) Generates an ECC keypair + selfsigned cert in {{ coturn_cert_dir }}
• Starts the stack via community.docker.docker_compose_v2

Required variables

Variable	Description
coturn_realm	Public DNS name used as realm + cert CN (e.g. stun.digitalboard.ch)
coturn_external_ip	Mapping for --external-ip, format PUBLIC[/PRIVATE]
coturn_static_auth_secret	Shared secret for HMAC-based credentials; must match talk_turn_secret on the HPB host

Important variables

Variable	Default	Description
coturn_cert_mode	file	One of acme, file, selfsigned
coturn_listening_port	443	TCP/UDP non-TLS port
coturn_tls_listening_port	443	TLS port (shared with non-TLS via STUN mux)
coturn_min_relay_port / coturn_max_relay_port	49160 / 49200	UDP relay range
coturn_internal_realm	""	Optional second SAN for split-horizon DNS
coturn_image	coturn/coturn:4.6.2-r5-alpine	Pinned by default; override as needed

ACME / nsupdate mode

When coturn_cert_mode: acme is set, also configure:

coturn_acme_email: "admin@digitalboard.ch"
coturn_acme_nsupdate_server: "ns1.digitalboard.ch"
coturn_acme_nsupdate_server_ip: "172.16.9.169"   # optional pin
coturn_acme_nsupdate_zone: "digitalboard._acme.digitalboard.ch"
# optional: override the auto-built challenge alias mapping
coturn_acme_challenge_aliases:
  - name: stun.digitalboard.ch
    alias: stun.digitalboard._acme.digitalboard.ch
  - name: stun.int.digitalboard.ch
    alias: stun.int.digitalboard._acme.digitalboard.ch

Place your TSIG key at playbooks/secrets/{{ inventory_hostname }}/nsupdate.key (mode 0600).

Secrets

Place the static auth secret at:

playbooks/secrets/{{ inventory_hostname }}/coturn_static_auth_secret

Mode 0600. The same value must be deployed to the HPB host as talk_turn_secret.

Firewall

The role does not manage firewall rules. Ensure the host has:

• 443/tcp and 443/udp reachable from the internet
• UDP {{ coturn_min_relay_port }}-{{ coturn_max_relay_port }} reachable from the internet