Upgrade mautrix-telegram (v0.15.3 -> v0.2604.0) (bridgev2) and adapt configuration

Matches the earlier Python -> Go rewrites of the other mautrix-* bridges.

Related to:
- https://github.com/mautrix/telegram/releases/tag/v0.2604.0
- https://mau.fi/blog/2026-04-mautrix-release/

The bridge is now a Go binary with upstream-handled automatic database and
config migration on first start, so in-place upgrades on Postgres should
Just Work for users on the defaults. The lottieconverter sidecar container
is gone (bundled upstream), and the public web-based login endpoint is
gone (login happens inside Matrix now).

Upstream v0.2604.0 has a known bug in the legacy SQLite migration that
can corrupt data. The role detects legacy Python-bridge SQLite databases
(via the `telethon_sessions` table signature) and refuses to upgrade,
pointing users to switch to Postgres (playbook-managed pgloader migration)
or wait for the next upstream release. The guard is isolated in its own
`validate_config_sqlite_legacy_migration_bug.yml` so it can be deleted
cleanly once upstream fixes the bug.

Removed variables (all caught by the deprecation check in
`validate_config.yml` with actionable rename/removal hints): the entire
`_hostname` / `_path_prefix` / `_scheme` / `_public_endpoint` /
`_appservice_public_*` / `_container_labels_public_endpoint_*` /
`_container_http_host_bind_port` family (web login endpoint is gone);
`_bot_token` (old-style relaybot is gone, use the common bridgev2 relay
mode); `_filter_mode` (dropped upstream); `_bridge_login_shared_secret_map*`
(use Appservice Double Puppet); `_username_template`, `_alias_template`,
`_displayname_template` (templates moved under `network:`, new Go-template
syntax, exposed via `_network_displayname_template`); all
`_lottieconverter_*` variables; `_appservice_database` (renamed to
`_appservice_database_uri`).

Added playbook-time validation that catches legacy permission values
(`relaybot`, `puppeting`, `full`) in the fully-merged config (so overrides
via `matrix_mautrix_telegram_configuration_extension_yaml` are caught too),
with a mapping hint in the error message.

Other notes:

- The legacy sqlite->postgres relocation of `{base_path}/mautrix-telegram.db`
  to `{data_path}/mautrix-telegram.db` now happens BEFORE the pgloader
  migration step, so users who flip to Postgres as part of this upgrade
  get their data imported correctly.
- The Ketesa managed-user regex for the telegram namespace is updated to
  match both regular IDs and the new `channel-<id>` form used by bridgev2.
- `matrix_playbook_migration_expected_version` bumped to v2026.04.24.0,
  with a new breaking-change entry pointing at the CHANGELOG section.

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

CHANGELOG.md

@@ -1,3 +1,20 @@
+# 2026-04-24
+
+## (BC Break) mautrix-telegram has been rewritten in Go (bridgev2)
+
+The [mautrix-telegram](./docs/configuring-playbook-bridge-mautrix-telegram.md) bridge has been [rewritten in Go](https://mau.fi/blog/2026-04-mautrix-release/) on top of the [bridgev2](https://docs.mau.fi/bridges/go/) architecture. See the [upstream v26.04 release notes](https://github.com/mautrix/telegram/releases/tag/v0.2604.0) for what changed in the bridge itself (shared-portal behavior, management-room state, new features, etc.).
+
+**Most users won't have to do anything.** If you use the playbook's integrated Postgres (the default) and haven't customized telegram-bridge variables beyond `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash`, just re-run the playbook; the bridge will migrate itself on first start. Taking a backup beforehand is still a good idea.
+
+⚠️ **SQLite users: do not upgrade yet.** Upstream v0.2604.0 has a [known bug in the legacy SQLite migration](https://github.com/mautrix/telegram/releases/tag/v0.2604.0) that can corrupt your data. The playbook detects this case and will refuse to proceed. Either switch to Postgres first (set `matrix_mautrix_telegram_database_engine: postgres`; the playbook handles the pgloader migration), or wait for the next upstream release.
+
+Playbook-specific things to know. The playbook will fail loudly if you're affected:
+
+- Many `matrix_mautrix_telegram_*` variables have been **removed** (web-login endpoint, lottieconverter, username/alias/displayname templates, filter-mode, bot-token relaybot, Shared-Secret-Auth map). The deprecation check will tell you exactly what to rename or drop when you run the playbook.
+- **Old-style relaybot users** (`matrix_mautrix_telegram_bot_token`): switch to the common [mautrix bridge relay mode](./docs/configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional) via `matrix_mautrix_telegram_bridge_relay_enabled: true`.
+- **Shared-Secret-Auth double-puppeting users**: switch to [Appservice Double Puppet](./docs/configuring-playbook-appservice-double-puppet.md); the playbook wires it up automatically.
+- **Custom `matrix_mautrix_telegram_bridge_permissions`**: map `relaybot` to `relay`, `puppeting` to `user`, `full` to `user`. Validated at playbook time.
+
 # 2026-04-03
 
 ## (BC Break) Synapse Admin (fork by etke.cc) is now Ketesa

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: 2018 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2018 - 2026 Slavi Pantaleev
 SPDX-FileCopyrightText: 2018 Hugues Morisset
 SPDX-FileCopyrightText: 2019 - 2022 MDAD project contributors
 SPDX-FileCopyrightText: 2021 Panagiotis Georgiadis
@@ -17,7 +17,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 The playbook can install and configure [mautrix-telegram](https://github.com/mautrix/telegram) for you.
 
-See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you.
+See the project's [documentation](https://docs.mau.fi/bridges/go/telegram/index.html) to learn what it does and why it might be useful to you.
 
 ## Prerequisites
 
@@ -25,18 +25,12 @@ See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/in
 
 To use the bridge, you'd need to obtain an API key from [https://my.telegram.org/apps](https://my.telegram.org/apps).
 
-### Enable Appservice Double Puppet or Shared Secret Auth (optional)
+### Enable Appservice Double Puppet (optional)
 
-If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
 
 See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
 
-**Notes**:
-
-- Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
-
-- If you decided to enable Double Puppeting manually, send `login-matrix` to the bot in order to receive an instruction about how to send an access token to it.
-
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `YOUR_TELEGRAM_APP_ID` and `YOUR_TELEGRAM_API_HASH`.
@@ -49,37 +43,16 @@ matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH
 
 ### Relaying
 
-### Enable relay-bot (optional)
+This bridge supports the common [mautrix bridge relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional). Once enabled, any authenticated user can be turned into a relaybot for a chat by sending `!tg set-relay` in that chat.
-
-If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `vars.yml` file:
-
-```yaml
-matrix_mautrix_telegram_bot_token: YOUR_TELEGRAM_BOT_TOKEN
-matrix_mautrix_telegram_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '*': relaybot
-```
 
 ### Configure a user as an administrator of the bridge (optional)
 
 You might also want to give permissions to a user to administrate the bot. See [this section](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional) on the common guide for details about it.
 
-More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
-
-### Use the bridge for direct chats only (optional)
-
-If you want to exclude all groups from syncing and use the Telegram-Bridge only for direct chats, add the following configuration to your `vars.yml` file:
-
-```yaml
-matrix_mautrix_telegram_filter_mode: whitelist
-```
-
 ### Extending the configuration
 
 There are some additional things you may wish to configure about the bridge.
 
-<!-- NOTE: common relay mode is not supported for this bridge -->
 See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#set-the-bots-username-optional), etc.
 
 ## Installing
@@ -99,9 +72,9 @@ The shortcut commands with the [`just` program](just.md) are also available: `ju
 
 To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
+You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/telegram/authentication.html).
 
-After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them. Note that the bridge won't automatically create rooms for private chats.
+After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them.
 
 ## Troubleshooting
 
@@ -109,8 +82,9 @@ As with all other services, you can find the logs in [systemd-journald](https://
 
 ### Increase logging verbosity
 
-The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
 
 ```yaml
-matrix_mautrix_telegram_logging_level: DEBUG
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_telegram_logging_level: debug
 ```

examples/vars.yml

@@ -2,7 +2,7 @@
 # This variable acknowledges that you've reviewed breaking changes up to this version.
 # The playbook will fail if this is outdated, guiding you through what changed.
 # See the changelog: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md
-matrix_playbook_migration_validated_version: v2026.04.03.0
+matrix_playbook_migration_validated_version: v2026.04.24.0
 
 # The bare domain name which represents your Matrix identity.
 # Matrix user IDs for your server will be of the form (`@alice:example.com`).

group_vars/matrix_servers

@@ -1936,9 +1936,6 @@ matrix_mautrix_meta_instagram_database_password: "{{ ((matrix_homeserver_generic
 # We don't enable bridges by default.
 matrix_mautrix_telegram_enabled: false
 
-matrix_mautrix_telegram_hostname: "{{ matrix_server_fqn_matrix }}"
-matrix_mautrix_telegram_path_prefix: "/{{ (matrix_homeserver_generic_secret_key + ':telegram') | hash('sha512') | to_uuid }}"
-
 matrix_mautrix_telegram_systemd_required_services_list_auto: |
   {{
     matrix_addons_homeserver_systemd_services_list
@@ -1946,16 +1943,9 @@ matrix_mautrix_telegram_systemd_required_services_list_auto: |
     ([postgres_identifier ~ '.service'] if (postgres_enabled and matrix_mautrix_telegram_database_hostname == postgres_connection_hostname) else [])
   }}
 
-matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default }}"
-
 matrix_mautrix_telegram_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_mautrix_telegram_container_image_registry_prefix_upstream_default }}"
 
-# Images are multi-arch (amd64 and arm64, but not arm32).
 matrix_mautrix_telegram_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
-matrix_mautrix_telegram_lottieconverter_container_image_self_build: "{{ matrix_architecture not in ['arm64', 'amd64'] }}"
-matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch: "{{ matrix_architecture != 'amd64' }}"
-
-matrix_mautrix_telegram_container_http_host_bind_port: "{{ (matrix_playbook_service_host_bind_interface_prefix ~ '9006') if matrix_playbook_service_host_bind_interface_prefix else '' }}"
 
 matrix_mautrix_telegram_container_network: "{{ matrix_addons_container_network }}"
 
@@ -1986,17 +1976,15 @@ matrix_mautrix_telegram_homeserver_token: "{{ (matrix_homeserver_generic_secret_
 
 matrix_mautrix_telegram_homeserver_async_media: "{{ matrix_homeserver_implementation in ['synapse'] }}"
 
-matrix_mautrix_telegram_bridge_login_shared_secret_map_auto: |-
+matrix_mautrix_telegram_provisioning_shared_secret: "{{ (matrix_homeserver_generic_secret_key + ':mau.telegram.prov') | hash('sha512') | to_uuid }}"
+
+matrix_mautrix_telegram_double_puppet_secrets_auto: |-
   {{
-    ({
+    {
       matrix_mautrix_telegram_homeserver_domain: ("as_token:" + matrix_appservice_double_puppet_registration_as_token)
-    })
+    }
     if matrix_appservice_double_puppet_enabled
-    else (
+    else {}
-      {matrix_mautrix_telegram_homeserver_domain: matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret}
-      if matrix_synapse_ext_password_provider_shared_secret_auth_enabled
-      else {}
-    )
   }}
 
 matrix_mautrix_telegram_metrics_enabled: "{{ prometheus_enabled or matrix_metrics_exposure_enabled }}"
@@ -5132,7 +5120,7 @@ matrix_ketesa_config_asManagedUsers_auto: |
     +
     ([
       '^@'+(matrix_mautrix_telegram_appservice_bot_username | default('') | regex_escape)+':'+(matrix_domain | regex_escape)+'$',
-      '^@'+(matrix_mautrix_telegram_username_template | regex_escape | replace('{userid}', '.+'))+':'+(matrix_domain | regex_escape)+'$',
+      '^@telegram_(channel-)?[0-9]+:'+(matrix_domain | regex_escape)+'$',
     ] if matrix_mautrix_telegram_enabled else [])
     +
     ([

roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml

@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2019 - 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2019 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2020 Johanna Dorothea Reichmann
 # SPDX-FileCopyrightText: 2020 Marcel Partap
 # SPDX-FileCopyrightText: 2021 Aaron Raimist
@@ -21,27 +21,13 @@
 
 matrix_mautrix_telegram_enabled: true
 
-matrix_mautrix_telegram_scheme: https
-matrix_mautrix_telegram_hostname: ''
-matrix_mautrix_telegram_path_prefix: ''
-
-matrix_mautrix_telegram_lottieconverter_container_image_self_build: false
-matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch: false
-matrix_mautrix_telegram_lottieconverter_container_repo: "https://mau.dev/tulir/lottieconverter.git"
-matrix_mautrix_telegram_lottieconverter_container_repo_version: "master"
-matrix_mautrix_telegram_lottieconverter_container_src_files_path: "{{ matrix_base_data_path }}/lotticonverter/docker-src"
-matrix_mautrix_telegram_lottieconverter_container_image: "{{ matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix }}tulir/lottieconverter:alpine-3.16"  # needs to be adjusted according to the FROM clause of Dockerfile of mautrix-telegram
-matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix: "{{ 'localhost/' if matrix_mautrix_telegram_lottieconverter_container_image_self_build else matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream }}"
-matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream: "{{ matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default }}"
-matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default: "dock.mau.dev/"
-
 matrix_mautrix_telegram_container_image_self_build: false
-matrix_mautrix_telegram_container_repo: "https://mau.dev/mautrix/telegram.git"
+matrix_mautrix_telegram_container_image_self_build_repo: "https://mau.dev/mautrix/telegram.git"
-matrix_mautrix_telegram_container_repo_version: "{{ 'master' if matrix_mautrix_telegram_version == 'latest' else matrix_mautrix_telegram_version }}"
+matrix_mautrix_telegram_container_image_self_build_branch: "{{ 'main' if matrix_mautrix_telegram_version == 'latest' else matrix_mautrix_telegram_version }}"
-matrix_mautrix_telegram_container_src_files_path: "{{ matrix_base_data_path }}/mautrix-telegram/docker-src"
 
 # renovate: datasource=docker depName=dock.mau.dev/mautrix/telegram
-matrix_mautrix_telegram_version: v0.15.3
+matrix_mautrix_telegram_version: v0.2604.0
+
 # See: https://mau.dev/mautrix/telegram/container_registry
 matrix_mautrix_telegram_container_image: "{{ matrix_mautrix_telegram_container_image_registry_prefix }}mautrix/telegram:{{ matrix_mautrix_telegram_version }}"
 matrix_mautrix_telegram_container_image_registry_prefix: "{{ 'localhost/' if matrix_mautrix_telegram_container_image_self_build else matrix_mautrix_telegram_container_image_registry_prefix_upstream }}"
@@ -52,30 +38,7 @@ matrix_mautrix_telegram_container_image_force_pull: "{{ matrix_mautrix_telegram_
 matrix_mautrix_telegram_base_path: "{{ matrix_base_data_path }}/mautrix-telegram"
 matrix_mautrix_telegram_config_path: "{{ matrix_mautrix_telegram_base_path }}/config"
 matrix_mautrix_telegram_data_path: "{{ matrix_mautrix_telegram_base_path }}/data"
-
+matrix_mautrix_telegram_container_src_files_path: "{{ matrix_mautrix_telegram_base_path }}/docker-src"
-matrix_mautrix_telegram_command_prefix: "!tg"
-
-matrix_mautrix_telegram_bridge_permissions: |
-  {{
-    {'*': 'relaybot', matrix_mautrix_telegram_homeserver_domain: 'full'}
-    | combine({matrix_admin: 'admin'} if matrix_admin else {})
-  }}
-
-# Get your own API keys at https://my.telegram.org/apps
-matrix_mautrix_telegram_api_id: ''
-matrix_mautrix_telegram_api_hash: ''
-matrix_mautrix_telegram_bot_token: disabled
-
-# Define the filter-mode
-matrix_mautrix_telegram_filter_mode: "blacklist"
-
-# Whether or not the public-facing endpoints should be enabled (web-based login)
-matrix_mautrix_telegram_appservice_public_enabled: true
-
-# Mautrix telegram public endpoint to log in to telegram
-# Use an uuid so it's not easily discoverable.
-# Example: /741a0483-ba17-4682-9900-30bd7269f1cc
-matrix_mautrix_telegram_public_endpoint: "{{ matrix_mautrix_telegram_path_prefix }}"
 
 matrix_mautrix_telegram_homeserver_address: ""
 matrix_mautrix_telegram_homeserver_domain: '{{ matrix_domain }}'
@@ -83,23 +46,15 @@ matrix_mautrix_telegram_homeserver_domain: '{{ matrix_domain }}'
 # Requires a homeserver that supports MSC2246 (https://github.com/matrix-org/matrix-spec-proposals/pull/2246).
 matrix_mautrix_telegram_homeserver_async_media: false
 matrix_mautrix_telegram_appservice_address: 'http://matrix-mautrix-telegram:8080'
-matrix_mautrix_telegram_appservice_public_external: '{{ matrix_mautrix_telegram_scheme }}://{{ matrix_mautrix_telegram_hostname }}{{ matrix_mautrix_telegram_public_endpoint }}'
-
-matrix_mautrix_telegram_appservice_bot_username: telegrambot
 
 matrix_mautrix_telegram_msc4190_enabled: "{{ matrix_bridges_msc4190_enabled }}"
+matrix_mautrix_telegram_self_sign_enabled: "{{ matrix_bridges_self_sign_enabled }}"
 
-# Specifies the default log level for all bridge loggers.
+matrix_mautrix_telegram_command_prefix: "!tg"
-matrix_mautrix_telegram_logging_level: WARNING
 
-# Whether or not created rooms should have federation enabled.
+# Get your own API keys at https://my.telegram.org/apps
-# If false, created portal rooms will never be federated.
+matrix_mautrix_telegram_api_id: ''
-matrix_mautrix_telegram_federate_rooms: true
+matrix_mautrix_telegram_api_hash: ''
-
-# Controls whether the matrix-mautrix-telegram container exposes its HTTP port (tcp/8080 in the container).
-#
-# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:9006"), or empty string to not expose.
-matrix_mautrix_telegram_container_http_host_bind_port: ''
 
 matrix_mautrix_telegram_container_network: ""
 
@@ -116,16 +71,6 @@ matrix_mautrix_telegram_container_labels_traefik_docker_network: "{{ matrix_maut
 matrix_mautrix_telegram_container_labels_traefik_entrypoints: web-secure
 matrix_mautrix_telegram_container_labels_traefik_tls_certResolver: default  # noqa var-naming
 
-# Controls whether labels will be added that expose mautrix-telegram's public endpoint
-matrix_mautrix_telegram_container_labels_public_endpoint_enabled: "{{ matrix_mautrix_telegram_appservice_public_enabled }}"
-matrix_mautrix_telegram_container_labels_public_endpoint_hostname: "{{ matrix_mautrix_telegram_hostname }}"
-matrix_mautrix_telegram_container_labels_public_endpoint_path_prefix: "{{ matrix_mautrix_telegram_path_prefix }}"
-matrix_mautrix_telegram_container_labels_public_endpoint_traefik_rule: "Host(`{{ matrix_mautrix_telegram_container_labels_public_endpoint_hostname }}`) && PathPrefix(`{{ matrix_mautrix_telegram_container_labels_public_endpoint_path_prefix }}`)"
-matrix_mautrix_telegram_container_labels_public_endpoint_traefik_priority: 0
-matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints: "{{ matrix_mautrix_telegram_container_labels_traefik_entrypoints }}"
-matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls: "{{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints != 'web' }}"
-matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls_certResolver: "{{ matrix_mautrix_telegram_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
-
 # Controls whether labels will be added that expose mautrix-telegram's metrics
 matrix_mautrix_telegram_container_labels_metrics_enabled: "{{ matrix_mautrix_telegram_metrics_enabled and matrix_mautrix_telegram_metrics_proxying_enabled }}"
 matrix_mautrix_telegram_container_labels_metrics_traefik_rule: "Host(`{{ matrix_mautrix_telegram_metrics_proxying_hostname }}`) && PathPrefix(`{{ matrix_mautrix_telegram_metrics_proxying_path_prefix }}`)"
@@ -161,14 +106,22 @@ matrix_mautrix_telegram_systemd_wanted_services_list: []
 matrix_mautrix_telegram_appservice_token: ''
 matrix_mautrix_telegram_homeserver_token: ''
 
-matrix_mautrix_telegram_provisioning_shared_secret: disable
+matrix_mautrix_telegram_appservice_bot_username: telegrambot
+
+# Minimum severity of journal log messages.
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_telegram_logging_level: 'warn'
+
+# Whether or not created rooms should have federation enabled.
+# If false, created portal rooms will never be federated.
+matrix_mautrix_telegram_federate_rooms: true
 
 # Whether or not metrics endpoint should be enabled.
 # Enabling them is usually enough for a local (in-container) Prometheus to consume them.
 # If metrics need to be consumed by another (external) Prometheus server, consider exposing them via `matrix_mautrix_telegram_metrics_proxying_enabled`.
 matrix_mautrix_telegram_metrics_enabled: false
 
-# Controls whether metrics should be exposed on a public URL.
+# Controls whether metrics should be proxied (exposed) on a public URL
 matrix_mautrix_telegram_metrics_proxying_enabled: false
 matrix_mautrix_telegram_metrics_proxying_hostname: ''
 matrix_mautrix_telegram_metrics_proxying_path_prefix: ''
@@ -190,21 +143,71 @@ matrix_mautrix_telegram_database_password: 'some-password'
 matrix_mautrix_telegram_database_hostname: ''
 matrix_mautrix_telegram_database_port: 5432
 matrix_mautrix_telegram_database_name: 'matrix_mautrix_telegram'
+matrix_mautrix_telegram_database_sslmode: disable
 
-matrix_mautrix_telegram_database_connection_string: 'postgres://{{ matrix_mautrix_telegram_database_username }}:{{ matrix_mautrix_telegram_database_password }}@{{ matrix_mautrix_telegram_database_hostname }}:{{ matrix_mautrix_telegram_database_port }}/{{ matrix_mautrix_telegram_database_name }}'
+matrix_mautrix_telegram_database_connection_string: 'postgresql://{{ matrix_mautrix_telegram_database_username }}:{{ matrix_mautrix_telegram_database_password }}@{{ matrix_mautrix_telegram_database_hostname }}:{{ matrix_mautrix_telegram_database_port }}/{{ matrix_mautrix_telegram_database_name }}?sslmode={{ matrix_mautrix_telegram_database_sslmode }}'
 
-matrix_mautrix_telegram_appservice_database: "{{
+matrix_mautrix_telegram_appservice_database_type: "{{
 	{
-		'sqlite': ('sqlite:///' + matrix_mautrix_telegram_sqlite_database_path_in_container),
+		'sqlite': 'sqlite3-fk-wal',
+		'postgres':'postgres',
+	}[matrix_mautrix_telegram_database_engine]
+}}"
+
+matrix_mautrix_telegram_appservice_database_uri: "{{
+	{
+		'sqlite': matrix_mautrix_telegram_sqlite_database_path_in_container,
 		'postgres': matrix_mautrix_telegram_database_connection_string,
 	}[matrix_mautrix_telegram_database_engine]
 }}"
 
-matrix_mautrix_telegram_bridge_login_shared_secret_map: "{{ matrix_mautrix_telegram_bridge_login_shared_secret_map_auto | combine(matrix_mautrix_telegram_bridge_login_shared_secret_map_custom) }}"
+matrix_mautrix_telegram_double_puppet_secrets: "{{ matrix_mautrix_telegram_double_puppet_secrets_auto | combine(matrix_mautrix_telegram_double_puppet_secrets_custom) }}"
-matrix_mautrix_telegram_bridge_login_shared_secret_map_auto: {}
+matrix_mautrix_telegram_double_puppet_secrets_auto: {}
-matrix_mautrix_telegram_bridge_login_shared_secret_map_custom: {}
+matrix_mautrix_telegram_double_puppet_secrets_custom: {}
 
-# Default configuration template which covers the generic use case.
+# Displayname template for Telegram users.
+# Available variables:
+#   {{ .FullName }}  - the full name of the Telegram user
+#   {{ .FirstName }} - the first name of the Telegram user
+#   {{ .LastName }}  - the last name of the Telegram user
+#   {{ .Username }}  - the primary username of the Telegram user, if the user has one
+#   {{ .UserID }}    - the internal user ID of the Telegram user
+#   {{ .Deleted }}   - true if the user has been deleted, false otherwise
+matrix_mautrix_telegram_network_displayname_template: '{% raw %}{{ if .Deleted }}Deleted account {{ .UserID }}{{ else }}{{ .FullName }}{{ end }}{% endraw %}'
+
+# Enable End-to-bridge encryption
+matrix_mautrix_telegram_bridge_encryption_allow: "{{ matrix_bridges_encryption_enabled }}"
+matrix_mautrix_telegram_bridge_encryption_default: "{{ matrix_bridges_encryption_default }}"
+matrix_mautrix_telegram_bridge_encryption_require: false
+matrix_mautrix_telegram_bridge_encryption_key_sharing_allow: "{{ matrix_mautrix_telegram_bridge_encryption_allow }}"
+# This pickle key value is backward-compatible with the legacy (Python) bridge.
+# See: https://mau.dev/mautrix/telegram/-/blob/v0.2604.0/cmd/mautrix-telegram/legacymigrate.go
+matrix_mautrix_telegram_bridge_encryption_pickle_key: mautrix.bridge.e2ee
+
+matrix_mautrix_telegram_bridge_personal_filtering_spaces: true
+
+matrix_mautrix_telegram_provisioning_shared_secret: ''
+matrix_mautrix_telegram_public_media_signing_key: ''
+
+matrix_mautrix_telegram_bridge_permissions: |
+  {{
+    {'*': 'relay', matrix_mautrix_telegram_homeserver_domain: 'user'}
+    | combine({matrix_admin: 'admin'} if matrix_admin else {})
+  }}
+
+# Enable bridge relay functionality
+matrix_mautrix_telegram_bridge_relay_enabled: "{{ matrix_bridges_relay_enabled }}"
+
+# Only allow admins on this home server to set themselves as a relay user
+matrix_mautrix_telegram_bridge_relay_admin_only: true
+
+# List of user login IDs which anyone can set as a relay, as long as the relay user is in the room.
+matrix_mautrix_telegram_bridge_relay_default_relays: []
+
+# Controls whether to do backfilling at all.
+matrix_mautrix_telegram_backfill_enabled: true
+
+# Default mautrix-telegram 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_mautrix_telegram_configuration_extension_yaml`)
@@ -228,37 +231,24 @@ matrix_mautrix_telegram_configuration: "{{ matrix_mautrix_telegram_configuration
 
 matrix_mautrix_telegram_registration_yaml: |
   id: telegram
+  url: {{ matrix_mautrix_telegram_appservice_address }}
   as_token: "{{ matrix_mautrix_telegram_appservice_token }}"
   hs_token: "{{ matrix_mautrix_telegram_homeserver_token }}"
+  # See https://github.com/mautrix/signal/issues/43
+  sender_localpart: _bot_{{ matrix_mautrix_telegram_appservice_bot_username }}
+  rate_limited: false
   namespaces:
       users:
       - exclusive: true
-        regex: '^@{{ matrix_mautrix_telegram_username_template | replace('{userid}', '.+') }}:{{ matrix_mautrix_telegram_homeserver_domain | regex_escape }}$'
+        regex: '^@telegram_.+:{{ matrix_mautrix_telegram_homeserver_domain | regex_escape }}$'
       - exclusive: true
         regex: '^@{{ matrix_mautrix_telegram_appservice_bot_username | regex_escape }}:{{ matrix_mautrix_telegram_homeserver_domain | regex_escape }}$'
-      aliases:
-      - exclusive: true
-        regex: '^#{{ matrix_mautrix_telegram_alias_template | replace('{groupname}', '.+') }}:{{ matrix_mautrix_telegram_homeserver_domain | regex_escape }}$'
-  # See https://github.com/mautrix/signal/issues/43
-  sender_localpart: _bot_{{ matrix_mautrix_telegram_appservice_bot_username }}
-  url: {{ matrix_mautrix_telegram_appservice_address }}
-  rate_limited: false
   de.sorunome.msc2409.push_ephemeral: true
   receive_ephemeral: true
   io.element.msc4190: {{ matrix_mautrix_telegram_msc4190_enabled | to_json }}
 
 matrix_mautrix_telegram_registration: "{{ matrix_mautrix_telegram_registration_yaml | from_yaml }}"
 
-# Templates for defining MXID's and displaynames for users and rooms.
-matrix_mautrix_telegram_username_template: 'telegram_{userid}'
-matrix_mautrix_telegram_alias_template: 'telegram_{groupname}'
-matrix_mautrix_telegram_displayname_template: '{displayname} (Telegram)'
-
-# Enable End-to-bridge encryption
-matrix_mautrix_telegram_bridge_encryption_allow: "{{ matrix_bridges_encryption_enabled }}"
-matrix_mautrix_telegram_bridge_encryption_default: "{{ matrix_bridges_encryption_default }}"
-matrix_mautrix_telegram_bridge_encryption_key_sharing_allow: "{{ matrix_mautrix_telegram_bridge_encryption_allow }}"
-
 # matrix_mautrix_telegram_restart_necessary controls whether the service
 # will be restarted (when true) or merely started (when false) by the
 # systemd service manager role (when conditional restart is enabled).

roles/custom/matrix-bridge-mautrix-telegram/tasks/setup_install.yml

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2018 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2018 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2018 Hugues Morisset
 # SPDX-FileCopyrightText: 2019 Aaron Raimist
 # SPDX-FileCopyrightText: 2019 Dan Arnfield
@@ -20,6 +20,40 @@
 - ansible.builtin.set_fact:
     matrix_mautrix_telegram_migration_requires_restart: false
 
+# The legacy Python bridge stored its SQLite DB at `{base_path}/mautrix-telegram.db` (the role's
+# root). Later, we started relocating it to `{base_path}/data/mautrix-telegram.db`. The sqlite→
+# postgres migration below only knows about the new path, so if the DB is still at the legacy
+# location, move it to the new location first — otherwise users who follow the changelog and
+# switch to Postgres wouldn't actually get their data imported before the service starts.
+- name: Check if a legacy-location SQLite database exists
+  ansible.builtin.stat:
+    path: "{{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db"
+  register: matrix_mautrix_telegram_stat_database_legacy_location
+
+- when: matrix_mautrix_telegram_stat_database_legacy_location.stat.exists | bool
+  block:
+    - name: Ensure matrix-mautrix-telegram.service is stopped before relocating legacy SQLite DB
+      ansible.builtin.service:
+        name: matrix-mautrix-telegram
+        state: stopped
+        enabled: false
+        daemon_reload: true
+      failed_when: false
+
+    - name: Ensure data directory exists for legacy SQLite DB relocation
+      ansible.builtin.file:
+        path: "{{ matrix_mautrix_telegram_data_path }}"
+        state: directory
+        mode: '0750'
+        owner: "{{ matrix_user_name }}"
+        group: "{{ matrix_group_name }}"
+
+    - name: (Data relocation) Move mautrix-telegram SQLite DB from legacy location to data directory
+      ansible.builtin.command:
+        cmd: "mv {{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db {{ matrix_mautrix_telegram_data_path }}/mautrix-telegram.db"
+        creates: "{{ matrix_mautrix_telegram_data_path }}/mautrix-telegram.db"
+        removes: "{{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db"
+
 - when: "matrix_mautrix_telegram_database_engine == 'postgres'"
   block:
     - name: Check if an SQLite database already exists
@@ -40,6 +74,7 @@
               engine_variable_name: 'matrix_mautrix_telegram_database_engine'
               engine_old: 'sqlite'
               systemd_services_to_stop: ['matrix-mautrix-telegram.service']
+              pgloader_options: ['--with "quote identifiers"']
 
         - ansible.builtin.set_fact:
             matrix_mautrix_telegram_migration_requires_restart: true
@@ -70,41 +105,18 @@
   delay: "{{ devture_playbook_help_container_retries_delay }}"
   until: matrix_mautrix_telegram_container_image_pull_result is not failed
 
-- name: Ensure lottieconverter is present when self-building
+- name: Ensure Mautrix Telegram repository is present on self-build
   ansible.builtin.git:
-    repo: "{{ matrix_mautrix_telegram_lottieconverter_container_repo }}"
+    repo: "{{ matrix_mautrix_telegram_container_image_self_build_repo }}"
-    version: "{{ matrix_mautrix_telegram_lottieconverter_container_repo_version }}"
-    dest: "{{ matrix_mautrix_telegram_lottieconverter_container_src_files_path }}"
-    force: "yes"
-  become: true
-  become_user: "{{ matrix_user_name }}"
-  register: matrix_mautrix_telegram_lottieconverter_git_pull_results
-  when: "matrix_mautrix_telegram_lottieconverter_container_image_self_build | bool and matrix_mautrix_telegram_container_image_self_build | bool"
-
-- name: Ensure lottieconverter Docker image is built
-  community.docker.docker_image:
-    name: "{{ matrix_mautrix_telegram_lottieconverter_container_image }}"
-    source: build
-    force_source: "{{ matrix_mautrix_telegram_lottieconverter_git_pull_results.changed if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
-    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_mautrix_telegram_lottieconverter_git_pull_results.changed }}"
-    build:
-      dockerfile: Dockerfile
-      path: "{{ matrix_mautrix_telegram_lottieconverter_container_src_files_path }}"
-      pull: true
-  when: "matrix_mautrix_telegram_lottieconverter_container_image_self_build | bool and matrix_mautrix_telegram_lottieconverter_git_pull_results.changed and matrix_mautrix_telegram_container_image_self_build | bool"
-
-- name: Ensure matrix-mautrix-telegram repository is present when self-building
-  ansible.builtin.git:
-    repo: "{{ matrix_mautrix_telegram_container_repo }}"
-    version: "{{ matrix_mautrix_telegram_container_repo_version }}"
     dest: "{{ matrix_mautrix_telegram_container_src_files_path }}"
+    version: "{{ matrix_mautrix_telegram_container_image_self_build_branch }}"
     force: "yes"
   become: true
   become_user: "{{ matrix_user_name }}"
   register: matrix_mautrix_telegram_git_pull_results
   when: "matrix_mautrix_telegram_container_image_self_build | bool"
 
-- name: Ensure matrix-mautrix-telegram Docker image is built
+- name: Ensure Mautrix Telegram Docker image is built
   community.docker.docker_image:
     name: "{{ matrix_mautrix_telegram_container_image }}"
     source: build
@@ -113,31 +125,8 @@
     build:
       dockerfile: Dockerfile
       path: "{{ matrix_mautrix_telegram_container_src_files_path }}"
-      pull: "{{ not matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch | bool }}"
+      pull: true
-      args:
+  when: "matrix_mautrix_telegram_container_image_self_build | bool"
-        TARGETARCH: ""
-  when: "matrix_mautrix_telegram_container_image_self_build | bool and matrix_mautrix_telegram_git_pull_results.changed"
-
-- name: Check if an old database file already exists
-  ansible.builtin.stat:
-    path: "{{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db"
-  register: matrix_mautrix_telegram_stat_database
-
-- name: (Data relocation) Ensure matrix-mautrix-telegram.service is stopped
-  ansible.builtin.service:
-    name: matrix-mautrix-telegram
-    state: stopped
-    enabled: false
-    daemon_reload: true
-  failed_when: false
-  when: "matrix_mautrix_telegram_stat_database.stat.exists"
-
-- name: (Data relocation) Move mautrix-telegram database file to ./data directory
-  ansible.builtin.command:
-    cmd: "mv {{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db {{ matrix_mautrix_telegram_data_path }}/mautrix-telegram.db"
-    creates: "{{ matrix_mautrix_telegram_data_path }}/mautrix-telegram.db"
-    removes: "{{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db"
-  when: "matrix_mautrix_telegram_stat_database.stat.exists"
 
 - name: Ensure mautrix-telegram config.yaml installed
   ansible.builtin.copy:

roles/custom/matrix-bridge-mautrix-telegram/tasks/validate_config.yml

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2019 - 2026 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2022 MDAD project contributors
 # SPDX-FileCopyrightText: 2025 Suguru Hirahara
 #
@@ -13,34 +13,72 @@
       Please rename the variable (`{{ item.old }}` -> `{{ item.new }}`) on your configuration file (vars.yml).
   when: "lookup('ansible.builtin.varnames', ('^' + item.old + '$'), wantlist=True) | length > 0"
   with_items:
-    - {'old': 'matrix_mautrix_telegram_container_exposed_port_number', 'new': '<superseded by matrix_mautrix_telegram_container_http_host_bind_port>'}
+    - {'old': 'matrix_mautrix_telegram_container_exposed_port_number', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
     - {'old': 'matrix_mautrix_telegram_container_self_build', 'new': 'matrix_mautrix_telegram_container_image_self_build'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_self_build', 'new': 'matrix_mautrix_telegram_container_image_self_build'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_self_build_mask_arch', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch'}
     - {'old': 'matrix_mautrix_telegram_login_shared_secret', 'new': '<removed>'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_name_prefix', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix'}
     - {'old': 'matrix_mautrix_telegram_docker_image_name_prefix', 'new': 'matrix_mautrix_telegram_container_image_registry_prefix'}
-    - {'old': 'matrix_telegram_lottieconverter_container_image_self_build', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build'}
+    - {'old': 'matrix_mautrix_telegram_docker_repo', 'new': 'matrix_mautrix_telegram_container_image_self_build_repo'}
-    - {'old': 'matrix_telegram_lottieconverter_container_image_self_build_mask_arch', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch'}
+    - {'old': 'matrix_mautrix_telegram_docker_repo_version', 'new': 'matrix_mautrix_telegram_container_image_self_build_branch'}
-    - {'old': 'matrix_telegram_lottieconverter_docker_repo', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo'}
-    - {'old': 'matrix_telegram_lottieconverter_docker_repo_version', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo_version'}
-    - {'old': 'matrix_telegram_lottieconverter_docker_src_files_path', 'new': 'matrix_mautrix_telegram_lottieconverter_container_src_files_path'}
-    - {'old': 'matrix_telegram_lottieconverter_docker_image', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image'}
-    - {'old': 'matrix_mautrix_telegram_docker_repo', 'new': 'matrix_mautrix_telegram_container_repo'}
-    - {'old': 'matrix_mautrix_telegram_docker_repo_version', 'new': 'matrix_mautrix_telegram_container_repo_version'}
     - {'old': 'matrix_mautrix_telegram_docker_src_files_path', 'new': 'matrix_mautrix_telegram_container_src_files_path'}
     - {'old': 'matrix_mautrix_telegram_docker_image', 'new': 'matrix_mautrix_telegram_container_image'}
     - {'old': 'matrix_mautrix_telegram_docker_image_force_pull', 'new': 'matrix_mautrix_telegram_container_image_force_pull'}
     - {'old': 'matrix_mautrix_telegram_docker_image_registry_prefix', 'new': 'matrix_mautrix_telegram_container_image_registry_prefix'}
     - {'old': 'matrix_mautrix_telegram_docker_image_registry_prefix_upstream', 'new': 'matrix_mautrix_telegram_container_image_registry_prefix_upstream'}
     - {'old': 'matrix_mautrix_telegram_docker_image_registry_prefix_upstream_default', 'new': 'matrix_mautrix_telegram_container_image_registry_prefix_upstream_default'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image'}
+    - {'old': 'matrix_mautrix_telegram_container_repo', 'new': 'matrix_mautrix_telegram_container_image_self_build_repo'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix'}
+    - {'old': 'matrix_mautrix_telegram_container_repo_version', 'new': 'matrix_mautrix_telegram_container_image_self_build_branch'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream'}
+    # Variables removed in the bridgev2 (Go) rewrite — mautrix-telegram no longer has a Python runtime,
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream_default', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default'}
+    # a separate lottieconverter container or a web-based login endpoint.
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo'}
+    - {'old': 'matrix_mautrix_telegram_scheme', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo_version', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo_version'}
+    - {'old': 'matrix_mautrix_telegram_hostname', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
-    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_src_files_path', 'new': 'matrix_mautrix_telegram_lottieconverter_container_src_files_path'}
+    - {'old': 'matrix_mautrix_telegram_path_prefix', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_public_endpoint', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_appservice_public_enabled', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_appservice_public_external', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_enabled', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_hostname', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_path_prefix', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_traefik_rule', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_traefik_priority', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls_certResolver', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_container_http_host_bind_port', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
+    - {'old': 'matrix_mautrix_telegram_filter_mode', 'new': '<removed (not available in the bridgev2 rewrite of mautrix-telegram)>'}
+    - {'old': 'matrix_mautrix_telegram_bot_token', 'new': '<removed; the old-style relaybot is gone — use the common bridge relay mode (matrix_mautrix_telegram_bridge_relay_enabled) instead>'}
+    - {'old': 'matrix_mautrix_telegram_bridge_login_shared_secret_map', 'new': '<superseded by matrix_mautrix_telegram_double_puppet_secrets>'}
+    - {'old': 'matrix_mautrix_telegram_bridge_login_shared_secret_map_auto', 'new': '<superseded by matrix_mautrix_telegram_double_puppet_secrets_auto>'}
+    - {'old': 'matrix_mautrix_telegram_bridge_login_shared_secret_map_custom', 'new': '<superseded by matrix_mautrix_telegram_double_puppet_secrets_custom>'}
+    - {'old': 'matrix_mautrix_telegram_username_template', 'new': '<removed (no longer configurable via a single variable; use matrix_mautrix_telegram_configuration_extension_yaml if needed)>'}
+    - {'old': 'matrix_mautrix_telegram_alias_template', 'new': '<removed (room aliases are no longer created by the bridgev2 rewrite of mautrix-telegram)>'}
+    - {'old': 'matrix_mautrix_telegram_displayname_template', 'new': '<superseded by matrix_mautrix_telegram_network_displayname_template (note: the syntax has changed to Go templates)>'}
+    - {'old': 'matrix_mautrix_telegram_appservice_database', 'new': '<superseded by matrix_mautrix_telegram_appservice_database_uri>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_repo', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_repo_version', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_src_files_path', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    # Historical lottieconverter aliases from before the _docker_ → _container_ rename:
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_container_self_build', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_name_prefix', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream_default', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo_version', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_mautrix_telegram_lottieconverter_docker_src_files_path', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    # Even older aliases (no `_mautrix` infix):
+    - {'old': 'matrix_telegram_lottieconverter_container_image_self_build', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_telegram_lottieconverter_container_image_self_build_mask_arch', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_telegram_lottieconverter_docker_repo', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_telegram_lottieconverter_docker_repo_version', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_telegram_lottieconverter_docker_src_files_path', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
+    - {'old': 'matrix_telegram_lottieconverter_docker_image', 'new': '<removed (lottieconverter is now bundled into the mautrix-telegram image)>'}
 
 - name: Fail if required mautrix-telegram settings not defined
   ansible.builtin.fail:
@@ -48,11 +86,8 @@
       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_mautrix_telegram_hostname', when: true}
-    - {'name': 'matrix_mautrix_telegram_path_prefix', when: true}
     - {'name': 'matrix_mautrix_telegram_api_id', when: true}
     - {'name': 'matrix_mautrix_telegram_api_hash', when: true}
-    - {'name': 'matrix_mautrix_telegram_public_endpoint', when: true}
     - {'name': 'matrix_mautrix_telegram_appservice_token', when: true}
     - {'name': 'matrix_mautrix_telegram_homeserver_address', when: true}
     - {'name': 'matrix_mautrix_telegram_homeserver_token', when: true}
@@ -60,3 +95,47 @@
     - {'name': 'matrix_mautrix_telegram_database_hostname', when: "{{ matrix_mautrix_telegram_database_engine == 'postgres' }}"}
     - {'name': 'matrix_mautrix_telegram_metrics_proxying_hostname', when: "{{ matrix_mautrix_telegram_metrics_proxying_enabled }}"}
     - {'name': 'matrix_mautrix_telegram_metrics_proxying_path_prefix', when: "{{ matrix_mautrix_telegram_metrics_proxying_enabled }}"}
+
+# Temporary workaround for an upstream SQLite legacy-migration bug in mautrix-telegram v0.2604.0.
+# See the separate task file for details; the whole file (and this include) can be deleted once
+# upstream ships a release that fixes the bug.
+- name: Guard against the upstream mautrix-telegram v0.2604.0 SQLite legacy-migration bug
+  ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config_sqlite_legacy_migration_bug.yml"
+  when:
+    - "matrix_mautrix_telegram_database_engine == 'sqlite'"
+    - "not (matrix_mautrix_telegram_bridgev2_sqlite_upgrade_confirmed | default(false) | bool)"
+
+# Bridgev2 permission values are: block, relay, commands, user, admin.
+# The old Python bridge had different levels (relaybot, user, puppeting, full, admin).
+# `user` and `admin` still exist in both but with different semantics (the new `user` is
+# equivalent to the old `full`/`puppeting`). `relaybot`, `puppeting` and `full` don't exist
+# in bridgev2 and will cause the bridge to reject its config at startup.
+#
+# We check the fully-merged configuration (not just `matrix_mautrix_telegram_bridge_permissions`)
+# because users commonly override permissions via `matrix_mautrix_telegram_configuration_extension_yaml`,
+# and those overrides would otherwise slip through validation.
+- name: Fail if bridge permissions still reference legacy Python-bridge permission levels
+  ansible.builtin.fail:
+    msg: |-
+      Your final mautrix-telegram configuration contains a `bridge.permissions` entry with
+      value `{{ item.value }}` (for `{{ item.key }}`). This was a permission level in the legacy
+      (Python) mautrix-telegram bridge but is not valid in the bridgev2 rewrite shipped in v0.2604.0
+      — the bridge would reject this at startup.
+
+      Valid values are: `relay`, `commands`, `user`, `admin` (plus `block`).
+
+      Rough mapping from the old levels:
+
+        relaybot  -> relay
+        user      -> user (semantics changed: this now grants full puppeting, like the old `full`)
+        puppeting -> user
+        full      -> user
+        admin     -> admin
+
+      See https://docs.mau.fi/bridges/general/permissions.html and the bridge's example config
+      for details. Update either `matrix_mautrix_telegram_bridge_permissions` or the `bridge.permissions`
+      section inside `matrix_mautrix_telegram_configuration_extension_yaml` — whichever you use.
+  when: "item.value in ['relaybot', 'puppeting', 'full']"
+  loop: "{{ (matrix_mautrix_telegram_configuration.bridge.permissions | default({})) | dict2items }}"
+  loop_control:
+    label: "{{ item.key }}"

roles/custom/matrix-bridge-mautrix-telegram/tasks/validate_config_sqlite_legacy_migration_bug.yml

@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+# ###########################################################################
+# TEMPORARY — delete this file (and its include in `validate_config.yml`)
+# once upstream mautrix-telegram ships a release that fixes the SQLite
+# legacy-migration bug introduced in v0.2604.0.
+#
+# Upstream warning:
+#   "Migration of SQLite databases has a known bug. If you're upgrading a
+#    legacy bridge that uses SQLite, use the main branch or wait for the
+#    next release"
+#   — https://github.com/mautrix/telegram/releases/tag/v0.2604.0
+#
+# We specifically want to block upgrades of the *legacy* Python-bridge
+# SQLite databases; fresh bridgev2 SQLite databases (or already-migrated
+# ones) must still be allowed.
+#
+# The cheapest reliable signature of a legacy Python-bridge DB is the
+# presence of the `telethon_sessions` table (the Python bridge's
+# Telethon-session store, which upstream's legacymigrate.sql renames to
+# `telethon_sessions_old` as part of the bridgev2 migration).
+#
+# Users can bypass this via `matrix_mautrix_telegram_bridgev2_sqlite_upgrade_confirmed: true`.
+# ###########################################################################
+
+- name: Check for an existing mautrix-telegram SQLite database (legacy location)
+  ansible.builtin.stat:
+    path: "{{ matrix_mautrix_telegram_base_path }}/mautrix-telegram.db"
+  register: matrix_mautrix_telegram_sqlite_legacy_path_stat
+
+- name: Check for an existing mautrix-telegram SQLite database (data path)
+  ansible.builtin.stat:
+    path: "{{ matrix_mautrix_telegram_sqlite_database_path_local }}"
+  register: matrix_mautrix_telegram_sqlite_data_path_stat
+
+- name: Inspect SQLite database for the legacy Python-bridge schema signature
+  ansible.builtin.command:
+    argv:
+      - python3
+      - -c
+      - |
+        import sqlite3, sys
+        try:
+            conn = sqlite3.connect("file:" + sys.argv[1] + "?mode=ro", uri=True)
+            cur = conn.execute(
+                "SELECT name FROM sqlite_master "
+                "WHERE type='table' AND name='telethon_sessions'"
+            )
+            sys.exit(1 if cur.fetchone() else 0)
+        except Exception:
+            sys.exit(0)
+      - "{{ matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.path if matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.exists else matrix_mautrix_telegram_sqlite_data_path_stat.stat.path }}"
+  register: matrix_mautrix_telegram_sqlite_legacy_check
+  changed_when: false
+  failed_when: false
+  when: >-
+    matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.exists
+    or matrix_mautrix_telegram_sqlite_data_path_stat.stat.exists
+
+- name: Fail if upgrading a legacy SQLite install (upstream has a known migration bug)
+  ansible.builtin.fail:
+    msg: |-
+      A legacy Python mautrix-telegram SQLite database was detected at
+      `{{ matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.path if matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.exists else matrix_mautrix_telegram_sqlite_data_path_stat.stat.path }}`
+      (it contains the `telethon_sessions` table from the Python bridge).
+
+      Upstream mautrix-telegram v0.2604.0 has a **known bug** in the legacy SQLite
+      database migration (see the warning on the release page:
+      https://github.com/mautrix/telegram/releases/tag/v0.2604.0).
+      Running this upgrade against a legacy SQLite database is very likely to corrupt your data.
+
+      Recommended options:
+
+      1. Switch to Postgres before upgrading. If you're using the playbook-managed Postgres
+         service (`postgres_enabled: true`), just set:
+
+             matrix_mautrix_telegram_database_engine: postgres
+
+         and re-run the playbook. The playbook will migrate your SQLite data into Postgres
+         first (via pgloader), and upstream's bridgev2 migration path is known to work on
+         Postgres.
+
+      2. Wait for the next upstream mautrix-telegram release, which is expected to fix the
+         SQLite migration bug.
+
+      If you're sure you want to proceed anyway (for example because you have a separate
+      backup), you can bypass this check by setting:
+
+          matrix_mautrix_telegram_bridgev2_sqlite_upgrade_confirmed: true
+
+      in your vars.yml. Only use the override if you know what you're doing.
+  when: >-
+    (matrix_mautrix_telegram_sqlite_legacy_path_stat.stat.exists
+      or matrix_mautrix_telegram_sqlite_data_path_stat.stat.exists)
+    and (matrix_mautrix_telegram_sqlite_legacy_check.rc | default(0)) == 1

roles/custom/matrix-bridge-mautrix-telegram/templates/labels.j2

@@ -1,5 +1,5 @@
 {#
-SPDX-FileCopyrightText: 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2024 - 2026 Slavi Pantaleev
 
 SPDX-License-Identifier: AGPL-3.0-or-later
 #}
@@ -11,36 +11,7 @@ traefik.enable=true
 traefik.docker.network={{ matrix_mautrix_telegram_container_labels_traefik_docker_network }}
 {% endif %}
 
-{% if matrix_mautrix_telegram_container_labels_public_endpoint_enabled %}
+traefik.http.services.matrix-mautrix-telegram-metrics.loadbalancer.server.port=8001
-############################################################
-#                                                          #
-# Public                                                   #
-#                                                          #
-############################################################
-
-traefik.http.services.matrix-mautrix-telegram-appservice.loadbalancer.server.port=8080
-
-traefik.http.routers.matrix-mautrix-telegram-public.rule={{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_rule }}
-
-{% if matrix_mautrix_telegram_container_labels_public_endpoint_traefik_priority | int > 0 %}
-traefik.http.routers.matrix-mautrix-telegram-public.priority={{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_priority }}
-{% endif %}
-
-traefik.http.routers.matrix-mautrix-telegram-public.service=matrix-mautrix-telegram-appservice
-traefik.http.routers.matrix-mautrix-telegram-public.entrypoints={{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_entrypoints }}
-
-traefik.http.routers.matrix-mautrix-telegram-public.tls={{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls | to_json }}
-{% if matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls %}
-traefik.http.routers.matrix-mautrix-telegram-public.tls.certResolver={{ matrix_mautrix_telegram_container_labels_public_endpoint_traefik_tls_certResolver }}
-{% endif %}
-
-############################################################
-#                                                          #
-# /Public                                                  #
-#                                                          #
-############################################################
-{% endif %}
-
 
 {% if matrix_mautrix_telegram_container_labels_metrics_enabled %}
 ############################################################
@@ -49,8 +20,6 @@ traefik.http.routers.matrix-mautrix-telegram-public.tls.certResolver={{ matrix_m
 #                                                          #
 ############################################################
 
-traefik.http.services.matrix-mautrix-telegram-metrics.loadbalancer.server.port=8000
-
 {% if matrix_mautrix_telegram_container_labels_metrics_middleware_basic_auth_enabled %}
 traefik.http.middlewares.matrix-mautrix-telegram-metrics-basic-auth.basicauth.users={{ matrix_mautrix_telegram_container_labels_metrics_middleware_basic_auth_users }}
 traefik.http.routers.matrix-mautrix-telegram-metrics.middlewares=matrix-mautrix-telegram-metrics-basic-auth

roles/custom/matrix-bridge-mautrix-telegram/templates/systemd/matrix-mautrix-telegram.service.j2

@@ -23,17 +23,15 @@ ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
 			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
 			--cap-drop=ALL \
 			--network={{ matrix_mautrix_telegram_container_network }} \
-			{% if matrix_mautrix_telegram_appservice_public_enabled and matrix_mautrix_telegram_container_http_host_bind_port %}
-			-p {{ matrix_mautrix_telegram_container_http_host_bind_port }}:8080 \
-			{% endif %}
 			--mount type=bind,src={{ matrix_mautrix_telegram_config_path }},dst=/config \
 			--mount type=bind,src={{ matrix_mautrix_telegram_data_path }},dst=/data \
 			--label-file={{ matrix_mautrix_telegram_base_path }}/labels \
+			--workdir=/data \
 			{% for arg in matrix_mautrix_telegram_container_extra_arguments %}
 			{{ arg }} \
 			{% endfor %}
 			{{ matrix_mautrix_telegram_container_image }} \
-			python3 -m mautrix_telegram -c /config/config.yaml --no-update
+			/usr/bin/mautrix-telegram -c /config/config.yaml -r /config/registration.yaml --no-update
 
 {% for network in matrix_mautrix_telegram_container_additional_networks %}
 ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-mautrix-telegram

roles/custom/matrix_playbook_migration/defaults/main.yml

@@ -14,10 +14,13 @@ matrix_playbook_migration_validated_version: ''
 # The version that the playbook expects the user to have validated against.
 # This is bumped whenever a breaking change is introduced.
 # The value configured here needs to exist in `matrix_playbook_migration_breaking_changes` as well.
-matrix_playbook_migration_expected_version: "v2026.04.03.0"
+matrix_playbook_migration_expected_version: "v2026.04.24.0"
 
 # A list of breaking changes, used to inform users what changed between their validated version and the expected version.
 matrix_playbook_migration_breaking_changes:
+  - version: "v2026.04.24.0"
+    summary: "(BC Break) mautrix-telegram has been rewritten in Go (bridgev2) — the web-based login endpoint, old-style relaybot and several variables have been removed"
+    changelog_url: "https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#2026-04-24"
   - version: "v2026.04.03.0"
     summary: "(BC Break) Synapse Admin is now Ketesa — role renamed and all variables changed from matrix_synapse_admin_* to matrix_ketesa_*"
     changelog_url: "https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/CHANGELOG.md#2026-04-03"