4
0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2026-05-22 05:48:01 +00:00

matrix-tuwunel: add Tuwunel homeserver role (#5200)

Tuwunel is a Matrix homeserver maintained by the matrix-construct
organisation. See https://matrix-construct.github.io/tuwunel/.

The rendered TOML emits only keys exposed as Ansible variables; the
rest fall back to tuwunel's upstream defaults. Anything not surfaced
can be set via the TUWUNEL_* env extension or by overriding the
template path.

Popular features Tuwunel adds variables for:

- OAuth2/OIDC identity providers (a list of `[[global.identity_provider]]`
  blocks; brand-aware defaults for Google, GitHub, Keycloak, MAS, etc)
- LDAP and JWT authentication
- Media storage providers (native local and S3 with multipart upload)
- RocksDB tuning (compression, direct_io, parallelism, online backups)
- Native TLS dual-protocol mode
- Blurhashing, Sentry crash reporting

Auto-wired from existing playbook globals: well-known client URL,
TURN/coturn, MatrixRTC LiveKit URL, federation.

The `tuwunel-migrate-from-conduwuit` tag performs a binary-swap
migration. Migration from any other Conduit derivative is unsupported
and would corrupt the database.

Signed-off-by: Jason Volk <jason@zemos.net>
This commit is contained in:
Jason Volk
2026-05-06 23:45:29 -07:00
committed by GitHub
parent 5251be8691
commit c111008d25
26 changed files with 1419 additions and 3 deletions

View File

@@ -0,0 +1 @@
{{ matrix_tuwunel_environment_variables_extension }}

View File

@@ -0,0 +1,4 @@
SPDX-FileCopyrightText: 2026 MDAD project contributors
SPDX-FileCopyrightText: 2026 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later

View File

@@ -0,0 +1,141 @@
{#
SPDX-FileCopyrightText: 2026 MDAD project contributors
SPDX-FileCopyrightText: 2026 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
#}
{% if matrix_tuwunel_container_labels_traefik_enabled %}
traefik.enable=true
{% if matrix_tuwunel_container_labels_traefik_docker_network %}
traefik.docker.network={{ matrix_tuwunel_container_labels_traefik_docker_network }}
{% endif %}
traefik.http.services.matrix-tuwunel.loadbalancer.server.port={{ matrix_tuwunel_config_port_number }}
{% if matrix_tuwunel_container_labels_public_client_root_enabled %}
############################################################
# #
# Public Root path (/) #
# #
############################################################
{% set client_root_middlewares = [] %}
{% if matrix_tuwunel_container_labels_public_client_root_redirection_enabled %}
{% set client_root_middlewares = client_root_middlewares + ['matrix-tuwunel-client-root-redirect'] %}
traefik.http.middlewares.matrix-tuwunel-client-root-redirect.redirectregex.regex=(.*)
traefik.http.middlewares.matrix-tuwunel-client-root-redirect.redirectregex.replacement={{ matrix_tuwunel_container_labels_public_client_root_redirection_url }}
{% endif %}
traefik.http.routers.matrix-tuwunel-public-client-root.rule={{ matrix_tuwunel_container_labels_public_client_root_traefik_rule }}
traefik.http.routers.matrix-tuwunel-public-client-root.middlewares={{ client_root_middlewares | join(',') }}
{% if matrix_tuwunel_container_labels_public_client_root_traefik_priority | int > 0 %}
traefik.http.routers.matrix-tuwunel-public-client-root.priority={{ matrix_tuwunel_container_labels_public_client_root_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-tuwunel-public-client-root.service=matrix-tuwunel
traefik.http.routers.matrix-tuwunel-public-client-root.entrypoints={{ matrix_tuwunel_container_labels_public_client_root_traefik_entrypoints }}
traefik.http.routers.matrix-tuwunel-public-client-root.tls={{ matrix_tuwunel_container_labels_public_client_root_traefik_tls | to_json }}
{% if matrix_tuwunel_container_labels_public_client_root_traefik_tls %}
traefik.http.routers.matrix-tuwunel-public-client-root.tls.certResolver={{ matrix_tuwunel_container_labels_public_client_root_traefik_tls_certResolver }}
{% endif %}
############################################################
# #
# /Public Root path (/) #
# #
############################################################
{% endif %}
{% if matrix_tuwunel_container_labels_public_client_api_enabled %}
############################################################
# #
# Public Client-API (/_matrix) #
# #
############################################################
traefik.http.routers.matrix-tuwunel-public-client-api.rule={{ matrix_tuwunel_container_labels_public_client_api_traefik_rule }}
{% if matrix_tuwunel_container_labels_public_client_api_traefik_priority | int > 0 %}
traefik.http.routers.matrix-tuwunel-public-client-api.priority={{ matrix_tuwunel_container_labels_public_client_api_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-tuwunel-public-client-api.service=matrix-tuwunel
traefik.http.routers.matrix-tuwunel-public-client-api.entrypoints={{ matrix_tuwunel_container_labels_public_client_api_traefik_entrypoints }}
traefik.http.routers.matrix-tuwunel-public-client-api.tls={{ matrix_tuwunel_container_labels_public_client_api_traefik_tls | to_json }}
{% if matrix_tuwunel_container_labels_public_client_api_traefik_tls %}
traefik.http.routers.matrix-tuwunel-public-client-api.tls.certResolver={{ matrix_tuwunel_container_labels_public_client_api_traefik_tls_certResolver }}
{% endif %}
############################################################
# #
# /Public Client-API (/_matrix) #
# #
############################################################
{% endif %}
{% if matrix_tuwunel_container_labels_internal_client_api_enabled %}
############################################################
# #
# Internal Client-API (/_matrix) #
# #
############################################################
traefik.http.routers.matrix-tuwunel-internal-client-api.rule={{ matrix_tuwunel_container_labels_internal_client_api_traefik_rule }}
{% if matrix_tuwunel_container_labels_internal_client_api_traefik_priority | int > 0 %}
traefik.http.routers.matrix-tuwunel-internal-client-api.priority={{ matrix_tuwunel_container_labels_internal_client_api_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-tuwunel-internal-client-api.service=matrix-tuwunel
traefik.http.routers.matrix-tuwunel-internal-client-api.entrypoints={{ matrix_tuwunel_container_labels_internal_client_api_traefik_entrypoints }}
############################################################
# #
# /Internal Client-API (/_matrix) #
# #
############################################################
{% endif %}
{% if matrix_tuwunel_container_labels_public_federation_api_enabled %}
############################################################
# #
# Public Federation-API (/_matrix) #
# #
############################################################
traefik.http.routers.matrix-tuwunel-public-federation-api.rule={{ matrix_tuwunel_container_labels_public_federation_api_traefik_rule }}
{% if matrix_tuwunel_container_labels_public_federation_api_traefik_priority | int > 0 %}
traefik.http.routers.matrix-tuwunel-public-federation-api.priority={{ matrix_tuwunel_container_labels_public_federation_api_traefik_priority }}
{% endif %}
traefik.http.routers.matrix-tuwunel-public-federation-api.service=matrix-tuwunel
traefik.http.routers.matrix-tuwunel-public-federation-api.entrypoints={{ matrix_tuwunel_container_labels_public_federation_api_traefik_entrypoints }}
traefik.http.routers.matrix-tuwunel-public-federation-api.tls={{ matrix_tuwunel_container_labels_public_federation_api_traefik_tls | to_json }}
{% if matrix_tuwunel_container_labels_public_federation_api_traefik_tls %}
traefik.http.routers.matrix-tuwunel-public-federation-api.tls.certResolver={{ matrix_tuwunel_container_labels_public_federation_api_traefik_tls_certResolver }}
{% endif %}
############################################################
# #
# /Public Federation-API (/_matrix) #
# #
############################################################
{% endif %}
{% endif %}
{{ matrix_tuwunel_container_labels_additional_labels }}

View File

@@ -0,0 +1,55 @@
#jinja2: lstrip_blocks: True
[Unit]
Description=Tuwunel Matrix homeserver
{% for service in matrix_tuwunel_systemd_required_services_list %}
Requires={{ service }}
After={{ service }}
{% endfor %}
{% for service in matrix_tuwunel_systemd_wanted_services_list %}
Wants={{ service }}
{% endfor %}
[Service]
Type=simple
Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-tuwunel 2>/dev/null || true'
ExecStartPre=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-tuwunel 2>/dev/null || true'
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
--rm \
--name=matrix-tuwunel \
--log-driver=none \
--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
--cap-drop=ALL \
--read-only \
--tmpfs=/tmp:rw,noexec,nosuid,size={{ matrix_tuwunel_tmp_directory_size_mb }}m \
--network={{ matrix_tuwunel_container_network }} \
--env-file={{ matrix_tuwunel_base_path }}/env \
--env TUWUNEL_CONFIG=/etc/tuwunel/tuwunel.toml \
--label-file={{ matrix_tuwunel_base_path }}/labels \
--mount type=bind,src={{ matrix_tuwunel_data_path }},dst=/var/lib/tuwunel \
--mount type=bind,src={{ matrix_tuwunel_config_path }},dst=/etc/tuwunel,ro \
{% for arg in matrix_tuwunel_container_extra_arguments %}
{{ arg }} \
{% endfor %}
{{ matrix_tuwunel_container_image }}
{% for network in matrix_tuwunel_container_additional_networks %}
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-tuwunel
{% endfor %}
ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-tuwunel
{% if matrix_tuwunel_systemd_service_post_start_delay_seconds != 0 %}
ExecStartPost=-{{ matrix_host_command_sleep }} {{ matrix_tuwunel_systemd_service_post_start_delay_seconds }}
{% endif %}
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-tuwunel 2>/dev/null || true'
ExecStop=-{{ devture_systemd_docker_base_host_command_sh }} -c '{{ devture_systemd_docker_base_host_command_docker }} rm matrix-tuwunel 2>/dev/null || true'
ExecReload={{ devture_systemd_docker_base_host_command_docker }} exec matrix-tuwunel /bin/sh -c 'kill -HUP 1'
Restart=always
RestartSec=30
SyslogIdentifier=matrix-tuwunel
[Install]
WantedBy=multi-user.target

View File

@@ -0,0 +1,4 @@
SPDX-FileCopyrightText: 2026 MDAD project contributors
SPDX-FileCopyrightText: 2026 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later

View File

@@ -0,0 +1,238 @@
{#
SPDX-FileCopyrightText: 2026 MDAD project contributors
SPDX-FileCopyrightText: 2026 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later
#}
### Tuwunel configuration rendered by matrix-docker-ansible-deploy.
###
### This file only emits options exposed as Ansible variables. All other knobs
### keep tuwunel's upstream defaults. To override anything not surfaced here,
### use `matrix_tuwunel_environment_variables_extension` (env vars override TOML)
### or replace the template via `matrix_tuwunel_template_tuwunel_config`.
###
### Reference: https://matrix-construct.github.io/tuwunel/configuration.html
[global]
server_name = {{ matrix_tuwunel_config_server_name | to_json }}
address = "0.0.0.0"
port = {{ matrix_tuwunel_config_port_number }}
database_path = "/var/lib/tuwunel"
max_request_size = {{ matrix_tuwunel_config_max_request_size }}
new_user_displayname_suffix = {{ matrix_tuwunel_config_new_user_displayname_suffix | to_json }}
allow_registration = {{ matrix_tuwunel_config_allow_registration | to_json }}
{% if matrix_tuwunel_config_registration_token | length > 0 %}
registration_token = {{ matrix_tuwunel_config_registration_token | to_json }}
{% endif %}
{% if matrix_tuwunel_config_yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse | bool %}
yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = true
{% endif %}
{% if matrix_tuwunel_config_emergency_password | length > 0 %}
emergency_password = {{ matrix_tuwunel_config_emergency_password | to_json }}
{% endif %}
allow_encryption = {{ matrix_tuwunel_config_allow_encryption | to_json }}
allow_room_creation = {{ matrix_tuwunel_config_allow_room_creation | to_json }}
default_room_version = {{ matrix_tuwunel_config_default_room_version | to_json }}
{% if matrix_tuwunel_config_auto_join_rooms | length > 0 %}
auto_join_rooms = {{ matrix_tuwunel_config_auto_join_rooms | to_json }}
{% endif %}
allow_federation = {{ matrix_tuwunel_config_allow_federation | to_json }}
trusted_servers = {{ matrix_tuwunel_config_trusted_servers | to_json }}
{% if matrix_tuwunel_config_allowed_remote_server_names | length > 0 %}
allowed_remote_server_names_experimental = {{ matrix_tuwunel_config_allowed_remote_server_names | to_json }}
{% endif %}
{% if matrix_tuwunel_config_forbidden_remote_server_names | length > 0 %}
forbidden_remote_server_names = {{ matrix_tuwunel_config_forbidden_remote_server_names | to_json }}
{% endif %}
{% if matrix_tuwunel_config_forbidden_remote_room_directory_server_names | length > 0 %}
forbidden_remote_room_directory_server_names = {{ matrix_tuwunel_config_forbidden_remote_room_directory_server_names | to_json }}
{% endif %}
{% if matrix_tuwunel_config_prevent_media_downloads_from | length > 0 %}
prevent_media_downloads_from = {{ matrix_tuwunel_config_prevent_media_downloads_from | to_json }}
{% endif %}
allow_outgoing_presence = {{ matrix_tuwunel_config_allow_outgoing_presence | to_json }}
{% if matrix_tuwunel_config_url_preview_domain_contains_allowlist | length > 0 %}
url_preview_domain_contains_allowlist = {{ matrix_tuwunel_config_url_preview_domain_contains_allowlist | to_json }}
{% endif %}
{% if matrix_tuwunel_config_url_preview_domain_explicit_allowlist | length > 0 %}
url_preview_domain_explicit_allowlist = {{ matrix_tuwunel_config_url_preview_domain_explicit_allowlist | to_json }}
{% endif %}
url_preview_check_root_domain = {{ matrix_tuwunel_config_url_preview_check_root_domain | to_json }}
create_admin_room = {{ matrix_tuwunel_config_create_admin_room | to_json }}
federate_admin_room = {{ matrix_tuwunel_config_federate_admin_room | to_json }}
grant_admin_to_first_user = {{ matrix_tuwunel_config_grant_admin_to_first_user | to_json }}
log = {{ matrix_tuwunel_config_log | to_json }}
{% if matrix_tuwunel_config_turn_uris | length > 0 %}
turn_uris = {{ matrix_tuwunel_config_turn_uris | to_json }}
{% endif %}
{% if matrix_tuwunel_config_turn_secret | length > 0 %}
turn_secret = {{ matrix_tuwunel_config_turn_secret | to_json }}
{% endif %}
{% if matrix_tuwunel_config_turn_username | length > 0 %}
turn_username = {{ matrix_tuwunel_config_turn_username | to_json }}
{% endif %}
{% if matrix_tuwunel_config_turn_password | length > 0 %}
turn_password = {{ matrix_tuwunel_config_turn_password | to_json }}
{% endif %}
{% if matrix_tuwunel_config_rocksdb_compression_algo | length > 0 %}
rocksdb_compression_algo = {{ matrix_tuwunel_config_rocksdb_compression_algo | to_json }}
{% endif %}
{% if matrix_tuwunel_config_rocksdb_compression_level | string | length > 0 %}
rocksdb_compression_level = {{ matrix_tuwunel_config_rocksdb_compression_level }}
{% endif %}
{% if matrix_tuwunel_config_rocksdb_bottommost_compression_level | string | length > 0 %}
rocksdb_bottommost_compression_level = {{ matrix_tuwunel_config_rocksdb_bottommost_compression_level }}
{% endif %}
rocksdb_direct_io = {{ matrix_tuwunel_config_rocksdb_direct_io | to_json }}
{% if matrix_tuwunel_config_rocksdb_parallelism_threads | int > 0 %}
rocksdb_parallelism_threads = {{ matrix_tuwunel_config_rocksdb_parallelism_threads }}
{% endif %}
{% if matrix_tuwunel_config_rocksdb_max_log_file_size | string | length > 0 %}
rocksdb_max_log_file_size = {{ matrix_tuwunel_config_rocksdb_max_log_file_size }}
{% endif %}
{% if matrix_tuwunel_config_rocksdb_log_time_to_roll | string | length > 0 %}
rocksdb_log_time_to_roll = {{ matrix_tuwunel_config_rocksdb_log_time_to_roll }}
{% endif %}
{% if matrix_tuwunel_config_database_backup_path | length > 0 %}
database_backup_path = {{ matrix_tuwunel_config_database_backup_path | to_json }}
database_backups_to_keep = {{ matrix_tuwunel_config_database_backups_to_keep }}
{% endif %}
{% if matrix_tuwunel_config_cache_capacity_modifier | string | length > 0 %}
cache_capacity_modifier = {{ matrix_tuwunel_config_cache_capacity_modifier }}
{% endif %}
{% if matrix_tuwunel_config_db_cache_capacity_mb | string | length > 0 %}
db_cache_capacity_mb = {{ matrix_tuwunel_config_db_cache_capacity_mb }}
{% endif %}
{% if matrix_tuwunel_config_db_write_buffer_capacity_mb | string | length > 0 %}
db_write_buffer_capacity_mb = {{ matrix_tuwunel_config_db_write_buffer_capacity_mb }}
{% endif %}
{% if matrix_tuwunel_config_sentry_enabled | bool %}
sentry = true
{% if matrix_tuwunel_config_sentry_endpoint | length > 0 %}
sentry_endpoint = {{ matrix_tuwunel_config_sentry_endpoint | to_json }}
{% endif %}
sentry_send_server_name = {{ matrix_tuwunel_config_sentry_send_server_name | to_json }}
sentry_traces_sample_rate = {{ matrix_tuwunel_config_sentry_traces_sample_rate }}
{% endif %}
{% if (matrix_tuwunel_config_tls_certs | length > 0) and (matrix_tuwunel_config_tls_key | length > 0) %}
[global.tls]
certs = {{ matrix_tuwunel_config_tls_certs | to_json }}
key = {{ matrix_tuwunel_config_tls_key | to_json }}
dual_protocol = {{ matrix_tuwunel_config_tls_dual_protocol | to_json }}
{% endif %}
{% set well_known_keys = [
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,
matrix_tuwunel_config_well_known_livekit_url,
] %}
{% if well_known_keys | select | list | length > 0 %}
[global.well_known]
{% if matrix_tuwunel_config_well_known_client | length > 0 %}
client = {{ matrix_tuwunel_config_well_known_client | to_json }}
{% endif %}
{% if matrix_tuwunel_config_well_known_server | length > 0 %}
server = {{ matrix_tuwunel_config_well_known_server | to_json }}
{% endif %}
{% if matrix_tuwunel_config_well_known_support_page | length > 0 %}
support_page = {{ matrix_tuwunel_config_well_known_support_page | to_json }}
{% endif %}
{% if matrix_tuwunel_config_well_known_support_email | length > 0 %}
support_email = {{ matrix_tuwunel_config_well_known_support_email | to_json }}
{% endif %}
{% if matrix_tuwunel_config_well_known_support_mxid | length > 0 %}
support_mxid = {{ matrix_tuwunel_config_well_known_support_mxid | to_json }}
{% endif %}
{% if matrix_tuwunel_config_well_known_livekit_url | length > 0 %}
livekit_url = {{ matrix_tuwunel_config_well_known_livekit_url | to_json }}
{% endif %}
{% endif %}
{% if matrix_tuwunel_config_blurhashing_enabled | bool %}
[global.blurhashing]
components_x = {{ matrix_tuwunel_config_blurhashing_components_x }}
components_y = {{ matrix_tuwunel_config_blurhashing_components_y }}
blurhash_max_raw_size = {{ matrix_tuwunel_config_blurhashing_max_raw_size }}
{% endif %}
{% if matrix_tuwunel_config_ldap_enabled | bool %}
[global.ldap]
enable = true
uri = {{ matrix_tuwunel_config_ldap_uri | to_json }}
base_dn = {{ matrix_tuwunel_config_ldap_base_dn | to_json }}
{% if matrix_tuwunel_config_ldap_bind_dn | length > 0 %}
bind_dn = {{ matrix_tuwunel_config_ldap_bind_dn | to_json }}
{% endif %}
{% if matrix_tuwunel_config_ldap_bind_password_file | length > 0 %}
bind_password_file = {{ matrix_tuwunel_config_ldap_bind_password_file | to_json }}
{% endif %}
filter = {{ matrix_tuwunel_config_ldap_filter | to_json }}
uid_attribute = {{ matrix_tuwunel_config_ldap_uid_attribute | to_json }}
name_attribute = {{ matrix_tuwunel_config_ldap_name_attribute | to_json }}
{% if matrix_tuwunel_config_ldap_admin_base_dn | length > 0 %}
admin_base_dn = {{ matrix_tuwunel_config_ldap_admin_base_dn | to_json }}
{% endif %}
{% if matrix_tuwunel_config_ldap_admin_filter | length > 0 %}
admin_filter = {{ matrix_tuwunel_config_ldap_admin_filter | to_json }}
{% endif %}
{% endif %}
{% if matrix_tuwunel_config_jwt_enabled | bool %}
[global.jwt]
enable = true
{% if matrix_tuwunel_config_jwt_key | length > 0 %}
key = {{ matrix_tuwunel_config_jwt_key | to_json }}
{% endif %}
format = {{ matrix_tuwunel_config_jwt_format | to_json }}
algorithm = {{ matrix_tuwunel_config_jwt_algorithm | to_json }}
register_user = {{ matrix_tuwunel_config_jwt_register_user | to_json }}
{% if matrix_tuwunel_config_jwt_audience | length > 0 %}
audience = {{ matrix_tuwunel_config_jwt_audience | to_json }}
{% endif %}
{% if matrix_tuwunel_config_jwt_issuer | length > 0 %}
issuer = {{ matrix_tuwunel_config_jwt_issuer | to_json }}
{% endif %}
require_exp = {{ matrix_tuwunel_config_jwt_require_exp | to_json }}
require_nbf = {{ matrix_tuwunel_config_jwt_require_nbf | to_json }}
validate_exp = {{ matrix_tuwunel_config_jwt_validate_exp | to_json }}
validate_nbf = {{ matrix_tuwunel_config_jwt_validate_nbf | to_json }}
{% endif %}
{% for idp in matrix_tuwunel_config_identity_providers %}
[[global.identity_provider]]
{% for key, value in idp.items() %}
{{ key }} = {{ value | to_json }}
{% endfor %}
{% endfor %}
{% for sp in matrix_tuwunel_config_storage_providers %}
[global.storage_provider.{{ sp.id }}.{{ sp.kind }}]
{% for key, value in sp.items() if key not in ['id', 'kind'] %}
{{ key }} = {{ value | to_json }}
{% endfor %}
{% endfor %}