---
argument_specs:
  main:
    short_description: Deploy a coturn TURN/STUN server with optional acme.sh sidecar.
    description:
      - "Renders a Docker Compose stack for coturn running in
        C(network_mode: host), with an optional C(acme.sh) sidecar that
        issues + renews a public TLS certificate via RFC2136 / nsupdate
        and restarts coturn on renewal."
      - Designed to be paired with the C(digitalboard.core.talk) role
        (Nextcloud Talk High Performance Backend).
    options:
      docker_compose_base_dir:
        type: path
        default: /etc/docker/compose
      docker_volume_base_dir:
        type: path
        default: /srv/data
      coturn_service_name:
        type: str
        default: coturn
      coturn_docker_compose_dir:
        type: path
      coturn_docker_volume_dir:
        type: path

      coturn_image:
        type: str
        default: "coturn/coturn:4.6.2-r5-alpine"
      coturn_acme_image:
        type: str
        default: "neilpang/acme.sh:3.1.0"

      coturn_realm:
        type: str
        default: stun.example.test
        description: Public DNS name used for the TURN realm and the public certificate.
      coturn_internal_realm:
        type: str
        default: ''
        description:
          - Optional second DNS name issued on the same certificate, used for
            split-horizon internal access (e.g. C(stun.int.example.test)).

      coturn_listening_port:
        type: int
        default: 3478
        description: TURN/STUN port (TCP + UDP). IANA standard is 3478.
      coturn_tls_listening_port:
        type: int
        default: 5349
        description: TURNS port (TCP + UDP). IANA standard is 5349.
      coturn_min_relay_port:
        type: int
        default: 49160
      coturn_max_relay_port:
        type: int
        default: 49200

      coturn_external_ip:
        type: str
        default: ''
        description:
          - coturn C(--external-ip) value. Format C("PUBLIC_IP") or
            C("PUBLIC_IP/PRIVATE_IP"). Must be set in host_vars for production.
      coturn_listening_ip:
        type: str
        default: '0.0.0.0'

      coturn_static_auth_secret:
        type: str
        required: true
        description:
          - Shared secret used by the HPB signaling server to mint short-lived
            TURN credentials. Default lookup reads
            C(playbooks/secrets/<host>/coturn_static_auth_secret).

      coturn_extra_args:
        type: list
        elements: str
        default: []
        description: Additional CLI flags appended verbatim to the container C(command:).

      coturn_cert_mode:
        type: str
        choices: [acme, file, selfsigned]
        default: file
        description:
          - C(acme) runs an acme.sh sidecar that issues + renews via RFC2136
            and restarts coturn. C(file) assumes a certificate already lives
            on the host (you manage it). C(selfsigned) generates one on first
            run (vagrant/dev only).
      coturn_cert_dir:
        type: path
      coturn_cert_file:
        type: str
        default: fullchain.cer
      coturn_key_file:
        type: str
        description: Defaults to C("{{ coturn_realm }}.key").

      coturn_acme_email:
        type: str
        default: admin@example.test
      coturn_acme_directory:
        type: str
        default: https://acme-v02.api.letsencrypt.org/directory
      coturn_acme_keylength:
        type: str
        default: ec-256
        choices: [ec-256, ec-384, '2048', '3072', '4096']
      coturn_acme_dnssleep:
        type: int
        default: 60
      coturn_acme_data_dir:
        type: path

      coturn_acme_nsupdate_server:
        type: str
        default: ''
        description: Authoritative nameserver acme.sh sends C(nsupdate) packets to.
      coturn_acme_nsupdate_server_ip:
        type: str
        default: ''
        description: Optional C(extra_hosts) pin (string IP) for the nsupdate server.
      coturn_acme_nsupdate_zone:
        type: str
        default: ''
        description: Delegated challenge zone (e.g. C(example._acme.example.test)).
      coturn_acme_challenge_aliases:
        type: list
        elements: dict
        default: []
        description:
          - Per-name challenge alias zones (one entry per SAN). When empty,
            built automatically as C({{ realm }}._acme.{{ zone-tail }}).
        options:
          name:
            type: str
            required: true
            description: SAN the challenge is for.
          alias:
            type: str
            required: true
            description: CNAME target where the C(_acme-challenge) TXT lives.
      coturn_acme_nsupdate_key_src:
        type: path
        description: Path of the TSIG key file on the controller, mounted into the acme container.