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>

The new version adds livekit_server_config_rtc_ips_includes and
livekit_server_config_rtc_ips_excludes variables, controlling LiveKit's
rtc.ips.includes/excludes CIDR filters for RTC IP addresses.

Related to #4958

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>

etherpad_base_url always ends with a trailing slash, and the playbook
passed it verbatim to jitsi_etherpad_base, which the Jitsi role appends
path segments to (e.g. /p/). The generated Jitsi configuration therefore
contained URLs like https://etherpad.example.com//p/, which can 404
depending on the web server. Strip trailing slashes when wiring.

Fixes #3471

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The new role release splits grafana_dashboard_download_urls into
default/auto/custom components. Wire the playbook's automatic dashboard
list via the auto component, so users can add their own dashboards
through grafana_dashboard_download_urls_custom without clobbering it.

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>

Element Web redesigned its welcome page into a built-in component
(element-hq/element-web#33211, first released in spring 2026) and no
longer falls back to loading welcome.html. The custom page the playbook
installed had therefore silently stopped having any effect, and it was a
fork of an upstream file that upstream has deleted (its button icon
assets are already missing from current Element Web builds).

Remove the welcome.html shipping and the variables that only applied to
it (matrix_client_element_welcome_headline, _welcome_text,
_welcome_logo_link, _page_template_welcome_path), rejecting them in
validate_config.yml with pointers to the alternatives. Logo and
background customization keep working through Element Web's branding
options, which the new welcome page still honors. A fully custom page
can be self-hosted and wired via embedded_pages.welcome_url.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Synapse only generates thumbnails of local media at upload time (unless
dynamic_thumbnails is enabled, which the playbook does not do) and no
tooling exists to regenerate them, so restoring a backup left all
previously uploaded local images without thumbnails permanently. The
official Synapse backup guide recommends backing this directory up.

Related to #4004.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The configuration template only rendered a datastore when its for_kinds
list was non-empty, even though the inline documentation (matching
upstream's) describes forKinds: [] as the way to make a datastore
readonly. That made the documented migration scenario impossible: moving
media between the file and s3 datastores while keeping the old one
readable.

Introduce matrix_media_repo_datastore_file_enabled and
matrix_media_repo_datastore_s3_enabled, which default to the previous
kinds-based behavior. A readonly datastore is now expressed by enabling
the datastore explicitly while assigning it no kinds.

Fixes #4303

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

synapse-usage-exporter is self-built by default (no upstream image is
published), so every user enabling it runs the git clone/update task. A
docker-src checkout whose files are owned by a different user (e.g. left
behind by an earlier clone) made that task fail: either with a
permission error, or with git's dubious-ownership protection, which
ignores the repository's own configuration and surfaces as a confusing
"'origin' does not appear to be a git repository" error.

Ensure the checkout's ownership recursively before updating it, and mark
the path as a safe.directory for the git invocation itself (via
GIT_CONFIG_* environment variables), so the ownership check cannot
misfire regardless of which user git effectively runs as.

Fixes #5065

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 user-namespace regexes in the mautrix-meta-messenger and
mautrix-meta-instagram registration templates interpolated
the bridge username prefix without regex-escaping it, unlike the
neighboring homeserver domain and appservice username values. The
default prefixes are regex-safe, but a customized prefix containing
regex metacharacters would produce a wrong (too broad or invalid)
appservice user namespace.

Related to the registration regex discussion in #5096.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The playbook-shipped welcome.html hardcoded #2e2f32 for the headline and
welcome text, which is nearly invisible on the dark background Element
renders when the dark theme is active. Element Web's default
use_system_theme behavior keys the theme off the system color scheme, so
switch the text to Element's dark-theme text color (#ebeef2) under a
prefers-color-scheme: dark media query.

Fixes #4838

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Pulls in borgmatic 2.1.6, fixing the 2.1.4 JSON parsing regression
(borgmatic-collective/borgmatic#1294) where warnings on stderr, such as
OpenSSH post-quantum key exchange notices, broke parsing of borg's JSON
output and failed the backup run.

Fixes #5188

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>

matrix_appservice_discord_container_image_self_build only switched the
image registry prefix to localhost/, but the role never had any build
tasks, so enabling it always ended in an image pull failure. Remove the
variable and reject it in validate_config.yml with a hint that the
prebuilt image is amd64-only and that mautrix-discord is the better
option on other architectures.

Fixes #2379

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>

The exporter's wal collector (enabled by default) calls pg_ls_waldir(),
which Postgres restricts to superusers and members of the pg_monitor
role. The exporter user is created as a plain managed-database user, so
scraping logged "permission denied for function pg_ls_waldir" on every
run.

Grant pg_monitor via the managed database's additional_sql_queries,
which the Postgres role applies both on initial creation and on
subsequent runs, covering existing installations too.

Fixes #3039

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Pulls in the pgloader connection string handling fix, which keeps the
Postgres password out of the command line and Ansible error output.

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

The upstream Synapse Grafana dashboard uses `{{job}}-{{index}}` in its
legends to tell workers apart, but the worker scrape configs only set
instance, worker_id, job and app labels. Without an index label, the
dashboard legends collapsed and workers could not be distinguished.

Derive the index label from the worker id (its per-type index is the
first number in the id, e.g. federation-sender-1, stream-writer-2-events),
matching the index label already set on the main process target.

Fixes #2158
Fixes #2159

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

Element Desktop (Electron) loads the location-sharing map style from a
`vector://vector` origin, so fetching map_style.json from the Element
domain is a cross-origin request. Without an Access-Control-Allow-Origin
header, the request is blocked and maps fail to load with "This homeserver
is not configured correctly to display maps".

Add a dedicated Traefik router for map_style.json that attaches an
Access-Control-Allow-Origin header (configurable via
matrix_client_element_location_sharing_map_style_access_control_allow_origin,
defaulting to `*`). It is only defined when location sharing is enabled.

Fixes #2291

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

Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5>

Signed-off-by: Suguru Hirahara <did🔑z6MkvVZk1A3KBApWJXv2Ju4H14ErDfRGxh8zxdXSZ4vACDg5>

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

Add devcontainer config

flake.lock already pins agru at the v0.2.1 commit (via #5415);
this label only names the built derivation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

This lets Renovate periodically refresh flake.lock, keeping the
nixpkgs and agru inputs of the development shell up to date.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add agru to flake.nix

Based on https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/4219 by @mcnesium

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Attaches a com.centurylinklabs.watchtower.enable=false label to the
matrix-matrixto container by default, telling Watchtower (if in use)
to skip it. The image is built locally from source, so Watchtower
cannot update it and merely produces 'digest retrieval failed' errors
on every run.

A dedicated variable is used (instead of pre-filling
matrix_matrixto_container_labels_additional_labels) so that people
overriding the additional-labels variable do not lose the label.

Fixes #4820

Based on the report and initial patch in
https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/4821 by @der-domi

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>