matrix-docker-ansible-deploy/roles/custom/matrix-tuwunel/defaults/main.yml

# SPDX-FileCopyrightText: 2025 - 2026 MDAD project contributors
# SPDX-FileCopyrightText: 2025 - 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later

---
# Tuwunel is a Matrix homeserver, the official successor to conduwuit.
# Project source code URL: https://github.com/matrix-construct/tuwunel
# See: https://matrix-construct.github.io/tuwunel/

matrix_tuwunel_enabled: true

matrix_tuwunel_hostname: ''

# renovate: datasource=docker depName=ghcr.io/matrix-construct/tuwunel
matrix_tuwunel_version: v1.8.1

matrix_tuwunel_container_image: "{{ matrix_tuwunel_container_image_registry_prefix }}matrix-construct/tuwunel:{{ matrix_tuwunel_container_image_tag }}"
matrix_tuwunel_container_image_tag: "{{ matrix_tuwunel_version }}"
matrix_tuwunel_container_image_registry_prefix: "{{ matrix_tuwunel_container_image_registry_prefix_upstream }}"
matrix_tuwunel_container_image_registry_prefix_upstream: "{{ matrix_tuwunel_container_image_registry_prefix_upstream_default }}"
matrix_tuwunel_container_image_registry_prefix_upstream_default: ghcr.io/

matrix_tuwunel_base_path: "{{ matrix_base_data_path }}/tuwunel"
matrix_tuwunel_config_path: "{{ matrix_tuwunel_base_path }}/config"
matrix_tuwunel_data_path: "{{ matrix_tuwunel_base_path }}/data"

matrix_tuwunel_config_port_number: 6167

matrix_tuwunel_tmp_directory_size_mb: 500

# List of systemd services that matrix-tuwunel.service depends on
matrix_tuwunel_systemd_required_services_list: "{{ matrix_tuwunel_systemd_required_services_list_default + matrix_tuwunel_systemd_required_services_list_auto + matrix_tuwunel_systemd_required_services_list_custom }}"
matrix_tuwunel_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
matrix_tuwunel_systemd_required_services_list_auto: []
matrix_tuwunel_systemd_required_services_list_custom: []

# List of systemd services that matrix-tuwunel.service wants
matrix_tuwunel_systemd_wanted_services_list: "{{ matrix_tuwunel_systemd_wanted_services_list_default + matrix_tuwunel_systemd_wanted_services_list_auto + matrix_tuwunel_systemd_wanted_services_list_custom }}"
matrix_tuwunel_systemd_wanted_services_list_default: []
matrix_tuwunel_systemd_wanted_services_list_auto: []
matrix_tuwunel_systemd_wanted_services_list_custom: []

# Controls how long to sleep for after starting the matrix-tuwunel container,
# so that subsequent services that depend on it can start after the homeserver
# is fully up.
#
# Set to 0 to remove the delay.
matrix_tuwunel_systemd_service_post_start_delay_seconds: 3

# The base container network. It will be auto-created by this role if it doesn't exist already.
matrix_tuwunel_container_network: ""

# A list of additional container networks that the container would be connected to.
# The role does not create these networks, so make sure they already exist.
# Use this to expose this container to another reverse proxy, which runs in a different container network.
matrix_tuwunel_container_additional_networks: "{{ matrix_tuwunel_container_additional_networks_auto + matrix_tuwunel_container_additional_networks_custom }}"
matrix_tuwunel_container_additional_networks_auto: []
matrix_tuwunel_container_additional_networks_custom: []

# matrix_tuwunel_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
# See `../templates/labels.j2` for details.
#
# To inject your own other container labels, see `matrix_tuwunel_container_labels_additional_labels`.
matrix_tuwunel_container_labels_traefik_enabled: true
matrix_tuwunel_container_labels_traefik_docker_network: "{{ matrix_tuwunel_container_network }}"
matrix_tuwunel_container_labels_traefik_entrypoints: web-secure
matrix_tuwunel_container_labels_traefik_tls_certResolver: default  # noqa var-naming

# Controls whether labels will be added for handling the root (/) path on a public Traefik entrypoint.
matrix_tuwunel_container_labels_public_client_root_enabled: true
matrix_tuwunel_container_labels_public_client_root_traefik_hostname: "{{ matrix_tuwunel_hostname }}"
matrix_tuwunel_container_labels_public_client_root_traefik_rule: "Host(`{{ matrix_tuwunel_container_labels_public_client_root_traefik_hostname }}`) && Path(`/`)"
matrix_tuwunel_container_labels_public_client_root_traefik_priority: 0
matrix_tuwunel_container_labels_public_client_root_traefik_entrypoints: "{{ matrix_tuwunel_container_labels_traefik_entrypoints }}"
matrix_tuwunel_container_labels_public_client_root_traefik_tls: "{{ matrix_tuwunel_container_labels_public_client_root_traefik_entrypoints != 'web' }}"
matrix_tuwunel_container_labels_public_client_root_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
matrix_tuwunel_container_labels_public_client_root_redirection_enabled: false
matrix_tuwunel_container_labels_public_client_root_redirection_url: ""

# Controls whether labels will be added that expose the Client-Server API on a public Traefik entrypoint.
matrix_tuwunel_container_labels_public_client_api_enabled: true
matrix_tuwunel_container_labels_public_client_api_traefik_hostname: "{{ matrix_tuwunel_hostname }}"
matrix_tuwunel_container_labels_public_client_api_traefik_path_prefix: /_matrix
matrix_tuwunel_container_labels_public_client_api_traefik_rule: "Host(`{{ matrix_tuwunel_container_labels_public_client_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_tuwunel_container_labels_public_client_api_traefik_path_prefix }}`)"
matrix_tuwunel_container_labels_public_client_api_traefik_priority: 0
matrix_tuwunel_container_labels_public_client_api_traefik_entrypoints: "{{ matrix_tuwunel_container_labels_traefik_entrypoints }}"
matrix_tuwunel_container_labels_public_client_api_traefik_tls: "{{ matrix_tuwunel_container_labels_public_client_api_traefik_entrypoints != 'web' }}"
matrix_tuwunel_container_labels_public_client_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming

# Controls whether labels will be added that expose the Client-Server API on the internal Traefik entrypoint.
matrix_tuwunel_container_labels_internal_client_api_enabled: false
matrix_tuwunel_container_labels_internal_client_api_traefik_path_prefix: "{{ matrix_tuwunel_container_labels_public_client_api_traefik_path_prefix }}"
matrix_tuwunel_container_labels_internal_client_api_traefik_rule: "PathPrefix(`{{ matrix_tuwunel_container_labels_internal_client_api_traefik_path_prefix }}`)"
matrix_tuwunel_container_labels_internal_client_api_traefik_priority: "{{ matrix_tuwunel_container_labels_public_client_api_traefik_priority }}"
matrix_tuwunel_container_labels_internal_client_api_traefik_entrypoints: ""

# Controls whether labels will be added that expose the Server-Server (Federation) API on a public Traefik entrypoint.
matrix_tuwunel_container_labels_public_federation_api_enabled: "{{ matrix_tuwunel_config_allow_federation }}"
matrix_tuwunel_container_labels_public_federation_api_traefik_hostname: "{{ matrix_tuwunel_hostname }}"
matrix_tuwunel_container_labels_public_federation_api_traefik_path_prefix: /_matrix
matrix_tuwunel_container_labels_public_federation_api_traefik_rule: "Host(`{{ matrix_tuwunel_container_labels_public_federation_api_traefik_hostname }}`) && PathPrefix(`{{ matrix_tuwunel_container_labels_public_federation_api_traefik_path_prefix }}`)"
matrix_tuwunel_container_labels_public_federation_api_traefik_priority: 0
matrix_tuwunel_container_labels_public_federation_api_traefik_entrypoints: ''
# TLS is force-enabled because the spec (https://spec.matrix.org/latest/server-server-api/#tls) requires the federation API use HTTPS.
matrix_tuwunel_container_labels_public_federation_api_traefik_tls: true
matrix_tuwunel_container_labels_public_federation_api_traefik_tls_certResolver: "{{ matrix_tuwunel_container_labels_traefik_tls_certResolver }}"  # noqa var-naming

# Additional Docker container labels (multiline string) appended verbatim to the label file.
# See `../templates/labels.j2`.
matrix_tuwunel_container_labels_additional_labels: ''

# Extra arguments for the Docker container
matrix_tuwunel_container_extra_arguments: []

# Specifies which template files to use when configuring tuwunel.
# To override the rendered config wholesale, copy the template into your inventory and point this at it:
# matrix_tuwunel_template_tuwunel_config: "{{ playbook_dir }}/inventory/host_vars/matrix.example.com/tuwunel.toml.j2"
matrix_tuwunel_template_tuwunel_config: "{{ role_path }}/templates/tuwunel.toml.j2"

# The pretty server name used as a suffix on user/room IDs. Cannot be changed after first start without a database wipe.
matrix_tuwunel_config_server_name: "{{ matrix_domain }}"

# Max size for uploads, in bytes
matrix_tuwunel_config_max_request_size: 20000000

# Enables open registration. If false, no users can register on this server.
matrix_tuwunel_config_allow_registration: false

# When registration is enabled, set a strong token to protect the endpoint from abuse.
# Generate one with e.g. `pwgen -s 64 1`. If left empty AND `allow_registration` is true,
# you must explicitly opt in via the open-registration acknowledgement variable below.
matrix_tuwunel_config_registration_token: ''

# Acknowledgement required to allow registration with no token.
# Maps to tuwunel's `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`.
matrix_tuwunel_config_yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse: false

# Suffix appended to new-user displaynames upon registration. Empty disables it.
# Upstream defaults to a flag glyph; we keep MDAD homeserver behavior consistent and leave this empty.
matrix_tuwunel_config_new_user_displayname_suffix: ""

# Emergency password to grant access to the admin user when locked out. Empty disables.
matrix_tuwunel_config_emergency_password: ''

# Trusted notary servers used for key verification.
matrix_tuwunel_config_trusted_servers:
  - "matrix.org"

# Logging directives in `tracing-subscriber` env-filter syntax.
matrix_tuwunel_config_log: "info,state_res=warn"

# TURN integration
matrix_tuwunel_config_turn_uris: []
matrix_tuwunel_config_turn_secret: ''
matrix_tuwunel_config_turn_username: ''
matrix_tuwunel_config_turn_password: ''

# Self-check toggles
matrix_tuwunel_self_check_validate_certificates: true

# Encryption / room creation policy
matrix_tuwunel_config_allow_encryption: true
matrix_tuwunel_config_allow_room_creation: true

# Default room version newly created rooms will use.
matrix_tuwunel_config_default_room_version: '12'

# Rooms newly registered users will be auto-joined to.
# Must be rooms this server has joined at least once and that are public.
matrix_tuwunel_config_auto_join_rooms: []

# (De)federation toggles
matrix_tuwunel_config_allow_federation: true
matrix_tuwunel_config_allowed_remote_server_names: []
matrix_tuwunel_config_forbidden_remote_server_names: []
matrix_tuwunel_config_forbidden_remote_room_directory_server_names: []
matrix_tuwunel_config_prevent_media_downloads_from: []

# List of IPv4/IPv6 CIDR ranges tuwunel refuses to send outbound requests to (SSRF protection).
# This applies to push gateway delivery, URL previews, and remote media fetches.
# Bridges/appservices use a separate resolver and are not affected.
#
# The default mirrors tuwunel's own upstream default, which denies RFC1918,
# loopback, multicast, and other unroutable/testnet ranges.
#
# To deny additional ranges, append to `matrix_tuwunel_config_ip_range_denylist_custom`.
# To permit a range that the default denies (e.g. if you run a push gateway like a
# localhost Sygnal or a LAN ntfy/UnifiedPush server on a private/loopback address, to
# which push delivery would otherwise be silently blocked), override
# `matrix_tuwunel_config_ip_range_denylist_default` with a trimmed list.
# Set the whole list to `[]` to disable denylisting entirely.
matrix_tuwunel_config_ip_range_denylist: "{{ matrix_tuwunel_config_ip_range_denylist_default + matrix_tuwunel_config_ip_range_denylist_auto + matrix_tuwunel_config_ip_range_denylist_custom }}"
matrix_tuwunel_config_ip_range_denylist_default:
  - '127.0.0.0/8'
  - '10.0.0.0/8'
  - '172.16.0.0/12'
  - '192.168.0.0/16'
  - '100.64.0.0/10'
  - '192.0.0.0/24'
  - '169.254.0.0/16'
  - '192.88.99.0/24'
  - '198.18.0.0/15'
  - '192.0.2.0/24'
  - '198.51.100.0/24'
  - '203.0.113.0/24'
  - '224.0.0.0/4'
  - '::1/128'
  - 'fe80::/10'
  - 'fc00::/7'
  - '2001:db8::/32'
  - 'ff00::/8'
  - 'fec0::/10'
matrix_tuwunel_config_ip_range_denylist_auto: []
matrix_tuwunel_config_ip_range_denylist_custom: []

# MSC4284 policy server enforcement.
# When enabled, rooms with a valid `m.room.policy` state event will have
# outgoing events signed by the configured policy server before federation.
# Refusal aborts the local request; transient network or timeout failures
# fail open with a warn log so a policy-server outage does not silently
# take the room offline.
matrix_tuwunel_config_enable_policy_servers: false

# Timeout (in seconds) for outbound `/sign` calls and inbound
# signature-fetches against a room's policy server.
matrix_tuwunel_config_policy_server_request_timeout: 5

# Outgoing presence is heavy on CPU and network and almost no clients use it. Off by default.
matrix_tuwunel_config_allow_outgoing_presence: false

# URL preview gating
matrix_tuwunel_config_url_preview_domain_contains_allowlist: []
matrix_tuwunel_config_url_preview_domain_explicit_allowlist: []
matrix_tuwunel_config_url_preview_check_root_domain: false

# Well-known overrides
# Maps to `[global.well_known] client = "..."` and `server = "host:port"`.
matrix_tuwunel_config_well_known_client: ''
matrix_tuwunel_config_well_known_server: ''
matrix_tuwunel_config_well_known_support_page: ''
matrix_tuwunel_config_well_known_support_email: ''
matrix_tuwunel_config_well_known_support_mxid: ''

# MatrixRTC foci served via /_matrix/client/v1/rtc/transports (MSC4143)
matrix_tuwunel_config_well_known_livekit_url: ''

# RocksDB tuning. Empty values let tuwunel auto-pick.
matrix_tuwunel_config_rocksdb_compression_algo: 'zstd'  # one of: zstd, lz4, bz2, none
matrix_tuwunel_config_rocksdb_compression_level: ''
matrix_tuwunel_config_rocksdb_bottommost_compression_level: ''
matrix_tuwunel_config_rocksdb_direct_io: false
matrix_tuwunel_config_rocksdb_parallelism_threads: 0
matrix_tuwunel_config_rocksdb_max_log_file_size: ''
matrix_tuwunel_config_rocksdb_log_time_to_roll: ''
matrix_tuwunel_config_database_backup_path: ''
matrix_tuwunel_config_database_backups_to_keep: 1

# Cache sizing. Empty values let tuwunel auto-pick (scaled by CPU count).
matrix_tuwunel_config_cache_capacity_modifier: ''
matrix_tuwunel_config_db_cache_capacity_mb: ''
matrix_tuwunel_config_db_write_buffer_capacity_mb: ''

# Admin room
matrix_tuwunel_config_create_admin_room: true
matrix_tuwunel_config_federate_admin_room: false
matrix_tuwunel_config_grant_admin_to_first_user: true

# Sentry crash/error reporting (off by default)
matrix_tuwunel_config_sentry_enabled: false
matrix_tuwunel_config_sentry_endpoint: ''
matrix_tuwunel_config_sentry_send_server_name: false
matrix_tuwunel_config_sentry_traces_sample_rate: 0.15

# Blurhashing for image previews
matrix_tuwunel_config_blurhashing_enabled: true
matrix_tuwunel_config_blurhashing_components_x: 4
matrix_tuwunel_config_blurhashing_components_y: 3
matrix_tuwunel_config_blurhashing_max_raw_size: 33554432

# Native TLS (use only when reverse-proxying is not desired)
matrix_tuwunel_config_tls_certs: ''
matrix_tuwunel_config_tls_key: ''
matrix_tuwunel_config_tls_dual_protocol: false

# LDAP authentication ([global.ldap] in tuwunel.toml).
# See: https://matrix-construct.github.io/tuwunel/authentication/providers.html
matrix_tuwunel_config_ldap_enabled: false
matrix_tuwunel_config_ldap_uri: ''
matrix_tuwunel_config_ldap_base_dn: ''
matrix_tuwunel_config_ldap_bind_dn: ''
matrix_tuwunel_config_ldap_bind_password_file: ''
matrix_tuwunel_config_ldap_filter: '(objectClass=*)'
matrix_tuwunel_config_ldap_uid_attribute: 'uid'
matrix_tuwunel_config_ldap_name_attribute: 'givenName'
matrix_tuwunel_config_ldap_admin_base_dn: ''
matrix_tuwunel_config_ldap_admin_filter: ''

# JWT authentication ([global.jwt] in tuwunel.toml).
matrix_tuwunel_config_jwt_enabled: false
matrix_tuwunel_config_jwt_key: ''
matrix_tuwunel_config_jwt_format: 'HMAC'  # one of: HMAC, B64HMAC, ECDSA, EDDSA
matrix_tuwunel_config_jwt_algorithm: 'HS256'
matrix_tuwunel_config_jwt_register_user: true
matrix_tuwunel_config_jwt_audience: []
matrix_tuwunel_config_jwt_issuer: []
matrix_tuwunel_config_jwt_require_exp: false
matrix_tuwunel_config_jwt_require_nbf: false
matrix_tuwunel_config_jwt_validate_exp: true
matrix_tuwunel_config_jwt_validate_nbf: true

# OAuth2/OIDC identity providers.
#
# Each entry becomes a `[[global.identity_provider]]` block. Only fields you set are emitted;
# tuwunel applies brand-aware defaults for known providers (Google, GitHub, Keycloak, MAS, etc).
#
# Example:
# matrix_tuwunel_config_identity_providers:
#   - brand: keycloak
#     client_id: matrix
#     client_secret: '...'
#     issuer_url: https://sso.example.com/realms/matrix
#     callback_url: https://matrix.example.com/_matrix/client/unstable/login/sso/callback/matrix
#     trusted: true
#   - brand: github
#     client_id: '...'
#     client_secret: '...'
#
# See: https://matrix-construct.github.io/tuwunel/authentication/providers.html
matrix_tuwunel_config_identity_providers: []

# Media storage providers.
#
# Each entry maps an ID to a backend. `kind` is `local` or `s3`; remaining keys map directly
# to fields under `[global.storage_provider.<ID>.<kind>]`.
#
# Examples:
# matrix_tuwunel_config_storage_providers:
#   - id: primary
#     kind: local
#     base_path: /var/lib/tuwunel/media
#   - id: archive
#     kind: s3
#     url: s3://my-bucket/media
#     region: us-east-1
#     key: AKIA...
#     secret: '...'
#
# See: https://matrix-construct.github.io/tuwunel/media/storage.html
matrix_tuwunel_config_storage_providers: []

# Additional environment variables to pass to the container, one per line.
# Environment variables override the rendered config file.
#
# Example:
# matrix_tuwunel_environment_variables_extension: |
#   TUWUNEL_REQUEST_TIMEOUT=60
#   TUWUNEL_DNS_CACHE_SIZE=131072
matrix_tuwunel_environment_variables_extension: ''

# matrix_tuwunel_restart_necessary controls whether the service will be restarted (when true)
# or merely started (when false) by the systemd service-manager role when conditional restart
# is enabled. Computed during installation based on whether config / unit / image changed.
matrix_tuwunel_restart_necessary: false