History

Simon Bärlocher 9a9039c4d3 docs(talk,coturn): add meta/argument_specs.yml * coturn: 31 typed options including the 3 cert modes (acme/file/ selfsigned), the RFC2136 acme.sh sidecar config and challenge alias subschema. coturn_static_auth_secret marked required. * talk: 34 typed options covering the signaling/janus/nats triplet, TURN integration, MCU (janus) tuning, trusted-proxy CIDRs and the extra_hosts pin. talk_backend_secret, talk_turn_secret, talk_session_hashkey and talk_session_blockkey marked required. Both specs load cleanly through ansible-core's ArgumentSpecValidator, have 100% defaults/spec coverage, and match the convention introduced for the other roles in this collection.		2026-05-26 15:35:19 +02:00
..
defaults	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00
handlers	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00
meta	docs(talk,coturn): add meta/argument_specs.yml	2026-05-26 15:35:19 +02:00
tasks	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00
templates	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00
tests	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00
vars	fix(talk,coturn): correct vars file header (was 'httpbin')	2026-05-26 15:35:18 +02:00
README.md	feat(talk/turn/signaling/hpb): add role for Talk with backend services	2026-05-26 15:35:18 +02:00

README.md

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