mautrix-gmessages: expose bridge HTTP API (for mautrix-manager and similar)

Add a generic mechanism for exposing bridges' HTTP API (the provisioning API, etc.) publicly on the Matrix domain, so tools like mautrix-manager (https://github.com/mautrix/manager) can drive bridge login. - Introduce global matrix_bridges_exposure_* vars (on by default), exposing each supported bridge under `<matrix-fqn>/bridges/<bridge>`. - mautrix-gmessages: make the provisioning shared secret configurable (auto-generated in group_vars) so the provisioning API is enabled, route the whole bridge HTTP port via Traefik, and populate appservice.public_address. Requests are authenticated by the bridge itself (per-user Matrix access token for the provisioning API, homeserver token for the appservice endpoints), not by the reverse proxy. This is the first bridge converted; the other mautrix bridges will follow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 03:20:44 +03:00 · 2026-06-28 19:52:24 +03:00
parent d61979a0b9
commit a4ddba3989
5 changed files with 76 additions and 2 deletions
@@ -54,6 +54,15 @@ matrix_bridges_msc4190_enabled: "{{ matrix_authentication_service_enabled and ma
 # Global var for enabling bridge self-signing ( On supported bridges)
 matrix_bridges_self_sign_enabled: "{{ matrix_bridges_msc4190_enabled }}"

+# Global vars for exposing bridges' HTTP API publicly on the Matrix domain.
+# This is used by tools like mautrix-manager (https://github.com/mautrix/manager) to drive bridge login.
+# Each supported bridge's HTTP endpoint is exposed under `<path_prefix>/<bridge>` (e.g. `/bridges/gmessages`).
+# Requests are authenticated by the bridge itself (e.g. per-user Matrix access token for the provisioning API,
+# or the homeserver token for the appservice endpoints), not by us.
+matrix_bridges_exposure_enabled: true
+matrix_bridges_exposure_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_bridges_exposure_path_prefix: /bridges
+
 # Global var to enable/disable relay mode across all bridges with relay mode support
 matrix_bridges_relay_enabled: false

@@ -38,6 +38,13 @@ matrix_mautrix_gmessages_homeserver_async_media: false
 matrix_mautrix_gmessages_homeserver_domain: "{{ matrix_domain }}"
 matrix_mautrix_gmessages_appservice_address: "http://matrix-mautrix-gmessages:8080"

+# Scheme of the bridge's public address (see `matrix_mautrix_gmessages_bridge_public_address`).
+matrix_mautrix_gmessages_scheme: https
+
+# The public base URL at which this bridge's HTTP API is reachable from outside (when exposed).
+# Used for the provisioning API's external-server (OpenID) flow and for public media links.
+matrix_mautrix_gmessages_bridge_public_address: "{{ (matrix_mautrix_gmessages_scheme + '://' + matrix_mautrix_gmessages_exposure_hostname + matrix_mautrix_gmessages_exposure_path_prefix) if matrix_mautrix_gmessages_exposure_enabled else '' }}"
+
 matrix_mautrix_gmessages_msc4190_enabled: "{{ matrix_bridges_msc4190_enabled }}"
 matrix_mautrix_gmessages_self_sign_enabled: "{{ matrix_bridges_self_sign_enabled }}"

@@ -75,6 +82,15 @@ matrix_mautrix_gmessages_container_labels_metrics_middleware_basic_auth_enabled:
 # See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
 matrix_mautrix_gmessages_container_labels_metrics_middleware_basic_auth_users: ''

+# Controls whether labels will be added that expose mautrix-gmessages' HTTP API
+# (used by tools like mautrix-manager for bridge login) at `https://<hostname><path_prefix>`.
+matrix_mautrix_gmessages_container_labels_exposure_enabled: "{{ matrix_mautrix_gmessages_exposure_enabled }}"
+matrix_mautrix_gmessages_container_labels_exposure_traefik_rule: "Host(`{{ matrix_mautrix_gmessages_exposure_hostname }}`) && PathPrefix(`{{ matrix_mautrix_gmessages_exposure_path_prefix }}`)"
+matrix_mautrix_gmessages_container_labels_exposure_traefik_priority: 0
+matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints: "{{ matrix_mautrix_gmessages_container_labels_traefik_entrypoints }}"
+matrix_mautrix_gmessages_container_labels_exposure_traefik_tls: "{{ matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints != 'web' }}"
+matrix_mautrix_gmessages_container_labels_exposure_traefik_tls_certResolver: "{{ matrix_mautrix_gmessages_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
 # matrix_mautrix_gmessages_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
 # See `../templates/labels.j2` for details.
 #
@@ -119,6 +135,11 @@ matrix_mautrix_gmessages_metrics_proxying_enabled: false
 matrix_mautrix_gmessages_metrics_proxying_hostname: ''
 matrix_mautrix_gmessages_metrics_proxying_path_prefix: ''

+# Controls whether mautrix-gmessages' HTTP API is exposed publicly (used by tools like mautrix-manager for bridge login).
+matrix_mautrix_gmessages_exposure_enabled: false
+matrix_mautrix_gmessages_exposure_hostname: ''
+matrix_mautrix_gmessages_exposure_path_prefix: ''
+
 # Database-related configuration fields.
 #
 # To use SQLite, stick to these defaults.
@@ -168,6 +189,10 @@ matrix_mautrix_gmessages_appservice_username_template: "{% raw %}gmessages_{{.}}

 matrix_mautrix_gmessages_public_media_signing_key: ''

+# Shared secret for authentication of provisioning API requests.
+# If set to "disable", the provisioning API will be disabled.
+matrix_mautrix_gmessages_provisioning_shared_secret: disable
+
 matrix_mautrix_gmessages_bridge_personal_filtering_spaces: true

 matrix_mautrix_gmessages_bridge_permissions: |
@@ -181,7 +181,7 @@ appservice:
    address: {{ matrix_mautrix_gmessages_appservice_address }}
    # A public address that external services can use to reach this appservice.
    # This value doesn't affect the registration file.
-    public_address: https://bridge.example.com
+    public_address: {{ matrix_mautrix_gmessages_bridge_public_address | to_json }}

    # The hostname and port where this appservice should listen.
    # For Docker, you generally have to change the hostname to 0.0.0.0.
@@ -247,7 +247,7 @@ provisioning:
    prefix: /_matrix/provision
    # Shared secret for authentication. If set to "generate" or null, a random secret will be generated,
    # or if set to "disable", the provisioning API will be disabled.
-    shared_secret: disable
+    shared_secret: {{ matrix_mautrix_gmessages_provisioning_shared_secret | to_json }}
    # Whether to allow provisioning API requests to be authed using Matrix access tokens.
    # This follows the same rules as double puppeting to determine which server to contact to check the token,
    # which means that by default, it only works for users on the same server as the bridge.
@@ -46,6 +46,39 @@ traefik.http.routers.matrix-mautrix-gmessages-metrics.tls.certResolver={{ matrix
 ############################################################
 {% endif %}

+{% if matrix_mautrix_gmessages_container_labels_exposure_enabled %}
+############################################################
+#                                                          #
+# Bridge API exposure                                      #
+#                                                          #
+############################################################
+
+traefik.http.services.matrix-mautrix-gmessages-exposure.loadbalancer.server.port=8080
+
+traefik.http.middlewares.matrix-mautrix-gmessages-exposure-strip-prefix.stripprefix.prefixes={{ matrix_mautrix_gmessages_exposure_path_prefix }}
+traefik.http.routers.matrix-mautrix-gmessages-exposure.middlewares=matrix-mautrix-gmessages-exposure-strip-prefix
+
+traefik.http.routers.matrix-mautrix-gmessages-exposure.rule={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_rule }}
+
+{% if matrix_mautrix_gmessages_container_labels_exposure_traefik_priority | int > 0 %}
+traefik.http.routers.matrix-mautrix-gmessages-exposure.priority={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_priority }}
+{% endif %}
+
+traefik.http.routers.matrix-mautrix-gmessages-exposure.service=matrix-mautrix-gmessages-exposure
+traefik.http.routers.matrix-mautrix-gmessages-exposure.entrypoints={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_entrypoints }}
+
+traefik.http.routers.matrix-mautrix-gmessages-exposure.tls={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_tls | to_json }}
+{% if matrix_mautrix_gmessages_container_labels_exposure_traefik_tls %}
+traefik.http.routers.matrix-mautrix-gmessages-exposure.tls.certResolver={{ matrix_mautrix_gmessages_container_labels_exposure_traefik_tls_certResolver }}
+{% endif %}
+
+############################################################
+#                                                          #
+# /Bridge API exposure                                     #
+#                                                          #
+############################################################
+{% endif %}
+

 {% endif %}