cqrenet/matrix-docker-ansible-deploy
3
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2026-04-25 01:47:35 +00:00
Code Issues Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Slavi Pantaleev
2026-04-24 08:43:57 +03:00
parent ce0c194cd3
commit 5b7a1c2a6c
12 changed files with 854 additions and 881 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 }}"
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 }}"
repo: "{{ matrix_mautrix_telegram_container_image_self_build_repo }}"
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 }}"
args:
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"
pull: true
when: "matrix_mautrix_telegram_container_image_self_build | bool"
- name: Ensure mautrix-telegram config.yaml installed
ansible.builtin.copy:

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

@@ -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_telegram_lottieconverter_container_image_self_build_mask_arch', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_self_build_mask_arch'}
- {'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_repo', 'new': 'matrix_mautrix_telegram_container_image_self_build_repo'}
- {'old': 'matrix_mautrix_telegram_docker_repo_version', 'new': 'matrix_mautrix_telegram_container_image_self_build_branch'}
- {'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_lottieconverter_docker_image_registry_prefix', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix'}
- {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream'}
- {'old': 'matrix_mautrix_telegram_lottieconverter_docker_image_registry_prefix_upstream_default', 'new': 'matrix_mautrix_telegram_lottieconverter_container_image_registry_prefix_upstream_default'}
- {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo'}
- {'old': 'matrix_mautrix_telegram_lottieconverter_docker_repo_version', 'new': 'matrix_mautrix_telegram_lottieconverter_container_repo_version'}
- {'old': 'matrix_mautrix_telegram_lottieconverter_docker_src_files_path', 'new': 'matrix_mautrix_telegram_lottieconverter_container_src_files_path'}
- {'old': 'matrix_mautrix_telegram_container_repo', 'new': 'matrix_mautrix_telegram_container_image_self_build_repo'}
- {'old': 'matrix_mautrix_telegram_container_repo_version', 'new': 'matrix_mautrix_telegram_container_image_self_build_branch'}
# Variables removed in the bridgev2 (Go) rewrite — mautrix-telegram no longer has a Python runtime,
# a separate lottieconverter container or a web-based login endpoint.
- {'old': 'matrix_mautrix_telegram_scheme', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
- {'old': 'matrix_mautrix_telegram_hostname', 'new': '<removed (the bridge no longer has a public web-based login endpoint)>'}
- {'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 }}"

99
roles/custom/matrix-bridge-mautrix-telegram/tasks/validate_config_sqlite_legacy_migration_bug.yml Normal file
View File

@@ -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