69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# 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
|