---
argument_specs:
  main:
    short_description: Deploy the Nextcloud Talk High Performance Backend (HPB) stack.
    description:
      - Renders a Docker Compose stack with C(nextcloud-spreed-signaling)
        (Strukturag), C(janus-gateway) (canyan build) and C(nats) (internal
        message broker) behind Traefik.
      - Designed to be paired with the C(digitalboard.core.coturn) role
        (TURN/STUN) and registered in Nextcloud via
        C(digitalboard.core.nextcloud)'s C(talk.yml) task.
    options:
      docker_compose_base_dir:
        type: path
        default: /etc/docker/compose
      docker_volume_base_dir:
        type: path
        default: /srv/data
      talk_service_name:
        type: str
        default: signaling
      talk_docker_compose_dir:
        type: path
      talk_docker_volume_dir:
        type: path

      talk_signaling_image:
        type: str
        default: "strukturag/nextcloud-spreed-signaling:1.3.4"
      talk_janus_image:
        type: str
        default: "canyan/janus-gateway:1.2.4"
      talk_nats_image:
        type: str
        default: "nats:2.10-alpine"

      talk_traefik_network:
        type: str
        default: proxy
      talk_internal_network:
        type: str
        default: hpb_internal

      talk_use_ssl:
        type: bool
        default: true
      talk_cert_resolver:
        type: str
        default: dns
      talk_domain:
        type: str
        default: signaling.example.test
        description: Public domain (typically routed through the DMZ Traefik).
      talk_internal_domain:
        type: str
        default: ''
        description:
          - Optional split-horizon C(*.int.*) domain for server-to-server
            traffic (e.g. C(signaling.int.example.test)).

      talk_nextcloud_url:
        type: str
        default: https://cloud.example.test
        description: Nextcloud base URL the HPB talks back to. Must be reachable from the HPB container.
      talk_nextcloud_extra_host_ip:
        type: str
        default: ''
        description:
          - Pin the Nextcloud hostname to a backend IP via C(extra_hosts) to bypass
            DMZ hairpin / SNI issues. Empty disables the pin.

      talk_backend_secret:
        type: str
        required: true
        description:
          - HMAC secret shared with Nextcloud Talk. Default lookup reads
            C(playbooks/secrets/<host>/talk_backend_secret).

      talk_turn_secret:
        type: str
        required: true
        description:
          - Shared secret with coturn (must match C(coturn_static_auth_secret)
            on the TURN host). Default lookup reads
            C(playbooks/secrets/<host>/talk_turn_secret).
      talk_turn_servers:
        type: str
        default: "turns:stun.example.test:5349?transport=tcp,turn:stun.example.test:3478"
        description:
          - TURN server URI list as understood by the signaling server.
            Override to C(:443) when coturn binds on 443 in restrictive networks.
      talk_turn_realm:
        type: str
        default: stun.example.test
      talk_turn_apikey:
        type: str
        default: ''
        description: Optional explicit API key; when empty a random one is generated on first run.

      talk_session_hashkey:
        type: str
        required: true
        description:
          - 32-byte hex string. Default lookup reads
            C(playbooks/secrets/<host>/talk_session_hashkey).
      talk_session_blockkey:
        type: str
        required: true
        description:
          - 32-byte hex string. Default lookup reads
            C(playbooks/secrets/<host>/talk_session_blockkey).

      talk_mcu_type:
        type: str
        choices: [janus]
        default: janus
      talk_janus_public_ip:
        type: str
        default: ''
        description: Must be set in host_vars. Goes into janus C(nat_1_1_mapping).
      talk_janus_rtp_port_min:
        type: int
        default: 20000
      talk_janus_rtp_port_max:
        type: int
        default: 21000
      talk_janus_stun_server:
        type: str
        default: stun.int.example.test
        description: STUN server janus uses for its own ICE candidate gathering.
      talk_janus_stun_port:
        type: int
        default: 5349
      talk_janus_ice_lite:
        type: bool
        default: true
      talk_janus_ice_tcp:
        type: bool
        default: true

      talk_trusted_proxies:
        type: list
        elements: str
        default:
          - "172.16.0.0/12"
          - "192.168.0.0/16"
          - "10.0.0.0/8"
      talk_allowed_hosts:
        type: list
        elements: str
        default:
          - "172.16.0.0/12"

      talk_extra_hosts:
        type: list
        elements: str
        default: []
        description:
          - Extra C(host:ip) entries forwarded to all three containers.
            Pre-populated with the Nextcloud pin when
            C(talk_nextcloud_extra_host_ip) is set.