Part of adopting a uniform naming policy for bridge variables,
where the variable prefix matches the role directory name.
The companion appservice variables defined by this role are folded
under the role prefix as well: matrix_mautrix_androidsms_* becomes
matrix_bridge_mautrix_wsproxy_androidsms_* and matrix_mautrix_imessage_*
becomes matrix_bridge_mautrix_wsproxy_imessage_*.
matrix_mautrix_signal_wsproxy_syncproxy_connection_string becomes
matrix_bridge_mautrix_wsproxy_syncproxy_connection_string, aligning it
with the sibling matrix_bridge_mautrix_wsproxy_syncproxy_* variables.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The CDN section of the federation documentation tells users to set
matrix_synapse_federation_port_enabled: false, which only works because
that recipe moves federation traffic to the client port. Followed
partially (keeping federation on the dedicated federation port behind a
fronting reverse proxy), the same line removes the federation route
entirely and breaks federation. Say so explicitly.
Fixes#4475
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The bridge could only be installed by self-building its source code,
and its upstream repository (on src.miscworks.net) has become
unreachable (the Internet Archive last saw it alive in May 2026),
making installation impossible. The bridge was also based on the
long-unmaintained node-kakao library and carried a warning that using
it may get KakaoTalk accounts banned.
The playbook catches leftover matrix_appservice_kakaotalk_* variables
and points users to the manual uninstallation instructions.
Related to #5068
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Matrix Authentication Service supports CAPTCHA protection (ReCaptcha
v2, Cloudflare Turnstile, hCaptcha) for certain operations like
self-service password registration, but configuring it required going
through matrix_authentication_service_configuration_extension_yaml.
Expose it via dedicated variables
(matrix_authentication_service_config_captcha_service, _site_key and
_secret_key), validate the service value and key presence, and document
the setup in the captcha documentation page, which so far only covered
Synapse and Dendrite.
Related to #5344
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Enabling matrix_hookshot_encryption_enabled configures the bridge side
correctly (registration flags, Valkey cache), but hookshot's encryption
also needs the homeserver to support and enable MSC2409 and MSC3202,
which are typically experimental features disabled by default. Nothing
documented that, so the resulting setup silently did not work.
Reference the MSCs in the variable's comment, and show the exact Synapse
settings in the hookshot documentation page. The playbook deliberately
does not auto-enable them: they are experimental homeserver-wide
features, and flipping them from a bridge toggle would be surprising.
Fixes#3861
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The autotuning defaults are derived from total system RAM, but every
Synapse process (the main one and each worker) applies the configured
limits independently, so worker setups multiply the theoretical
aggregate cache memory usage.
Fixes#3336
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add the two remaining hints from the official Synapse backup guide:
- never import a dump into a database that already has tables present
(at best it errors, at worst it causes subtle inconsistencies)
- when restoring a backup older than the server's current state,
truncate e2e_one_time_keys_json before starting Synapse, so used
one-time keys are not re-issued (which causes decryption errors);
our pg_dumpall-based backup commands include that table
Fixes#4004
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The docs claimed that reverse-proxying "or simply a 302 redirect" needs
no CORS headers. That is only true for reverse-proxying: browsers apply
CORS checks to every response in a redirect chain, so a redirect
response itself must also carry Access-Control-Allow-Origin, otherwise
web clients fail even though the final destination sets the header.
Fixes#4650
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The wildcard certificate examples attached tls.domains labels to a
router named matrix-synapse-federation-api, but the Synapse role
actually names it matrix-synapse-public-federation-api (see
templates/synapse/labels.j2), so the documented labels matched nothing
and the certificate configuration silently did not apply.
Fixes#3129
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The import-synapse-media-store task synchronizes the media store with
ansible.posix.synchronize delegated to the server itself, which requires
the rsync binary on the server. Nothing in the playbook installs it, so
the import failed on minimal systems with "Failed to find required
executable rsync". Document the prerequisite.
Fixes#2551
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Caddy evaluates directives according to its own fixed directive order,
not their order in the Caddyfile. redir runs before reverse_proxy, so a
redirect elsewhere in the same site block silently shadows the
/.well-known/matrix reverse-proxying. Add a note and a handle-block
example that enforces the intended priority.
Fixes#1080
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- add SPDX licensing information for REUSE compliance
- drop the JSONC comment from devcontainer.json, keeping it strict JSON
(as required by the check-json pre-commit hook)
- bump the base image to the current ghcr.io/devture/ansible release
- mention the dev container in docs/ansible.md
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Running `just add-inventory-host example.com 1.2.3.4` (or
`make add-inventory-host domain=example.com ip=1.2.3.4`) adds a new
host to the inventory, creating inventory/hosts and
inventory/host_vars/matrix.DOMAIN/vars.yml from the example files,
with strong secrets generated automatically.
Existing configuration is never overwritten. The command refuses to
run if the host is already in the inventory, so it can also be used
for adding more hosts later.
Based on the idea proposed in
https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/4682 by @Ser5
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds optional support for running the playbook on Synology DSM 7+, detected
automatically via /etc/synoinfo.conf so that non-Synology hosts are unaffected.
Includes DSM-native user/group management (synouser/synogroup), a requests
version constraint for Docker SDK compatibility, and a boot-fix service that
re-shares the volume mount and starts matrix services skipped by DSM's boot
ordering. The shared-mount volume path is configurable via
matrix_base_synology_volume_path, and the make-shared step only runs when the
volume is not already shared.
Co-authored-by: CKSit <sitchiuki@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a "Expose the bridge's API" section to the common mautrix bridges
documentation page (covering the /bridges/<bridge> path, the
/.well-known/matrix/mautrix auto-discovery file, how to disable it, and
the custom-bridges hook), plus a CHANGELOG entry announcing the feature.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the matrix-rustpush-bridge role, a Matrix <-> iMessage bridge built
on the mautrix-go bridgev2 framework using RustPush (OpenBubbles backend).
Unlike the existing mautrix-imessage/wsproxy bridge, it talks directly to
Apple's push notification service, so it needs neither a running Mac nor a
wsproxy on the homeserver. Each user supplies a hardware key extracted from a
Mac through the bridge bot's login flow.
The bridge uses its own bot username and puppet namespace (rustpushbot,
rustpush_*) so it does not collide with the wsproxy iMessage bridge.
This bridge is in early development and may have stability issues.
LiveKit v1.12.0 tightens TURN security: credentials now carry a TTL,
and TURN no longer relays to restricted peer CIDRs by default. The
role defaults match upstream's secure defaults and are appropriate
for typical playbook deployments.
Bumps the migration-validation gate accordingly so users are pointed
at the CHANGELOG entry on next run.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This release adds opt-in server-level enforcement of MSC4284 policy
servers via two new `[global]` keys: `enable_policy_servers` and
`policy_server_request_timeout`. Surface both as Ansible variables
matching tuwunel's upstream defaults (off, 5s timeout) and refresh the
docs section that previously claimed MSC4284 needed no playbook
configuration.
Closes https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/5213.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The former conduwuit maintainer (@x86pup, formerly @girlbossceo)
clarified in the PR thread that they endorse Tuwunel as conduwuit's
successor, and the archived conduwuit repo's README points there too.
Update the migration section in the conduwuit doc and the Tuwunel
CHANGELOG entry to reflect this with attribution.
Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/5200.
Previously only Continuwuity was offered as a migration path. Tuwunel
is a fork of conduwuit which reads the database directly via the new
`tuwunel-migrate-from-conduwuit` tag, so it deserves a parallel entry.
Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/5200.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tuwunel is a Matrix homeserver maintained by the matrix-construct
organisation. See https://matrix-construct.github.io/tuwunel/.
The rendered TOML emits only keys exposed as Ansible variables; the
rest fall back to tuwunel's upstream defaults. Anything not surfaced
can be set via the TUWUNEL_* env extension or by overriding the
template path.
Popular features Tuwunel adds variables for:
- OAuth2/OIDC identity providers (a list of `[[global.identity_provider]]`
blocks; brand-aware defaults for Google, GitHub, Keycloak, MAS, etc)
- LDAP and JWT authentication
- Media storage providers (native local and S3 with multipart upload)
- RocksDB tuning (compression, direct_io, parallelism, online backups)
- Native TLS dual-protocol mode
- Blurhashing, Sentry crash reporting
Auto-wired from existing playbook globals: well-known client URL,
TURN/coturn, MatrixRTC LiveKit URL, federation.
The `tuwunel-migrate-from-conduwuit` tag performs a binary-swap
migration. Migration from any other Conduit derivative is unsupported
and would corrupt the database.
Signed-off-by: Jason Volk <jason@zemos.net>
Sentence-case the heading to match the rest of the file, fix a broken
"appservice mode](url)(Draupnir for all)" link by folding the
parenthetical into the link text, hyphenate "non-release tag" and
"force-restart", correct "a update" -> "an update", and reword "work
perfectly" to the more accurate "work correctly".
Follow-up to 75f097e55 (#5187).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Add Matrix <-> Meshtastic bridge (meshtastic-matrix-relay)
Vendors the meshtastic-matrix-relay (mmrelay) role into roles/custom/
following the conventions used by other bridge roles.
Co-authored-by: luschmar <90399580+luschmar@users.noreply.github.com>
* Add docs and CHANGELOG entry for Matrix <-> Meshtastic bridge
Co-authored-by: luschmar <90399580+luschmar@users.noreply.github.com>
---------
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
When fronting the playbook's integrated Traefik reverse-proxy with
another reverse-proxy (e.g. nginx), WebSocket traffic needs to be
forwarded to LiveKit Server at the `/livekit-server/` path for Matrix
RTC calls to work.
Adds a `/livekit-server/` location block to the nginx reverse-proxy
example, a section to the Matrix RTC docs explaining the requirement,
and cross-links between the two.
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>
Slavi Pantaleev
jasonlaguidice
Aine
Suguru Hirahara
cksit
Aine
c-bg
Suguru Hirahara
Catalan Lover
Jason Volk
luschmar
thigg
QEDeD