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>

roles/custom/matrix-tuwunel/tasks/install.yml

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure tuwunel config path exists
+  ansible.builtin.file:
+    path: "{{ matrix_tuwunel_config_path }}"
+    state: directory
+    mode: '0750'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+
+- name: Ensure tuwunel data path exists
+  ansible.builtin.file:
+    path: "{{ matrix_tuwunel_data_path }}"
+    state: directory
+    mode: '0770'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+
+- name: Ensure tuwunel configuration installed
+  ansible.builtin.template:
+    src: "{{ matrix_tuwunel_template_tuwunel_config }}"
+    dest: "{{ matrix_tuwunel_config_path }}/tuwunel.toml"
+    mode: '0644'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  register: matrix_tuwunel_config_result
+
+- name: Ensure tuwunel support files installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/{{ item }}.j2"
+    dest: "{{ matrix_tuwunel_base_path }}/{{ item }}"
+    mode: '0640'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - labels
+    - env
+  register: matrix_tuwunel_support_files_result
+
+- name: Ensure tuwunel container network is created
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_tuwunel_container_network }}"
+    driver: bridge
+    driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
+
+- name: Ensure tuwunel container image is pulled
+  community.docker.docker_image_pull:
+    name: "{{ matrix_tuwunel_container_image }}"
+    pull: always
+  register: matrix_tuwunel_container_image_pull_result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: matrix_tuwunel_container_image_pull_result is not failed
+
+- name: Ensure matrix-tuwunel.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-tuwunel.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-tuwunel.service"
+    mode: '0644'
+  register: matrix_tuwunel_systemd_service_result
+
+- name: Determine whether tuwunel needs a restart
+  ansible.builtin.set_fact:
+    matrix_tuwunel_restart_necessary: >-
+      {{
+        matrix_tuwunel_config_result.changed | default(false)
+        or matrix_tuwunel_support_files_result.changed | default(false)
+        or matrix_tuwunel_systemd_service_result.changed | default(false)
+        or matrix_tuwunel_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-tuwunel/tasks/main.yml

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- tags:
+    - setup-all
+    - setup-tuwunel
+    - install-all
+    - install-tuwunel
+  block:
+    - when: matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"
+
+- tags:
+    - setup-all
+    - setup-tuwunel
+  block:
+    - when: not matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"
+
+- tags:
+    - self-check
+  block:
+    - when: matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/self_check_client_api.yml"
+
+    - when: matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/self_check_federation_api.yml"
+
+- tags:
+    - tuwunel-migrate-from-conduwuit
+  block:
+    - when: matrix_tuwunel_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/migrate_from_conduwuit.yml"

roles/custom/matrix-tuwunel/tasks/migrate_from_conduwuit.yml

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+# Migrates from the conduwuit server implementation (`/matrix/conduwuit`) to tuwunel (`/matrix/tuwunel`).
+# Tuwunel is the official successor to conduwuit and reads conduwuit's RocksDB layout directly.
+# We back up the freshly generated tuwunel directory, copy conduwuit's data into it,
+# rename the config file, restore tuwunel's labels file, and start the new service.
+
+- name: Check existence of conduwuit directory
+  ansible.builtin.stat:
+    path: "{{ matrix_base_data_path }}/conduwuit"
+  register: matrix_removed_conduwuit_directory_stat
+
+- name: Check existence of tuwunel directory
+  ansible.builtin.stat:
+    path: "{{ matrix_base_data_path }}/tuwunel"
+  register: matrix_tuwunel_directory_stat
+
+- when: >
+        matrix_removed_conduwuit_directory_stat.stat.exists | bool and
+        matrix_tuwunel_directory_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-tuwunel.service systemd service is stopped
+      ansible.builtin.systemd:
+        name: matrix-tuwunel
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure tuwunel directory is backed up
+      ansible.builtin.command:
+        cmd: "mv {{ matrix_base_data_path }}/tuwunel {{ matrix_base_data_path }}/tuwunel_old"
+        creates: "{{ matrix_base_data_path }}/tuwunel_old"
+        removes: "{{ matrix_base_data_path }}/tuwunel"
+
+    - name: Ensure conduwuit directory contents are copied to tuwunel
+      ansible.builtin.copy:
+        src: "{{ matrix_base_data_path }}/conduwuit/"
+        dest: "{{ matrix_base_data_path }}/tuwunel"
+        remote_src: true
+        mode: preserve
+
+    - name: Ensure conduwuit.toml file is renamed
+      ansible.builtin.command:
+        cmd: "mv {{ matrix_base_data_path }}/tuwunel/config/conduwuit.toml {{ matrix_base_data_path }}/tuwunel/config/tuwunel.toml"
+        removes: "{{ matrix_base_data_path }}/tuwunel/config/conduwuit.toml"
+
+    - name: Ensure tuwunel labels are restored
+      ansible.builtin.copy:
+        src: "{{ matrix_base_data_path }}/tuwunel_old/labels"
+        dest: "{{ matrix_base_data_path }}/tuwunel/labels"
+        remote_src: true
+        force: true
+        mode: preserve
+
+    - name: Ensure directories ownership is set
+      block:
+        - name: Set tuwunel ownership
+          ansible.builtin.file:
+            path: "{{ matrix_base_data_path }}/tuwunel"
+            state: directory
+            owner: "{{ matrix_user_name }}"
+            group: "{{ matrix_group_name }}"
+            recurse: true
+
+        - name: Set tuwunel_old ownership
+          ansible.builtin.file:
+            path: "{{ matrix_base_data_path }}/tuwunel_old"
+            state: directory
+            owner: "{{ matrix_user_name }}"
+            group: "{{ matrix_group_name }}"
+            recurse: true
+
+    - name: Ensure matrix-tuwunel.service systemd service is started
+      ansible.builtin.systemd:
+        name: matrix-tuwunel
+        state: started
+        enabled: true
+        daemon_reload: true

roles/custom/matrix-tuwunel/tasks/self_check_client_api.yml

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check Matrix Client API
+  ansible.builtin.uri:
+    url: "{{ matrix_tuwunel_client_api_url_endpoint_public }}"
+    follow_redirects: none
+    validate_certs: "{{ matrix_tuwunel_self_check_validate_certificates }}"
+  register: result_matrix_tuwunel_client_api
+  ignore_errors: true
+  check_mode: false
+  when: matrix_tuwunel_enabled | bool
+  delegate_to: 127.0.0.1
+  become: false
+
+- name: Fail if Matrix Client API not working
+  ansible.builtin.fail:
+    msg: "Failed checking Matrix Client API is up at `{{ matrix_server_fqn_matrix }}` (checked endpoint: `{{ matrix_tuwunel_client_api_url_endpoint_public }}`). Is tuwunel running? Is port 443 open in your firewall? Full error: {{ result_matrix_tuwunel_client_api }}"
+  when: "matrix_tuwunel_enabled | bool and (result_matrix_tuwunel_client_api.failed or 'json' not in result_matrix_tuwunel_client_api)"
+
+- name: Report working Matrix Client API
+  ansible.builtin.debug:
+    msg: "The Matrix Client API at `{{ matrix_server_fqn_matrix }}` (checked endpoint: `{{ matrix_tuwunel_client_api_url_endpoint_public }}`) is working"
+  when: matrix_tuwunel_enabled | bool

roles/custom/matrix-tuwunel/tasks/self_check_federation_api.yml

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check Matrix Federation API
+  ansible.builtin.uri:
+    url: "{{ matrix_tuwunel_federation_api_url_endpoint_public }}"
+    follow_redirects: none
+    validate_certs: "{{ matrix_tuwunel_self_check_validate_certificates }}"
+  register: result_matrix_tuwunel_federation_api
+  ignore_errors: true
+  check_mode: false
+  when: matrix_tuwunel_enabled | bool
+  delegate_to: 127.0.0.1
+  become: false
+
+- name: Fail if Matrix Federation API not working
+  ansible.builtin.fail:
+    msg: "Failed checking Matrix Federation API is up at `{{ matrix_server_fqn_matrix }}` (checked endpoint: `{{ matrix_tuwunel_federation_api_url_endpoint_public }}`). Is tuwunel running? Is port {{ matrix_federation_public_port }} open in your firewall? Full error: {{ result_matrix_tuwunel_federation_api }}"
+  when: "matrix_tuwunel_enabled | bool and matrix_tuwunel_config_allow_federation | bool and (result_matrix_tuwunel_federation_api.failed or 'json' not in result_matrix_tuwunel_federation_api)"
+
+- name: Fail if Matrix Federation API unexpectedly enabled
+  ansible.builtin.fail:
+    msg: "Matrix Federation API is up at `{{ matrix_server_fqn_matrix }}` (checked endpoint: `{{ matrix_tuwunel_federation_api_url_endpoint_public }}`) despite being disabled."
+  when: "matrix_tuwunel_enabled | bool and not matrix_tuwunel_config_allow_federation | bool and not result_matrix_tuwunel_federation_api.failed"
+
+- name: Report working Matrix Federation API
+  ansible.builtin.debug:
+    msg: "The Matrix Federation API at `{{ matrix_server_fqn_matrix }}` (checked endpoint: `{{ matrix_tuwunel_federation_api_url_endpoint_public }}`) is working"
+  when: "matrix_tuwunel_enabled | bool and matrix_tuwunel_config_allow_federation | bool"

roles/custom/matrix-tuwunel/tasks/setup_install.yml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- ansible.builtin.include_tasks: "{{ role_path }}/tasks/install.yml"

roles/custom/matrix-tuwunel/tasks/setup_uninstall.yml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- ansible.builtin.include_tasks: "{{ role_path }}/tasks/uninstall.yml"

roles/custom/matrix-tuwunel/tasks/uninstall.yml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check existence of matrix-tuwunel service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-tuwunel.service"
+  register: matrix_tuwunel_service_stat
+
+- when: matrix_tuwunel_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-tuwunel is stopped
+      ansible.builtin.systemd:
+        name: matrix-tuwunel
+        state: stopped
+        daemon_reload: true
+
+    - name: Ensure matrix-tuwunel.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-tuwunel.service"
+        state: absent

roles/custom/matrix-tuwunel/tasks/validate_config.yml

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 MDAD project contributors
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Fail if required tuwunel settings not defined
+  ansible.builtin.fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
+  with_items:
+    - {'name': 'matrix_tuwunel_hostname', when: true}
+    - {'name': 'matrix_tuwunel_container_network', when: true}
+    - {'name': 'matrix_tuwunel_container_labels_internal_client_api_traefik_entrypoints', when: "{{ matrix_tuwunel_container_labels_internal_client_api_enabled }}"}
+
+- name: Fail if registration is enabled without a token or explicit acknowledgement
+  ansible.builtin.fail:
+    msg: >-
+      `matrix_tuwunel_config_allow_registration` is true, but neither
+      `matrix_tuwunel_config_registration_token` nor
+      `matrix_tuwunel_config_yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
+      is set. Set a registration token (recommended) or explicitly opt in to open registration.
+  when: >-
+    matrix_tuwunel_config_allow_registration | bool
+    and (matrix_tuwunel_config_registration_token | length == 0)
+    and not (matrix_tuwunel_config_yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse | bool)
+
+- name: Fail if a storage provider is missing required fields
+  ansible.builtin.fail:
+    msg: >-
+      Storage provider `{{ item.id | default('?') }}` is missing required fields.
+      Each entry must define both `id` and `kind` (one of: local, s3).
+  when: "(item.id | default('') | length == 0) or (item.kind | default('') not in ['local', 's3'])"
+  with_items: "{{ matrix_tuwunel_config_storage_providers }}"
+
+- name: Fail if an identity provider is missing required fields
+  ansible.builtin.fail:
+    msg: >-
+      Identity provider entry is missing both `client_id` and `brand`.
+      At minimum one of these is required for tuwunel to identify the provider.
+  when: "(item.client_id | default('') | length == 0) and (item.brand | default('') | length == 0)"
+  with_items: "{{ matrix_tuwunel_config_identity_providers }}"