matrix-static-files: advertise exposed mautrix bridges via /.well-known/matrix/mautrix

Emit a /.well-known/matrix/mautrix file listing the base URLs of all
enabled and exposed mautrix bridges under the `fi.mau.bridges` property,
so tools like Mautrix Manager (https://github.com/mautrix/manager) can
auto-discover them.

The list is built in group_vars from each bridge's public address and is
gated on the bridge being enabled, the playbook attaching its Traefik
labels, and the exposure router being emitted, so we only advertise URLs
that are actually reachable. The file follows the same auto/custom and
configuration-extension pattern as the other well-known files and is only
written when the list is non-empty.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

roles/custom/matrix-static-files/defaults/main.yml

@@ -358,6 +358,59 @@ matrix_static_files_file_matrix_support_configuration: "{{ matrix_static_files_f
 ########################################################################
 
 
+########################################################################
+#                                                                      #
+# Related to /.well-known/matrix/mautrix                               #
+#                                                                      #
+########################################################################
+
+# Controls whether a `/.well-known/matrix/mautrix` file is generated and used at all.
+# This file allows tools like Mautrix Manager (https://github.com/mautrix/manager) to auto-discover the bridges hosted on this server.
+# By default, it's enabled only when there's something to advertise (see `matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges`).
+matrix_static_files_file_matrix_mautrix_enabled: "{{ matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges | length > 0 }}"
+
+# Controls the fi.mau.bridges property in the /.well-known/matrix/mautrix file.
+# This is a list of base URLs for bridges hosted on (and connected to) this server.
+matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges: "{{ matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_auto + matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_custom }}"
+matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_auto: []
+matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_custom: []
+
+# Default /.well-known/matrix/mautrix configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrix_static_files_file_matrix_mautrix_configuration_extension_json`)
+# or completely replace this variable with your own template.
+matrix_static_files_file_matrix_mautrix_configuration_json: "{{ lookup('template', 'templates/public/.well-known/matrix/mautrix.j2', convert_data=False) | from_json }}"
+
+# Your custom JSON configuration for /.well-known/matrix/mautrix should go to `matrix_static_files_file_matrix_mautrix_configuration_extension_json`.
+# This configuration extends the default starting configuration (`matrix_static_files_file_matrix_mautrix_configuration_extension_json`).
+#
+# You can override individual variables from the default configuration, or introduce new ones.
+#
+# If you need something more special, you can take full control by
+# completely redefining `matrix_static_files_file_matrix_mautrix_configuration_json`.
+#
+# Example configuration extension follows:
+#
+# matrix_static_files_file_matrix_mautrix_configuration_extension_json: |
+#   {
+#     "fi.mau.external_bridge_servers": ["https://bridges.example.com"]
+#   }
+matrix_static_files_file_matrix_mautrix_configuration_extension_json: '{}'
+
+matrix_static_files_file_matrix_mautrix_configuration_extension: "{{ matrix_static_files_file_matrix_mautrix_configuration_extension_json | from_json if matrix_static_files_file_matrix_mautrix_configuration_extension_json | from_json is mapping else {} }}"
+
+# Holds the final /.well-known/matrix/mautrix configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_static_files_file_matrix_mautrix_configuration_json` or `matrix_static_files_file_matrix_mautrix_configuration_extension_json`.
+matrix_static_files_file_matrix_mautrix_configuration: "{{ matrix_static_files_file_matrix_mautrix_configuration_json | combine(matrix_static_files_file_matrix_mautrix_configuration_extension, recursive=True) }}"
+
+########################################################################
+#                                                                      #
+# /Related to /.well-known/matrix/mautrix                              #
+#                                                                      #
+########################################################################
+
+
 ########################################################################
 #                                                                      #
 # Related to index.html                                                #

roles/custom/matrix-static-files/tasks/install.yml

@@ -65,6 +65,10 @@
       dest: "{{ matrix_static_files_public_well_known_matrix_path }}/support"
       when: "{{ matrix_static_files_file_matrix_support_enabled }}"
 
+    - content: "{{ matrix_static_files_file_matrix_mautrix_configuration | to_nice_json }}"
+      dest: "{{ matrix_static_files_public_well_known_matrix_path }}/mautrix"
+      when: "{{ matrix_static_files_file_matrix_mautrix_enabled }}"
+
     # This one will not be deleted if `matrix_static_files_file_index_html_enabled` flips to `false`.
     # See the comment for `matrix_static_files_file_index_html_enabled` to learn why.
     - content: "{{ matrix_static_files_file_index_html_template }}"
@@ -84,6 +88,12 @@
     state: absent
   when: "not matrix_static_files_file_matrix_support_enabled | bool"
 
+- name: Ensure /.well-known/matrix/mautrix file deleted if not enabled
+  ansible.builtin.file:
+    path: "{{ matrix_static_files_public_well_known_matrix_path }}/mautrix"
+    state: absent
+  when: "not matrix_static_files_file_matrix_mautrix_enabled | bool"
+
 - name: Ensure matrix-static-files container image is pulled
   community.docker.docker_image_pull:
     name: "{{ matrix_static_files_container_image }}"

roles/custom/matrix-static-files/templates/public/.well-known/matrix/mautrix.j2

@@ -0,0 +1,3 @@
+{
+	"fi.mau.bridges": {{ matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges | to_json }}
+}

roles/custom/matrix-static-files/templates/public/.well-known/matrix/mautrix.j2.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later