# coturn

Deploys a [coturn](https://github.com/coturn/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:

```yaml
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