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>

group_vars/matrix_servers

@@ -6019,6 +6019,24 @@ matrix_static_files_file_matrix_client_property_org_matrix_msc4143_rtc_foci_auto
     )
   }}
 
+# Advertise all enabled and exposed mautrix bridges for auto-discovery by tools like Mautrix Manager.
+# A bridge's public address is only reachable when the playbook attaches its Traefik labels and emits the exposure router,
+# so we gate on these in addition to the bridge being enabled.
+matrix_static_files_file_matrix_mautrix_property_fi_mau_bridges_auto: |-
+  {{
+    [
+      matrix_mautrix_bluesky_appservice_public_address if (matrix_mautrix_bluesky_enabled and matrix_mautrix_bluesky_container_labels_traefik_enabled and matrix_mautrix_bluesky_container_labels_exposure_enabled) else '',
+      matrix_mautrix_gmessages_bridge_public_address if (matrix_mautrix_gmessages_enabled and matrix_mautrix_gmessages_container_labels_traefik_enabled and matrix_mautrix_gmessages_container_labels_exposure_enabled) else '',
+      matrix_mautrix_meta_instagram_bridge_public_address if (matrix_mautrix_meta_instagram_enabled and matrix_mautrix_meta_instagram_container_labels_traefik_enabled and matrix_mautrix_meta_instagram_container_labels_exposure_enabled) else '',
+      matrix_mautrix_meta_messenger_bridge_public_address if (matrix_mautrix_meta_messenger_enabled and matrix_mautrix_meta_messenger_container_labels_traefik_enabled and matrix_mautrix_meta_messenger_container_labels_exposure_enabled) else '',
+      matrix_mautrix_signal_bridge_public_address if (matrix_mautrix_signal_enabled and matrix_mautrix_signal_container_labels_traefik_enabled and matrix_mautrix_signal_container_labels_exposure_enabled) else '',
+      matrix_mautrix_slack_bridge_public_address if (matrix_mautrix_slack_enabled and matrix_mautrix_slack_container_labels_traefik_enabled and matrix_mautrix_slack_container_labels_exposure_enabled) else '',
+      matrix_mautrix_telegram_bridge_public_address if (matrix_mautrix_telegram_enabled and matrix_mautrix_telegram_container_labels_traefik_enabled and matrix_mautrix_telegram_container_labels_exposure_enabled) else '',
+      matrix_mautrix_twitter_appservice_public_address if (matrix_mautrix_twitter_enabled and matrix_mautrix_twitter_container_labels_traefik_enabled and matrix_mautrix_twitter_container_labels_exposure_enabled) else '',
+      matrix_mautrix_whatsapp_bridge_public_address if (matrix_mautrix_whatsapp_enabled and matrix_mautrix_whatsapp_container_labels_traefik_enabled and matrix_mautrix_whatsapp_container_labels_exposure_enabled) else '',
+    ] | select | list
+  }}
+
 matrix_static_files_file_matrix_server_property_m_server: "{{ matrix_server_fqn_matrix_federation }}:{{ matrix_federation_public_port }}"
 
 matrix_static_files_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"

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