From db70230ae16ff8351450b21d007f336003ff873e Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 09:17:24 -0600
Subject: [PATCH 01/28] Add room-workers as a new preset, with new room
 workers, sync workers, client readers, and federation readers.  Based on
 https://tcpipuk.github.io/synapse/index.html

---
 group_vars/matrix_servers                     |  5 ++
 .../defaults/main.yml                         |  5 ++
 ...ix-synapse-reverse-proxy-companion.conf.j2 | 81 ++++++++++++++-----
 roles/custom/matrix-synapse/defaults/main.yml | 47 +++++++++++
 .../tasks/synapse/workers/init.yml            | 52 ++++++++++++
 roles/custom/matrix-synapse/vars/main.yml     | 19 +++++
 6 files changed, 190 insertions(+), 19 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 3ebe649be..d4f4ea1bc 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -4081,6 +4081,11 @@ matrix_synapse_reverse_proxy_companion_container_labels_internal_client_api_trae
 
 matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: "{{ matrix_synapse_workers_enabled }}"
 matrix_synapse_reverse_proxy_companion_synapse_workers_list: "{{ matrix_synapse_workers_enabled_list }}"
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: "{{ matrix_synapse_workers_room_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations: "{{ matrix_synapse_workers_room_worker_federation_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations: "{{ matrix_synapse_workers_sync_worker_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations: "{{ matrix_synapse_workers_client_reader_client_server_endpoints }}"
+matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations: "{{ matrix_synapse_workers_federation_reader_federation_endpoints }}"
 matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations: "{{ matrix_synapse_workers_generic_worker_client_server_endpoints }}"
 matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations: "{{ matrix_synapse_workers_generic_worker_federation_endpoints }}"
 matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations: "{{ matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints }}"
diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
index 7a3f4f709..3f19e3a2b 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
@@ -206,6 +206,11 @@ matrix_synapse_reverse_proxy_companion_synapse_federation_api_additional_server_
 # synapse worker activation and endpoint mappings
 matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: false
 matrix_synapse_reverse_proxy_companion_synapse_workers_list: []
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: []
+matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations: []
+matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations: []
+matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations: []
+matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations: []
 matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations: []
 matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations: []
 matrix_synapse_reverse_proxy_companion_synapse_stream_writer_typing_stream_worker_client_server_locations: []
diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index c94855d59..c3164e963 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -1,5 +1,9 @@
 #jinja2: lstrip_blocks: "True"
 
+{% set room_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'room_worker') | list %}
+{% set sync_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'sync_worker') | list %}
+{% set client_reader_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'client_reader') | list %}
+{% set federation_reader_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'federation_reader') | list %}
 {% set generic_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'generic_worker') | list %}
 {% set stream_writer_typing_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'typing') | list %}
 {% set stream_writer_to_device_stream_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'stream_writer') | selectattr('stream_writer_stream', 'equalto', 'to_device') | list %}
@@ -9,9 +13,31 @@
 {% set media_repository_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'media_repository') | list %}
 {% set user_dir_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'user_dir') | list %}
 
-{% macro render_worker_upstream(name, workers) %}
+
+# Maps from https://tcpipuk.github.io/synapse/deployment/nginx.html#mapsconf
+# Client username from MXID
+map $http_authorization $mxid_localpart {
+  default                           $http_authorization;
+  "~Bearer syt_(?<username>.*?)_.*" $username;
+  ""                                $accesstoken_from_urlparam;
+}
+
+# Whether to upgrade HTTP connection
+map $http_upgrade $connection_upgrade {
+  default upgrade;
+  '' close;
+}
+
+#Extract room name from URI
+map $request_uri $room_name {
+  ~^/_matrix/(client|federation)/.*?(?:%21|!)(?<room>[A-Za-z0-9._=\-\/]+)(?::|%3A)[A-Za-z0-9._=\-\/]+ $room;
+}
+# End maps
+
+{% macro render_worker_upstream(name, workers, load_balance) %}
 {% if workers | length > 0 %}
 	upstream {{ name }} {
+		{{ load_balance }}
 		keepalive {{ workers | length * 2 }};
 		{% for worker in workers %}
 			server "{{ worker.name }}:{{ worker.port }}";
@@ -37,28 +63,22 @@
 	{% endif %}
 	# Round Robin "upstream" pools for workers
 
-	{% if generic_workers |length > 0 %}
-	upstream generic_workers_upstream {
-		# ensures that requests from the same client will always be passed
-		# to the same server (except when this server is unavailable)
-		hash $http_x_forwarded_for;
-		keepalive {{ generic_workers | length * 2 }};
+	{{ render_worker_upstream('room_workers_upstream', room_workers, 'hash $room_name consistent;')
+	{{ render_worker_upstream('sync_workers_upstream', room_workers, 'hash $mxid_localpart consistent;')
+	{{ render_worker_upstream('client_reader_workers_upstream', client_reader_workers, 'least_conn;')
+	{{ render_worker_upstream('federation_reader_workers_upstream', federation_reader_workers, 'hash $http_x_forwarded_for;') }}
 
-		{% for worker in generic_workers %}
-			server "{{ worker.name }}:{{ worker.port }}";
-		{% endfor %}
-	}
-	{% endif %}
+	{{ render_worker_upstream('generic_workers_upstream', generic_workers, 'hash $http_x_forwarded_for;') }}
 
-	{{ render_worker_upstream('stream_writer_typing_stream_workers_upstream', stream_writer_typing_stream_workers) }}
-	{{ render_worker_upstream('stream_writer_to_device_stream_workers_upstream', stream_writer_to_device_stream_workers) }}
-	{{ render_worker_upstream('stream_writer_account_data_stream_workers_upstream', stream_writer_account_data_stream_workers) }}
-	{{ render_worker_upstream('stream_writer_receipts_stream_workers_upstream', stream_writer_receipts_stream_workers) }}
-	{{ render_worker_upstream('stream_writer_presence_stream_workers_upstream', stream_writer_presence_stream_workers) }}
+	{{ render_worker_upstream('stream_writer_typing_stream_workers_upstream', stream_writer_typing_stream_workers, '') }}
+	{{ render_worker_upstream('stream_writer_to_device_stream_workers_upstream', stream_writer_to_device_stream_workers, '') }}
+	{{ render_worker_upstream('stream_writer_account_data_stream_workers_upstream', stream_writer_account_data_stream_workers, '') }}
+	{{ render_worker_upstream('stream_writer_receipts_stream_workers_upstream', stream_writer_receipts_stream_workers, '') }}
+	{{ render_worker_upstream('stream_writer_presence_stream_workers_upstream', stream_writer_presence_stream_workers, '') }}
 
-	{{ render_worker_upstream('media_repository_workers_upstream', media_repository_workers) }}
+	{{ render_worker_upstream('media_repository_workers_upstream', media_repository_workers, 'least_conn;') }}
 
-	{{ render_worker_upstream('user_dir_workers_upstream', user_dir_workers) }}
+	{{ render_worker_upstream('user_dir_workers_upstream', user_dir_workers, '') }}
 {% endif %}
 
 server {
@@ -74,6 +94,21 @@ server {
 	{% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
 		{# Workers redirects BEGIN #}
 
+		{% if room_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations, 'room_workers_upstream') }}
+		{% endif %}
+
+		{% if sync_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations, 'sync_workers_upstream') }}
+		{% endif %}
+
+		{% if client_reader_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations, 'client_reader_workers_upstream') }}
+		{% endif %}
+
 		{% if generic_workers | length > 0 %}
 			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappgeneric_worker
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations, 'generic_workers_upstream') }}
@@ -165,6 +200,14 @@ server {
 	gzip_types text/plain application/json;
 
 	{% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
+		{% if room_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations, 'room_workers_upstream') }}
+		{% endif %}
+		{% if federation_reader_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_federation_reader_federation_locations, 'federation_reader_workers_upstream') }}
+		{% endif %}
 		{% if generic_workers | length > 0 %}
 			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappgeneric_worker
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_generic_worker_federation_locations, 'generic_workers_upstream') }}
diff --git a/roles/custom/matrix-synapse/defaults/main.yml b/roles/custom/matrix-synapse/defaults/main.yml
index 4b1513fa5..7dd7ec227 100644
--- a/roles/custom/matrix-synapse/defaults/main.yml
+++ b/roles/custom/matrix-synapse/defaults/main.yml
@@ -666,6 +666,10 @@ matrix_synapse_workers_preset: one-of-each
 
 matrix_synapse_workers_presets:
   little-federation-helper:
+    room_workers_count: 0
+    sync_workers_count: 0
+    client_reader_workers_count: 0
+    federation_reader_workers_count: 0
     generic_workers_count: 0
     pusher_workers_count: 0
     federation_sender_workers_count: 1
@@ -680,6 +684,10 @@ matrix_synapse_workers_presets:
     stream_writer_receipts_stream_workers_count: 0
     stream_writer_presence_stream_workers_count: 0
   one-of-each:
+    room_workers_count: 0
+    sync_workers_count: 0
+    client_reader_workers_count: 0
+    federation_reader_workers_count: 0
     generic_workers_count: 1
     pusher_workers_count: 1
     federation_sender_workers_count: 1
@@ -693,6 +701,24 @@ matrix_synapse_workers_presets:
     stream_writer_account_data_stream_workers_count: 1
     stream_writer_receipts_stream_workers_count: 1
     stream_writer_presence_stream_workers_count: 1
+  room-workers:
+    room_workers_count: 1
+    sync_workers_count: 1
+    client_reader_workers_count: 1
+    federation_reader_workers_count: 1
+    generic_workers_count: 0
+    pusher_workers_count: 1
+    federation_sender_workers_count: 1
+    media_repository_workers_count: 1
+    appservice_workers_count: 1
+    user_dir_workers_count: 1
+    background_workers_count: 1
+    stream_writer_events_stream_workers_count: 1
+    stream_writer_typing_stream_workers_count: 1
+    stream_writer_to_device_stream_workers_count: 1
+    stream_writer_account_data_stream_workers_count: 1
+    stream_writer_receipts_stream_workers_count: 1
+    stream_writer_presence_stream_workers_count: 1
 
 # Controls whether the matrix-synapse container exposes the various worker ports
 # (see `port` and `metrics_port` in `matrix_synapse_workers_enabled_list`) outside of the container.
@@ -733,6 +759,27 @@ matrix_synapse_worker_container_labels_public_metrics_middleware_basic_auth_user
 #   another.label="here"
 matrix_synapse_worker_container_labels_additional_labels: ''
 
+# Room workers
+matrix_synapse_workers_room_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['room_workers_count'] }}"
+matrix_synapse_workers_room_workers_port_range_start: 28111
+matrix_synapse_workers_room_workers_metrics_range_start: 29111
+
+# Sync workers
+matrix_synapse_workers_sync_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['sync_workers_count'] }}"
+matrix_synapse_workers_sync_workers_port_range_start: 28211
+matrix_synapse_workers_sync_workers_metrics_range_start: 29211
+
+# Client reader workers
+matrix_synapse_workers_client_reader_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['client_reader_workers_count'] }}"
+matrix_synapse_workers_client_reader_workers_port_range_start: 28311
+matrix_synapse_workers_client_reader_workers_metrics_range_start: 29311
+
+# Federation reader workers
+matrix_synapse_workers_federation_reader_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['federation_reader_workers_count'] }}"
+matrix_synapse_workers_federation_reader_workers_port_range_start: 28411
+matrix_synapse_workers_federation_reader_workers_metrics_range_start: 29411
+
+# Generic workers
 matrix_synapse_workers_generic_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['generic_workers_count'] }}"
 matrix_synapse_workers_generic_workers_port_range_start: 18111
 matrix_synapse_workers_generic_workers_metrics_range_start: 19111
diff --git a/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml b/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
index 68b8f37e3..a1bc4cc72 100644
--- a/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
+++ b/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
@@ -4,6 +4,58 @@
 # set_fact within a loop does not work reliably in Ansible (it only executes on the first iteration for some reason),
 # so we're forced to do something much uglier.
 
+- name: Build room workers
+  ansible.builtin.set_fact:
+    worker:
+      id: "room-worker-{{ item }}"
+      name: "matrix-synapse-worker-room-{{ item }}"
+      type: 'room_worker'
+      app: 'generic_worker'
+      webserving: true
+      port: "{{ matrix_synapse_workers_room_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_room_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_room_workers"
+  loop: "{{ range(0, matrix_synapse_workers_room_workers_count | int) | list }}"
+
+- name: Build client sync workers
+  ansible.builtin.set_fact:
+    worker:
+      id: "sync-worker-{{ item }}"
+      name: "matrix-synapse-worker-sync-{{ item }}"
+      type: 'sync_worker'
+      app: 'generic_worker'
+      webserving: true
+      port: "{{ matrix_synapse_workers_sync_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_sync_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_sync_workers"
+  loop: "{{ range(0, matrix_synapse_workers_sync_workers_count | int) | list }}"
+
+- name: Build client reader workers
+  ansible.builtin.set_fact:
+    worker:
+      id: "client-reader-{{ item }}"
+      name: "matrix-synapse-worker-client-reader-{{ item }}"
+      type: 'client_reader'
+      app: 'generic_worker'
+      webserving: true
+      port: "{{ matrix_synapse_workers_client_reader_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_client_reader_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_client_reader_workers"
+  loop: "{{ range(0, matrix_synapse_workers_client_reader_workers_count | int) | list }}"
+
+- name: Build federation reader workers
+  ansible.builtin.set_fact:
+    worker:
+      id: "federation-reader-{{ item }}"
+      name: "matrix-synapse-worker-federation-reader-{{ item }}"
+      type: 'federation_reader'
+      app: 'generic_worker'
+      webserving: true
+      port: "{{ matrix_synapse_workers_federation_reader_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_federation_reader_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_federation_reader_workers"
+  loop: "{{ range(0, matrix_synapse_workers_federation_reader_workers_count | int) | list }}"
+
 - name: Build generic workers
   ansible.builtin.set_fact:
     worker:
diff --git a/roles/custom/matrix-synapse/vars/main.yml b/roles/custom/matrix-synapse/vars/main.yml
index 137a59737..63ad48550 100644
--- a/roles/custom/matrix-synapse/vars/main.yml
+++ b/roles/custom/matrix-synapse/vars/main.yml
@@ -8,6 +8,25 @@ matrix_synapse_media_store_directory_name: "{{ matrix_synapse_media_store_path |
 # Optionally: `false` to fully disable tls on outbound smtp
 matrix_synapse_email_smtp_enable_tls: true
 
+# Room workers handle any URL that contains a room id, either through the client-server API or the federation API
+# - see https://tcpipuk.github.io/synapse/deployment/nginx.html#locationsconf
+matrix_synapse_workers_room_worker_client_server_endpoints:
+  - ^/_matrix/client/.*?!(?<room>[A-Za-z0-9._=\-\/]+):[A-Za-z0-9.\-]+
+matrix_synapse_workers_room_worker_federation_endpoints:
+  - ^/_matrix/federation/v[12]/(?:state_ids|get_missing_events)/(?:%21|!)(?<room>[A-Za-z0-9._=\-\/]+)(:|%3A)[A-Za-z0-9.\-]+
+
+# Sync workers handle /sync and the (now deprecated) related endpoints
+matrix_synapse_workers_sync_worker_client_server_endpoints:
+  - ^/_matrix/client/(api/v1|r0|v3|unstable)/(sync|events|initialSync|rooms/[^/]+/initialSync)$
+
+# Client reader workers handle generic client-server endpoints that don't contain a roomid or sync
+matrix_synapse_workers_client_reader_client_server_endpoints:
+  - ^/_matrix/client/(api/v1|r0|v3|unstable)/(room_keys/|keys/(query|changes|claim|upload/|room_keys/)|login|register(/available|/m.login.registration_token/validity|)|password_policy|profile|rooms/.*/(joined_members|context/.*|members|state|hierarchy|relations/|event/|aliases|timestamp_to_event|redact|send|state/|(join|invite|leave|ban|unban|kick))|createRoom|publicRooms|account/(3pid|whoami|devices)|versions|voip/turnServer|joined_rooms|search|user/.*/filter(/|$)|directory/room/.*|capabilities)
+
+# Federation reader workers handle generic federation endpoints that don't contain a roomid
+matrix_synapse_workers_federation_reader_federation_endpoints:
+  - ^/_matrix/(federation/(v1|v2)|key/v2)/
+
 # A Synapse generic worker can handle both federation and client-server API endpoints.
 # We wish to split these, as we normally serve federation separately and don't want them mixed up.
 #

From 0175a472d73556eb25ab0cededf25c5e891ac948 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 10:02:36 -0600
Subject: [PATCH 02/28] Typo: forgot closing }}'s

---
 .../conf.d/matrix-synapse-reverse-proxy-companion.conf.j2   | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index c3164e963..f44823aa8 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -63,9 +63,9 @@ map $request_uri $room_name {
 	{% endif %}
 	# Round Robin "upstream" pools for workers
 
-	{{ render_worker_upstream('room_workers_upstream', room_workers, 'hash $room_name consistent;')
-	{{ render_worker_upstream('sync_workers_upstream', room_workers, 'hash $mxid_localpart consistent;')
-	{{ render_worker_upstream('client_reader_workers_upstream', client_reader_workers, 'least_conn;')
+	{{ render_worker_upstream('room_workers_upstream', room_workers, 'hash $room_name consistent;') }}
+	{{ render_worker_upstream('sync_workers_upstream', room_workers, 'hash $mxid_localpart consistent;') }}
+	{{ render_worker_upstream('client_reader_workers_upstream', client_reader_workers, 'least_conn;') }}
 	{{ render_worker_upstream('federation_reader_workers_upstream', federation_reader_workers, 'hash $http_x_forwarded_for;') }}
 
 	{{ render_worker_upstream('generic_workers_upstream', generic_workers, 'hash $http_x_forwarded_for;') }}

From 12a8d535e81ad95fef232aa997c1afc5aa7dc624 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 10:53:20 -0600
Subject: [PATCH 03/28] Move maps inside the if-workers block; Add Tom's map to
 extract access token from the URI arg

---
 ...ix-synapse-reverse-proxy-companion.conf.j2 | 45 ++++++++++---------
 1 file changed, 24 insertions(+), 21 deletions(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index f44823aa8..11619f204 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -13,27 +13,6 @@
 {% set media_repository_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'media_repository') | list %}
 {% set user_dir_workers = matrix_synapse_reverse_proxy_companion_synapse_workers_list | selectattr('type', 'equalto', 'user_dir') | list %}
 
-
-# Maps from https://tcpipuk.github.io/synapse/deployment/nginx.html#mapsconf
-# Client username from MXID
-map $http_authorization $mxid_localpart {
-  default                           $http_authorization;
-  "~Bearer syt_(?<username>.*?)_.*" $username;
-  ""                                $accesstoken_from_urlparam;
-}
-
-# Whether to upgrade HTTP connection
-map $http_upgrade $connection_upgrade {
-  default upgrade;
-  '' close;
-}
-
-#Extract room name from URI
-map $request_uri $room_name {
-  ~^/_matrix/(client|federation)/.*?(?:%21|!)(?<room>[A-Za-z0-9._=\-\/]+)(?::|%3A)[A-Za-z0-9._=\-\/]+ $room;
-}
-# End maps
-
 {% macro render_worker_upstream(name, workers, load_balance) %}
 {% if workers | length > 0 %}
 	upstream {{ name }} {
@@ -58,6 +37,30 @@ map $request_uri $room_name {
 {% endmacro %}
 
 {% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
+
+# Maps from https://tcpipuk.github.io/synapse/deployment/nginx.html#mapsconf
+# Client username from access token
+map $arg_access_token $accesstoken_from_urlparam {
+  default                    $arg_access_token;
+  "~syt_(?<username>.*?)_.*" $username;
+}
+# Client username from MXID
+map $http_authorization $mxid_localpart {
+  default                           $http_authorization;
+  "~Bearer syt_(?<username>.*?)_.*" $username;
+  ""                                $accesstoken_from_urlparam;
+}
+# Whether to upgrade HTTP connection
+map $http_upgrade $connection_upgrade {
+  default upgrade;
+  '' close;
+}
+#Extract room name from URI
+map $request_uri $room_name {
+  ~^/_matrix/(client|federation)/.*?(?:%21|!)(?<room>[A-Za-z0-9._=\-\/]+)(?::|%3A)[A-Za-z0-9._=\-\/]+ $room;
+}
+# End maps
+
 	{% if matrix_synapse_reverse_proxy_companion_synapse_cache_enabled %}
     	proxy_cache_path  {{ matrix_synapse_reverse_proxy_companion_synapse_cache_path }} levels=1:2 keys_zone={{ matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_name }}:{{ matrix_synapse_reverse_proxy_companion_synapse_cache_keys_zone_size }} inactive={{ matrix_synapse_reverse_proxy_companion_synapse_cache_inactive_time }} max_size={{ matrix_synapse_reverse_proxy_companion_synapse_cache_max_size_mb }}m;
 	{% endif %}

From 5ca9a7269a3ad6aee0c0c654ca348161cfdc2b2c Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 10:58:46 -0600
Subject: [PATCH 04/28] Add the new worker types to the list of available
 worker types

---
 roles/custom/matrix-synapse/vars/main.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/roles/custom/matrix-synapse/vars/main.yml b/roles/custom/matrix-synapse/vars/main.yml
index 63ad48550..828dcbeab 100644
--- a/roles/custom/matrix-synapse/vars/main.yml
+++ b/roles/custom/matrix-synapse/vars/main.yml
@@ -261,9 +261,13 @@ matrix_synapse_workers_user_dir_endpoints:
 
 matrix_synapse_workers_avail_list:
   - appservice
+  - client_reader
+  - federation_reader
   - federation_sender
   - generic_worker
   - media_repository
   - pusher
+  - room_worker
+  - sync_worker
   - user_dir
 ### workers:end

From 1379200e9dc8a8064d91a3a7ab14baba3e4ec5d3 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 11:13:51 -0600
Subject: [PATCH 05/28] Add new worker types to the dynamic workers list

---
 .../custom/matrix-synapse/tasks/synapse/workers/init.yml  | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml b/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
index a1bc4cc72..8bf8201a0 100644
--- a/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
+++ b/roles/custom/matrix-synapse/tasks/synapse/workers/init.yml
@@ -182,6 +182,14 @@
     matrix_synapse_dynamic_workers_list: "{{ matrix_synapse_dynamic_workers_list | default([]) + [item.ansible_facts.worker] }}"
   with_items: |
     {{
+      matrix_synapse_workers_list_results_room_workers.results
+      +
+      matrix_synapse_workers_list_results_sync_workers.results
+      +
+      matrix_synapse_workers_list_results_client_reader_workers.results
+      +
+      matrix_synapse_workers_list_results_federation_reader_workers.results
+      +
       matrix_synapse_workers_list_results_generic_workers.results
       +
       matrix_synapse_workers_list_results_stream_writer_workers.results

From 124524ea1fa28f3a2c9573ace834d9f1aa190f26 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 11:22:46 -0600
Subject: [PATCH 06/28] Typo: Send sync endpoints to sync workers, not room
 workers

---
 .../nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index 11619f204..781b2edb3 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -67,7 +67,7 @@ map $request_uri $room_name {
 	# Round Robin "upstream" pools for workers
 
 	{{ render_worker_upstream('room_workers_upstream', room_workers, 'hash $room_name consistent;') }}
-	{{ render_worker_upstream('sync_workers_upstream', room_workers, 'hash $mxid_localpart consistent;') }}
+	{{ render_worker_upstream('sync_workers_upstream', sync_workers, 'hash $mxid_localpart consistent;') }}
 	{{ render_worker_upstream('client_reader_workers_upstream', client_reader_workers, 'least_conn;') }}
 	{{ render_worker_upstream('federation_reader_workers_upstream', federation_reader_workers, 'hash $http_x_forwarded_for;') }}
 

From a1cbe7f39b43b6016543db02b8d6e102e62f2ff9 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 16:32:32 -0600
Subject: [PATCH 07/28] Add overrides for locations that must go to the main
 Synapse process

---
 .../defaults/main.yml                         |  4 +-
 ...ix-synapse-reverse-proxy-companion.conf.j2 | 45 +++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
index 3f19e3a2b..4a330e7a8 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
@@ -220,7 +220,9 @@ matrix_synapse_reverse_proxy_companion_synapse_stream_writer_receipts_stream_wor
 matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations: []
 matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations: []
 matrix_synapse_reverse_proxy_companion_synapse_user_dir_locations: []
-
+matrix_synapse_reverse_proxy_companion_client_server_main_override_locations_regex: ^/_matrix/client/(api/v1|r0|v3|unstable)/(account/3pid/|directory/list/room/|pushrules/|rooms/[^/]+/(forget|upgrade)|login/sso/redirect/|register)
+matrix_synapse_reverse_proxy_companion_client_server_sso_override_locations_regex: ^(/_matrix/client/(api/v1|r0|v3|unstable)/login/sso/redirect|/_synapse/client/(pick_username|(new_user_consent|oidc/callback|pick_idp|sso_register)$))
+matrix_synapse_reverse_proxy_companion_federation_override_locations_regex: ^/_matrix/federation/v1/openid/userinfo$
 
 # synapse content caching
 matrix_synapse_reverse_proxy_companion_synapse_cache_enabled: false
diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index 781b2edb3..81c9ced20 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -95,6 +95,36 @@ server {
 	gzip_types text/plain application/json;
 
 	{% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
+		# Client-server overrides -- These locations must go to the main Synapse process
+		location ~ {{ matrix_synapse_reverse_proxy_companion_client_server_main_override_locations_regex }} {
+			{# FIXME: This block was copied from the main Synapse fallback below.  It would be better to have it in one place and avoid duplication. #}
+			{# Use the embedded DNS resolver in Docker containers to discover the service #}
+			resolver {{ matrix_synapse_reverse_proxy_companion_http_level_resolver }} valid=5s;
+			set $backend "{{ matrix_synapse_reverse_proxy_companion_client_api_addr }}";
+			proxy_pass http://$backend;
+
+			proxy_set_header Host $host;
+
+			client_body_buffer_size 25M;
+			client_max_body_size {{ matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb }}M;
+			proxy_max_temp_file_size 0;
+		}
+
+		# Client-server SSO overrides -- These locations must go to the main Synapse process
+		location ~ {{ matrix_synapse_reverse_proxy_companion_client_server_sso_override_locations_regex }} {
+			{# FIXME: This block was copied from the main Synapse fallback below.  It would be better to have it in one place and avoid duplication. #}
+			{# Use the embedded DNS resolver in Docker containers to discover the service #}
+			resolver {{ matrix_synapse_reverse_proxy_companion_http_level_resolver }} valid=5s;
+			set $backend "{{ matrix_synapse_reverse_proxy_companion_client_api_addr }}";
+			proxy_pass http://$backend;
+
+			proxy_set_header Host $host;
+
+			client_body_buffer_size 25M;
+			client_max_body_size {{ matrix_synapse_reverse_proxy_companion_client_api_client_max_body_size_mb }}M;
+			proxy_max_temp_file_size 0;
+		}
+
 		{# Workers redirects BEGIN #}
 
 		{% if room_workers | length > 0 %}
@@ -203,6 +233,21 @@ server {
 	gzip_types text/plain application/json;
 
 	{% if matrix_synapse_reverse_proxy_companion_synapse_workers_enabled %}
+		# Federation overrides -- These locations must go to the main Synapse process
+		location ~ {{ matrix_synapse_reverse_proxy_companion_federation_override_locations_regex }} {
+			{# FIXME: This block was copied from the fallback location below.  It would be better to have it in one place and avoid duplication. #}
+			{# Use the embedded DNS resolver in Docker containers to discover the service #}
+			resolver {{ matrix_synapse_reverse_proxy_companion_http_level_resolver }} valid=5s;
+			set $backend "{{ matrix_synapse_reverse_proxy_companion_federation_api_addr }}";
+			proxy_pass http://$backend;
+
+			proxy_set_header Host $host;
+
+			client_body_buffer_size 25M;
+			client_max_body_size {{ matrix_synapse_reverse_proxy_companion_federation_api_client_max_body_size_mb }}M;
+			proxy_max_temp_file_size 0;
+		}
+
 		{% if room_workers | length > 0 %}
 			# https://tcpipuk.github.io/synapse/deployment/workers.html
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_federation_locations, 'room_workers_upstream') }}

From 0dbdaf5b9f2e339684e8c916787cf623b20a2cab Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 16:51:23 -0600
Subject: [PATCH 08/28] Enable HTTP resources for new worker types

---
 .../matrix-synapse/templates/synapse/worker.yaml.j2 | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/roles/custom/matrix-synapse/templates/synapse/worker.yaml.j2 b/roles/custom/matrix-synapse/templates/synapse/worker.yaml.j2
index 18b96a55f..738f0fa33 100644
--- a/roles/custom/matrix-synapse/templates/synapse/worker.yaml.j2
+++ b/roles/custom/matrix-synapse/templates/synapse/worker.yaml.j2
@@ -7,10 +7,17 @@ worker_log_config: /data/{{ matrix_server_fqn_matrix }}.log.config
 
 {% set http_resources = [] %}
 
-{% if matrix_synapse_worker_details.type == 'user_dir' %}
+{% if matrix_synapse_worker_details.type == 'room_worker' %}
+  {% set http_resources = http_resources + ['client', 'federation'] %}
+{% elif matrix_synapse_worker_details.type == 'sync_worker' %}
   {% set http_resources = http_resources + ['client'] %}
-{% endif %}
-{% if matrix_synapse_worker_details.type == 'generic_worker' %}
+{% elif matrix_synapse_worker_details.type == 'client_reader' %}
+  {% set http_resources = http_resources + ['client'] %}
+{% elif matrix_synapse_worker_details.type == 'federation_reader' %}
+  {% set http_resources = http_resources + ['federation'] %}
+{% elif matrix_synapse_worker_details.type == 'user_dir' %}
+  {% set http_resources = http_resources + ['client'] %}
+{% elif matrix_synapse_worker_details.type == 'generic_worker' %}
   {% set http_resources = http_resources + ['client', 'federation'] %}
 {% endif %}
 {#

From 55604f73c5d0726e006a936af8d302bdcafa0cff Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Tue, 16 Jan 2024 17:24:13 -0600
Subject: [PATCH 09/28] Bugfix: Locations for new workers must go *after* the
 stream writers

---
 ...ix-synapse-reverse-proxy-companion.conf.j2 | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index 81c9ced20..dcb6ebeea 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -127,21 +127,6 @@ server {
 
 		{# Workers redirects BEGIN #}
 
-		{% if room_workers | length > 0 %}
-			# https://tcpipuk.github.io/synapse/deployment/workers.html
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations, 'room_workers_upstream') }}
-		{% endif %}
-
-		{% if sync_workers | length > 0 %}
-			# https://tcpipuk.github.io/synapse/deployment/workers.html
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations, 'sync_workers_upstream') }}
-		{% endif %}
-
-		{% if client_reader_workers | length > 0 %}
-			# https://tcpipuk.github.io/synapse/deployment/workers.html
-			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations, 'client_reader_workers_upstream') }}
-		{% endif %}
-
 		{% if generic_workers | length > 0 %}
 			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappgeneric_worker
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_generic_worker_client_server_locations, 'generic_workers_upstream') }}
@@ -172,6 +157,21 @@ server {
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_stream_writer_presence_stream_worker_client_server_locations, 'stream_writer_presence_stream_workers_upstream') }}
 		{% endif %}
 
+		{% if room_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations, 'room_workers_upstream') }}
+		{% endif %}
+
+		{% if sync_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations, 'sync_workers_upstream') }}
+		{% endif %}
+
+		{% if client_reader_workers | length > 0 %}
+			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations, 'client_reader_workers_upstream') }}
+		{% endif %}
+
 		{% if media_repository_workers | length > 0 %}
 			# https://matrix-org.github.io/synapse/latest/workers.html#synapseappmedia_repository
 			{% for location in matrix_synapse_reverse_proxy_companion_synapse_media_repository_locations %}

From 7d9eb561644811c912d9e074d4b7f70198060f10 Mon Sep 17 00:00:00 2001
From: Charles Wright <cvwright@futo.org>
Date: Wed, 17 Jan 2024 15:22:27 -0600
Subject: [PATCH 10/28] Add a validation step to fail when the user allocates
 generic workers together with all of the new worker types

---
 roles/custom/matrix-synapse/tasks/validate_config.yml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/roles/custom/matrix-synapse/tasks/validate_config.yml b/roles/custom/matrix-synapse/tasks/validate_config.yml
index ab389a432..fdf208e8d 100644
--- a/roles/custom/matrix-synapse/tasks/validate_config.yml
+++ b/roles/custom/matrix-synapse/tasks/validate_config.yml
@@ -47,6 +47,12 @@
     - "matrix_synapse_workers_stream_writer_receipts_stream_workers_count"
     - "matrix_synapse_workers_stream_writer_presence_stream_workers_count"
 
+- name: Fail when mixing generic workers with new specialized workers
+  ansible.builtin.fail:
+    msg: >-
+      Generic workers should not be mixed with the new specialized worker types (room workers, sync workers, client readers, and federation readers)
+  when: matrix_synapse_workers_generic_workers_count | int > 0 and matrix_synapse_workers_room_workers_count | int > 0 and matrix_synapse_workers_sync_workers_count | int > 0 and matrix_synapse_workers_client_reader_workers_count | int > 0 and matrix_synapse_workers_federation_reader_workers_count | int > 0
+
 - name: (Deprecation) Catch and report renamed settings
   ansible.builtin.fail:
     msg: >-

From dbebe7c59825ad439ccf0939acf94bd01efbedbc Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 19 Jan 2024 08:19:28 +0200
Subject: [PATCH 11/28] Add variable for controlling force_disable in
 io.element.e2ee in /.well-known/matrix/client

---
 roles/custom/matrix-static-files/defaults/main.yml          | 6 ++++++
 .../templates/public/.well-known/matrix/client.j2           | 3 ++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/roles/custom/matrix-static-files/defaults/main.yml b/roles/custom/matrix-static-files/defaults/main.yml
index 966d04437..75c87494a 100644
--- a/roles/custom/matrix-static-files/defaults/main.yml
+++ b/roles/custom/matrix-static-files/defaults/main.yml
@@ -176,6 +176,12 @@ matrix_static_files_file_matrix_client_property_io_element_e2ee_secure_backup_re
 # See: https://github.com/element-hq/element-web/blob/develop/docs/e2ee.md
 matrix_static_files_file_matrix_client_property_io_element_e2ee_secure_backup_setup_methods: []
 
+# Controls the io.element.e2ee/force_disable property in the /.well-known/matrix/client file,
+# which can be set to `true` to instruct Element whether to disable End-to-End Encryption by default
+# and to not show encryption related-settings in room settings.
+# See: https://github.com/element-hq/element-web/blob/develop/docs/e2ee.md
+matrix_static_files_file_matrix_client_property_io_element_e2ee_force_disable: false
+
 # Default /.well-known/matrix/client configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
 #
diff --git a/roles/custom/matrix-static-files/templates/public/.well-known/matrix/client.j2 b/roles/custom/matrix-static-files/templates/public/.well-known/matrix/client.j2
index ca272fe35..5a3deb6a2 100644
--- a/roles/custom/matrix-static-files/templates/public/.well-known/matrix/client.j2
+++ b/roles/custom/matrix-static-files/templates/public/.well-known/matrix/client.j2
@@ -39,7 +39,8 @@
 	"io.element.e2ee": {
 		"default": {{ matrix_static_files_file_matrix_client_property_io_element_e2ee_default|to_json }},
 		"secure_backup_required": {{ matrix_static_files_file_matrix_client_property_io_element_e2ee_secure_backup_required|to_json }},
-		"secure_backup_setup_methods": {{ matrix_static_files_file_matrix_client_property_io_element_e2ee_secure_backup_setup_methods|to_json }}
+		"secure_backup_setup_methods": {{ matrix_static_files_file_matrix_client_property_io_element_e2ee_secure_backup_setup_methods|to_json }},
+		"force_disable": {{ matrix_static_files_file_matrix_client_property_io_element_e2ee_force_disable|to_json }}
 	}
 	{% endif %}
 	{% if matrix_static_files_file_matrix_client_property_io_element_e2ee_entries_enabled %},

From db7ed0e830e46e032e6ce04f0e85092911a3cfba Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 19 Jan 2024 12:13:22 +0200
Subject: [PATCH 12/28] Fix Traefik load balancer port for
 matrix-mx-puppet-slack

---
 roles/custom/matrix-bridge-mx-puppet-slack/templates/labels.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/custom/matrix-bridge-mx-puppet-slack/templates/labels.j2 b/roles/custom/matrix-bridge-mx-puppet-slack/templates/labels.j2
index aec01387f..0937c9d75 100644
--- a/roles/custom/matrix-bridge-mx-puppet-slack/templates/labels.j2
+++ b/roles/custom/matrix-bridge-mx-puppet-slack/templates/labels.j2
@@ -5,7 +5,7 @@ traefik.enable=true
 traefik.docker.network={{ matrix_mx_puppet_slack_container_labels_traefik_docker_network }}
 {% endif %}
 
-traefik.http.services.matrix-mx-puppet-slack.loadbalancer.server.port={{ matrix_mx_puppet_slack_appservice_address }}
+traefik.http.services.matrix-mx-puppet-slack.loadbalancer.server.port={{ matrix_mx_puppet_slack_appservice_port }}
 
 {% if matrix_mx_puppet_slack_container_labels_public_endpoint_enabled %}
 ############################################################

From f953dd2cd6c8cef1121728077d793bd4c255116f Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 19 Jan 2024 17:02:16 +0200
Subject: [PATCH 13/28] Only strip /hookshot prefix for Hookshot widgetapi

Public URLs are like: `/hookshot/widgetapi/v1/static/`
.. which get translated to requests for: `/widgetapi/v1/static/`

Previously, we were stripping the whole `/hookshot/widgetapi` prefix,
which is wrong.
---
 roles/custom/matrix-bridge-hookshot/defaults/main.yml   | 1 -
 roles/custom/matrix-bridge-hookshot/templates/labels.j2 | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/roles/custom/matrix-bridge-hookshot/defaults/main.yml b/roles/custom/matrix-bridge-hookshot/defaults/main.yml
index 6d9210245..1c1ab4c5c 100644
--- a/roles/custom/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/custom/matrix-bridge-hookshot/defaults/main.yml
@@ -201,7 +201,6 @@ matrix_hookshot_widgets_roomSetupWidget_addOnInvite: false   # noqa var-naming
 #   - fec0::/10
 matrix_hookshot_widgets_disallowedIpRanges: ''   # noqa var-naming
 matrix_hookshot_widgets_internal: "/widgetapi"
-# Default value of matrix_hookshot_widgets_endpoint: "/hookshot/widgetapi"
 matrix_hookshot_widgets_hostname: "{{ matrix_hookshot_public_hostname }}"
 matrix_hookshot_widgets_endpoint: "{{ matrix_hookshot_public_endpoint }}{{ matrix_hookshot_widgets_internal }}"
 matrix_hookshot_widgets_publicUrl: "{{ matrix_hookshot_urlprefix }}{{ matrix_hookshot_widgets_endpoint }}/v1/static"   # noqa var-naming
diff --git a/roles/custom/matrix-bridge-hookshot/templates/labels.j2 b/roles/custom/matrix-bridge-hookshot/templates/labels.j2
index 07f015723..4aa3f6420 100644
--- a/roles/custom/matrix-bridge-hookshot/templates/labels.j2
+++ b/roles/custom/matrix-bridge-hookshot/templates/labels.j2
@@ -83,7 +83,7 @@ traefik.http.routers.matrix-hookshot-appservice.tls.certResolver={{ matrix_hooks
 #                                                          #
 ############################################################
 
-traefik.http.middlewares.matrix-hookshot-widgets-strip-prefix.stripprefix.prefixes={{ matrix_hookshot_widgets_endpoint }}
+traefik.http.middlewares.matrix-hookshot-widgets-strip-prefix.stripprefix.prefixes={{ matrix_hookshot_public_endpoint }}
 
 traefik.http.routers.matrix-hookshot-widgets.rule={{ matrix_hookshot_container_labels_widgets_traefik_rule }}
 traefik.http.routers.matrix-hookshot-widgets.middlewares=matrix-hookshot-widgets-strip-prefix

From 90332f8c3d75c75a53d6a097ddd2c0a5b2f83397 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Fri, 19 Jan 2024 17:08:14 +0200
Subject: [PATCH 14/28] Fix problematic Hookshot redirect for
 /hookshot/widgetapi/v1/static

Hookshot wants a trailing slash for this route.

If we let Hookshot redirect, it goes to `/widgetapi/v1/static/`,
instead of `/hookshot/widgetapi/v1/static/`, so we take this matter into our
own hands.
---
 roles/custom/matrix-bridge-hookshot/defaults/main.yml   | 2 +-
 roles/custom/matrix-bridge-hookshot/templates/labels.j2 | 7 ++++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/roles/custom/matrix-bridge-hookshot/defaults/main.yml b/roles/custom/matrix-bridge-hookshot/defaults/main.yml
index 1c1ab4c5c..e7f46a7cc 100644
--- a/roles/custom/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/custom/matrix-bridge-hookshot/defaults/main.yml
@@ -203,7 +203,7 @@ matrix_hookshot_widgets_disallowedIpRanges: ''   # noqa var-naming
 matrix_hookshot_widgets_internal: "/widgetapi"
 matrix_hookshot_widgets_hostname: "{{ matrix_hookshot_public_hostname }}"
 matrix_hookshot_widgets_endpoint: "{{ matrix_hookshot_public_endpoint }}{{ matrix_hookshot_widgets_internal }}"
-matrix_hookshot_widgets_publicUrl: "{{ matrix_hookshot_urlprefix }}{{ matrix_hookshot_widgets_endpoint }}/v1/static"   # noqa var-naming
+matrix_hookshot_widgets_publicUrl: "{{ matrix_hookshot_urlprefix }}{{ matrix_hookshot_widgets_endpoint }}/v1/static/"   # noqa var-naming
 matrix_hookshot_widgets_branding_widgetTitle: "Hookshot Configuration"   # noqa var-naming
 
 
diff --git a/roles/custom/matrix-bridge-hookshot/templates/labels.j2 b/roles/custom/matrix-bridge-hookshot/templates/labels.j2
index 4aa3f6420..31c035300 100644
--- a/roles/custom/matrix-bridge-hookshot/templates/labels.j2
+++ b/roles/custom/matrix-bridge-hookshot/templates/labels.j2
@@ -83,10 +83,15 @@ traefik.http.routers.matrix-hookshot-appservice.tls.certResolver={{ matrix_hooks
 #                                                          #
 ############################################################
 
+# Redirect `{PREFIX}/widgetapi/v1/static` to `{PREFIX}/widgetapi/v1/static/`.
+# Hookshot does it too, but does not obey the prefix, which leads people elsewhere.
+traefik.http.middlewares.matrix-hookshot-widgets-slashless-redirect.redirectregex.regex=({{ matrix_hookshot_widgets_endpoint | quote }}/v1/static)$
+traefik.http.middlewares.matrix-hookshot-widgets-slashless-redirect.redirectregex.replacement=${1}/
+
 traefik.http.middlewares.matrix-hookshot-widgets-strip-prefix.stripprefix.prefixes={{ matrix_hookshot_public_endpoint }}
 
 traefik.http.routers.matrix-hookshot-widgets.rule={{ matrix_hookshot_container_labels_widgets_traefik_rule }}
-traefik.http.routers.matrix-hookshot-widgets.middlewares=matrix-hookshot-widgets-strip-prefix
+traefik.http.routers.matrix-hookshot-widgets.middlewares=matrix-hookshot-widgets-slashless-redirect,matrix-hookshot-widgets-strip-prefix
 
 {% if matrix_hookshot_container_labels_widgets_traefik_priority | int > 0 %}
 traefik.http.routers.matrix-hookshot-widgets.priority={{ matrix_hookshot_container_labels_widgets_traefik_priority }}

From 0823efe22e5a9878471091db796c07a61ff7e53f Mon Sep 17 00:00:00 2001
From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com>
Date: Fri, 19 Jan 2024 15:31:02 +0000
Subject: [PATCH 15/28] Update vectorim/element-web Docker tag to v1.11.55

---
 roles/custom/matrix-client-element/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/custom/matrix-client-element/defaults/main.yml b/roles/custom/matrix-client-element/defaults/main.yml
index 4fb7b2eeb..305deae19 100644
--- a/roles/custom/matrix-client-element/defaults/main.yml
+++ b/roles/custom/matrix-client-element/defaults/main.yml
@@ -11,7 +11,7 @@ matrix_client_element_container_image_self_build_repo: "https://github.com/eleme
 matrix_client_element_container_image_self_build_low_memory_system_patch_enabled: "{{ ansible_memtotal_mb < 4096 }}"
 
 # renovate: datasource=docker depName=vectorim/element-web
-matrix_client_element_version: v1.11.54
+matrix_client_element_version: v1.11.55
 
 matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:{{ matrix_client_element_version }}"
 matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else matrix_container_global_registry_prefix }}"

From 6c1069fd16a81615ee2f96f38525ec675be7fcd9 Mon Sep 17 00:00:00 2001
From: SirHazza <31993698+SirHazza@users.noreply.github.com>
Date: Fri, 19 Jan 2024 22:46:58 +0000
Subject: [PATCH 16/28] Updated nginx proxy fronting with NPM guide

Updated the 'nginx reverse-proxy fronting' documentation with a guide for Nginx Proxy Manager, as you can't use the pre-existing nginx matrix.conf
---
 examples/reverse-proxies/nginx/README.md | 72 ++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/examples/reverse-proxies/nginx/README.md b/examples/reverse-proxies/nginx/README.md
index 5501cf1e6..246d24ed3 100644
--- a/examples/reverse-proxies/nginx/README.md
+++ b/examples/reverse-proxies/nginx/README.md
@@ -15,3 +15,75 @@ Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modi
 This configuration **disables SSL certificate retrieval**, so you will **need to obtain SSL certificates manually** (e.g. by using [certbot](https://certbot.eff.org/)) and set the appropriate path in `matrix.conf`. In the example nginx configuration, a single certificate is used for all subdomains (`matrix.DOMAIN`, `element.DOMAIN`, etc.). For your setup, may wish to change this and use separate `server` blocks and separate certificate files for each host.
 
 Also note that your copy of the `matrix.conf` file has to be adapted to whatever services you are using. For example, remove `element.domain.com` from the `server_name` list if you don't use [Element](../../../docs/configuring-playbook-client-element.md) web client or add `dimension.domain.com` to it if you do use the [Dimension](../../../docs/configuring-playbook-dimension.md) integration manager.
+
+## Using Nginx Proxy Manager
+
+Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/) provides nginx capabilities but inside a pre-built Docker container. With the ability for managing proxy hosts and automatic SSL certificates via a simple web interface.
+
+If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM has access to ports 443, 80 and 81, but you would also need to **provide access to the fedderation ports** `8448` and `8449`.
+
+
+### Creating proxy hosts in Nginx Proxy Manager
+
+Open the 'Proxy Hosts' page in the NPM web interface and select `Add Proxy Host`, the first being for matrix web traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix web proxy config
+Domain Names: matrix.DOMAIN
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 81
+
+# Custom locations
+# Add one custom location
+Define location: /
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 81
+Custom config:
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Real-IP $remote_addr;
+    client_max_body_size 50M;
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+```
+
+Again, under the 'Proxy Hosts' page select `Add Proxy Host`, this time for your federation traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix Federation proxy config
+Domain Names: matrix.DOMAIN:8448
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 8449
+
+# Custom locations
+# Add one custom location
+Define location: /
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 8449
+Custom config:
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    client_max_body_size 50M;
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+
+# Advanced
+# Allows NPM to listen on the federation port
+Custom Nginx Configuration: listen 8448 ssl http2;
+```
+
+Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.

From 3c7f89624679e2d59a524a9070ba82915cc2f3d5 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 11:10:34 +0200
Subject: [PATCH 17/28] Prevent generic workers being combined with any of the
 other types

Until now, the validation check would only get tripped up
if generic workers are used, combined with at least one EACH
other type of specialized workers.

This means that someone doing this:

```
matrix_synapse_workers_preset: one-of-each
matrix_synapse_workers_client_reader_workers_count: 5
```

.. would not have triggered this safety check.

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100
---
 roles/custom/matrix-synapse/tasks/validate_config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/custom/matrix-synapse/tasks/validate_config.yml b/roles/custom/matrix-synapse/tasks/validate_config.yml
index fdf208e8d..2f1a5e1c0 100644
--- a/roles/custom/matrix-synapse/tasks/validate_config.yml
+++ b/roles/custom/matrix-synapse/tasks/validate_config.yml
@@ -51,7 +51,7 @@
   ansible.builtin.fail:
     msg: >-
       Generic workers should not be mixed with the new specialized worker types (room workers, sync workers, client readers, and federation readers)
-  when: matrix_synapse_workers_generic_workers_count | int > 0 and matrix_synapse_workers_room_workers_count | int > 0 and matrix_synapse_workers_sync_workers_count | int > 0 and matrix_synapse_workers_client_reader_workers_count | int > 0 and matrix_synapse_workers_federation_reader_workers_count | int > 0
+  when: matrix_synapse_workers_generic_workers_count | int > 0 and ((matrix_synapse_workers_room_workers_count | int + matrix_synapse_workers_sync_workers_count | int + matrix_synapse_workers_client_reader_workers_count | int + matrix_synapse_workers_federation_reader_workers_count | int) > 0)
 
 - name: (Deprecation) Catch and report renamed settings
   ansible.builtin.fail:

From 16ca50c6ef4f37759ff7c1fce040958158e9e011 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 11:24:59 +0200
Subject: [PATCH 18/28] Add a few more comments in
 matrix-synapse-reverse-proxy-companion.conf.j2

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100
---
 .../conf.d/matrix-synapse-reverse-proxy-companion.conf.j2   | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2 b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
index b3b8165e8..0dac97120 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/conf.d/matrix-synapse-reverse-proxy-companion.conf.j2
@@ -158,17 +158,23 @@ server {
 		{% endif %}
 
 		{% if room_workers | length > 0 %}
+			# room workers
 			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			# https://tcpipuk.github.io/synapse/deployment/nginx.html#locationsconf
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations, 'room_workers_upstream') }}
 		{% endif %}
 
 		{% if sync_workers | length > 0 %}
+			# sync workers
 			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			# https://tcpipuk.github.io/synapse/deployment/nginx.html#locationsconf
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_sync_worker_client_server_locations, 'sync_workers_upstream') }}
 		{% endif %}
 
 		{% if client_reader_workers | length > 0 %}
+			# client_reader workers
 			# https://tcpipuk.github.io/synapse/deployment/workers.html
+			# https://tcpipuk.github.io/synapse/deployment/nginx.html#locationsconf
 			{{ render_locations_to_upstream(matrix_synapse_reverse_proxy_companion_synapse_client_reader_client_server_locations, 'client_reader_workers_upstream') }}
 		{% endif %}
 

From 7cb33da46ad4645709f8809506f99b8b03aaa232 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 11:35:20 +0200
Subject: [PATCH 19/28] Add some clarification comment in
 matrix-synapse-reverse-proxy-companion/defaults/main.yml

---
 .../matrix-synapse-reverse-proxy-companion/defaults/main.yml   | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
index cebb259eb..f480f2891 100644
--- a/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
+++ b/roles/custom/matrix-synapse-reverse-proxy-companion/defaults/main.yml
@@ -192,7 +192,8 @@ matrix_synapse_reverse_proxy_companion_synapse_client_api_additional_server_conf
 matrix_synapse_reverse_proxy_companion_synapse_federation_api_additional_server_configuration_blocks: []
 
 
-# synapse worker activation and endpoint mappings
+# synapse worker activation and endpoint mappings.
+# These are all populated via Ansible group variables.
 matrix_synapse_reverse_proxy_companion_synapse_workers_enabled: false
 matrix_synapse_reverse_proxy_companion_synapse_workers_list: []
 matrix_synapse_reverse_proxy_companion_synapse_room_worker_client_server_locations: []

From 84446e52e983f9cf1a1441f980d55773406b0a8c Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 12:39:20 +0200
Subject: [PATCH 20/28] Rename Synapse worker preset name (room-workers ->
 specialized-workers)

I believe `specialized-workers` is a better name than `room-workers`,
because when enabled, 4 different types of specialized workers are
created:

- Room workers
- Sync workers
- Client readers
- Federation readers

Only one of these is called room-workers.

In the future, more specialized workers may be added, making the
`room-workers` preset name an even poorer choice.

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100
---
 roles/custom/matrix-synapse/defaults/main.yml |  2 +-
 roles/custom/matrix-synapse/tasks/init.yml    | 11 +++++++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/roles/custom/matrix-synapse/defaults/main.yml b/roles/custom/matrix-synapse/defaults/main.yml
index 84bc9ff8a..ac382622b 100644
--- a/roles/custom/matrix-synapse/defaults/main.yml
+++ b/roles/custom/matrix-synapse/defaults/main.yml
@@ -706,7 +706,7 @@ matrix_synapse_workers_presets:
     stream_writer_account_data_stream_workers_count: 1
     stream_writer_receipts_stream_workers_count: 1
     stream_writer_presence_stream_workers_count: 1
-  room-workers:
+  specialized-workers:
     room_workers_count: 1
     sync_workers_count: 1
     client_reader_workers_count: 1
diff --git a/roles/custom/matrix-synapse/tasks/init.yml b/roles/custom/matrix-synapse/tasks/init.yml
index 234eb78e5..341350a49 100644
--- a/roles/custom/matrix-synapse/tasks/init.yml
+++ b/roles/custom/matrix-synapse/tasks/init.yml
@@ -1,5 +1,16 @@
 ---
 
+# This validation task is here, not in validate_config.yml,
+# because init.yml runs before it.
+#
+# validate_config.yml aims to validate the configuration based on the work we do,
+# so we can't change the order.
+- name: Fail when using the old (renamed) room-workers preset
+  ansible.builtin.fail:
+    msg: >-
+      The `room-workers` preset has been renamed to `specialized-workers`. Update your `matrix_synapse_workers_preset` variable to use the new name.
+  when: matrix_synapse_workers_preset == 'room-workers'
+
 # Unless `matrix_synapse_workers_enabled_list` is explicitly defined,
 # we'll generate it dynamically.
 - ansible.builtin.include_tasks: "{{ role_path }}/tasks/synapse/workers/init.yml"

From 9fb2d53b542820165295b526fd6bfe257b0afdd5 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 12:41:21 +0200
Subject: [PATCH 21/28] Rework Synapse workers documentation

Related to: https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100
---
 docs/configuring-playbook-synapse.md          | 53 +++++++++++++++++--
 roles/custom/matrix-synapse/defaults/main.yml |  3 +-
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/docs/configuring-playbook-synapse.md b/docs/configuring-playbook-synapse.md
index e9a3c3520..e99a56e7f 100644
--- a/docs/configuring-playbook-synapse.md
+++ b/docs/configuring-playbook-synapse.md
@@ -20,22 +20,65 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
 
 ## Load balancing with workers
 
-To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md).
+To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
 
 To enable Synapse worker support, update your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
 
 ```yaml
 matrix_synapse_workers_enabled: true
+
+matrix_synapse_workers_preset: one-of-each
 ```
 
-We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration):
-- `little-federation-helper` - a very minimal worker configuration to improve federation performance
-- `one-of-each` - one worker of each supported type
+By default, this enables the `one-of-each` [worker preset](#worker-presets), but you may wish to use another preset or [control the number of worker instances](#controlling-the-number-of-worker-instances).
+
+### Worker presets
+
+We support a few configuration presets (`matrix_synapse_workers_preset: one-of-each` being the default configuration right now):
+
+- (federation-only) `little-federation-helper` - a very minimal worker configuration to improve federation performance
+- (generic) `one-of-each` - defaults to one worker of each supported type - no smart routing, just generic workers
+- (specialized) `specialized-workers` - defaults to one worker of each supported type, but disables generic workers and uses [specialized workers](#specialized-workers) instead
+
+These presets represent a few common configurations. There are many worker types which can be mixed and matched based on your needs.
+
+#### Generic workers
+
+Previously, the playbook only supported the most basic type of load-balancing. We call it **generic load-balancing** below, because incoming HTTP requests are sent to a generic worker. Load-balancing was done based on the requestor's IP address. This is simple, but not necessarily optimal. If you're accessing your account from multiple IP addresses (e.g. your mobile phone being on a different network than your PC), these separate requests may potentially be routed to different workers, each of which would need to cache roughly the same data.
+
+This is **still the default load-balancing method (preset) used by the playbook**.
+
+To use generic load-balancing, do not specify `matrix_synapse_workers_preset` to make it use the default value (`one-of-each`), or better yet - explicitly set it as `one-of-each`.
+
+You may also consider [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
 
-If you'd like more customization power, you can start with one of the presets and tweak various `matrix_synapse_workers_*_count` variables manually.
+#### Specialized workers
+
+The playbook now supports a smarter **specialized load-balancing** inspired by [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). Instead of routing requests to one or more [generic workers](#generic-workers) based only on the requestor's IP adddress, specialized load-balancing routes to **4 different types of specialized workers** based on **smarter criteria** - the access token (username) of the requestor and/or on the resource (room, etc.) being requested.
+
+The playbook supports these **4 types** of specialized workers:
+
+- Room workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) & [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs dedicated to handling specific rooms
+- Sync workers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs related to synchronization (most notably [the `/sync` endpoint](https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3sync))
+- Client readers - handles various [Client-Server](https://spec.matrix.org/v1.9/client-server-api/) APIs which are not for specific rooms (handled by **room workers**) or for synchronization (handled by **sync workers**)
+- Federation readers - handles various [Federation](https://spec.matrix.org/v1.9/server-server-api) APIs which are not for specific rooms (handled by **room workers**)
+
+To use specialized load-balancing, consider enabling the `specialized-workers` [worker preset](#worker-presets) and potentially [tweaking the number of workers of each type](#controlling-the-number-of-worker-instances) from the default (one of each).
+
+#### Controlling the number of worker instances
+
+If you'd like more customization power, you can start with one of the [worker presets](#worker-presets) and then tweak various `matrix_synapse_workers_*_count` variables manually.
+
+To find what variables are available for you to override in your own `vars.yml` configuration file, see the [`defaults/main.yml` file for the `matrix-synapse` Ansible role](../roles/custom/matrix-synapse/defaults/main.yml).
+
+The only thing you **cannot** do is mix [generic workers](#generic-workers) and [specialized workers](#specialized-workers).
+
+#### Effect of enabling workers on the rest of your server
 
 When Synapse workers are enabled, the integrated [Postgres database is tuned](maintenance-postgres.md#tuning-postgresql), so that the maximum number of Postgres connections are increased from `200` to `500`. If you need to decrease or increase the number of maximum Postgres connections further, use the `devture_postgres_max_connections` variable.
 
+A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component handles load-balancing for workers. This role/component is automatically enabled when you enable workers. Make sure to use the `setup-all` tag (not `install-all`!) during the playbook's [installation](./installing.md) process, especially if you're disabling workers, so that components may be installed/uninstalled correctly.
+
 In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/matrix-org/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
 
 
diff --git a/roles/custom/matrix-synapse/defaults/main.yml b/roles/custom/matrix-synapse/defaults/main.yml
index ac382622b..dd4ac05a2 100644
--- a/roles/custom/matrix-synapse/defaults/main.yml
+++ b/roles/custom/matrix-synapse/defaults/main.yml
@@ -663,7 +663,8 @@ matrix_synapse_workers_enabled: false
 #
 # The posible values (as seen in `matrix_synapse_workers_presets`) are:
 # - "little-federation-helper" - a very minimal worker configuration to improve federation performance
-# - "one-of-each" - one worker of each supported type
+# - "one-of-each" - one worker of each supported type + a generic worker
+# - "specialized-workers" - one worker of each supported type + specialized workers
 #
 # You can override `matrix_synapse_workers_presets` to define your own presets, which is ill-advised, because it's fragile.
 # To use a more custom configuration, start with one of these presets as a base and configure `matrix_synapse_workers_*_count` variables manually, to suit your liking.

From 24394d3ec42b5381e2fcd0f671b88cd7cc35beca Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 12:41:46 +0200
Subject: [PATCH 22/28] Announce support for specialized Synapse workers

Related to https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100
---
 CHANGELOG.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7bb44f665..aecd10d5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,16 @@
+# 2024-01-20
+
+## Support for more efficient (specialized) Synapse workers
+
+Thanks to [Charles Wright](https://github.com/cvwright) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook has [received support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100) for load-balancing the Synapse workload via [specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) which are supposed to work better than our old [generic workers]((./docs/configuring-playbook-synapse.md#generic-workers)) implementation.
+
+For now, playbook defaults remain unchanged and the `one-of-each` [workers preset](./docs/configuring-playbook-synapse.md#worker-presets) continues being the default. However, the default may change in the future. If you'd like to remain on this preset even if/when the defaults change, consider explicitly adding `matrix_synapse_workers_preset: one-of-each` to your `vars.yml` configuration.
+
+Our specialized workers setup is based on recommendations found in [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html). What's special about our new setup is that we try to parse information out of the request (who the user is; which room is being operated on) and try to forward similar requests to the same worker. As an example, this means that once a worker caches some room information, subsequent requests for the same room will be routed to the same worker (which supposedly still has the room's state cached).
+
+To get started, refer to our [Specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) documentation section.
+
+
 # 2024-01-17
 
 ## Switching to Element's AGPLv3-licensed Synapse release

From 9a7cb0f716e0ea73cf956ca84e736ab37b6e29bf Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 12:45:10 +0200
Subject: [PATCH 23/28] Fix broken link in changelog entry

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aecd10d5b..0e8ece22b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 ## Support for more efficient (specialized) Synapse workers
 
-Thanks to [Charles Wright](https://github.com/cvwright) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook has [received support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100) for load-balancing the Synapse workload via [specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) which are supposed to work better than our old [generic workers]((./docs/configuring-playbook-synapse.md#generic-workers)) implementation.
+Thanks to [Charles Wright](https://github.com/cvwright) from [FUTO](https://www.futo.org/), the creators of the [Circles app](https://circu.li/), the playbook has [received support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3100) for load-balancing the Synapse workload via [specialized workers](./docs/configuring-playbook-synapse.md#specialized-workers) which are supposed to work better than our old [generic workers](./docs/configuring-playbook-synapse.md#generic-workers) implementation.
 
 For now, playbook defaults remain unchanged and the `one-of-each` [workers preset](./docs/configuring-playbook-synapse.md#worker-presets) continues being the default. However, the default may change in the future. If you'd like to remain on this preset even if/when the defaults change, consider explicitly adding `matrix_synapse_workers_preset: one-of-each` to your `vars.yml` configuration.
 

From f10bc264da3f9323f9487d0e45d4db27caf7c0e2 Mon Sep 17 00:00:00 2001
From: Pierre 'McFly' Marty <paq.marty@gmail.com>
Date: Sat, 20 Jan 2024 12:58:14 +0100
Subject: [PATCH 24/28] chore(deps): update Telegrambot config

---
 group_vars/matrix_servers                     |   1 +
 .../defaults/main.yml                         |   8 +
 .../templates/config.yaml.j2                  | 366 +++++++++++++++---
 3 files changed, 312 insertions(+), 63 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index b97da1813..19da2c483 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1331,6 +1331,7 @@ matrix_mautrix_telegram_container_labels_metrics_middleware_basic_auth_users: "{
 
 matrix_mautrix_telegram_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'telegr.as.token', rounds=655555) | to_uuid }}"
 
+matrix_mautrix_telegram_homeserver_domain: "{{ matrix_domain }}"
 matrix_mautrix_telegram_homeserver_address: "{{ matrix_addons_homeserver_client_api_url }}"
 matrix_mautrix_telegram_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'telegr.hs.token', rounds=655555) | to_uuid }}"
 
diff --git a/roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml b/roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml
index 04ea86411..863e3a012 100644
--- a/roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml
+++ b/roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml
@@ -1,3 +1,9 @@
+# File              : roles/custom/matrix-bridge-mautrix-telegram/defaults/main.yml
+# Author            : Pierre (McFly) Marty <paq.marty@gmail.com>
+# Date              : 17.01.2024
+# Last Modified Date: 17.01.2024
+# Last Modified By  : Pierre (McFly) Marty <paq.marty@gmail.com>
+# -----
 ---
 # mautrix-telegram is a Matrix <-> Telegram bridge
 # Project source code URL: https://github.com/mautrix/telegram
@@ -175,6 +181,8 @@ matrix_mautrix_telegram_appservice_database: "{{
 
 # Can be set to enable automatic double-puppeting via Shared Secret Auth (https://github.com/devture/matrix-synapse-shared-secret-auth).
 matrix_mautrix_telegram_login_shared_secret: ''
+matrix_mautrix_telegram_bridge_login_shared_secret_map:
+   "{{ {matrix_mautrix_telegram_homeserver_domain: matrix_mautrix_telegram_login_shared_secret} if matrix_mautrix_telegram_login_shared_secret else {}  }}"
 
 # Default configuration template which covers the generic use case.
 # You can customize it by controlling the various variables inside it.
diff --git a/roles/custom/matrix-bridge-mautrix-telegram/templates/config.yaml.j2 b/roles/custom/matrix-bridge-mautrix-telegram/templates/config.yaml.j2
index 350ac31d5..30145b0e0 100644
--- a/roles/custom/matrix-bridge-mautrix-telegram/templates/config.yaml.j2
+++ b/roles/custom/matrix-bridge-mautrix-telegram/templates/config.yaml.j2
@@ -8,6 +8,20 @@ homeserver:
     # Whether or not to verify the SSL certificate of the homeserver.
     # Only applies if address starts with https://
     verify_ssl: true
+    # What software is the homeserver running?
+    # Standard Matrix homeservers like Synapse, Dendrite and Conduit should just use "standard" here.
+    software: standard
+    # Number of retries for all HTTP requests if the homeserver isn't reachable.
+    http_retry_count: 4
+    # The URL to push real-time bridge status to.
+    # If set, the bridge will make POST requests to this URL whenever a user's Telegram connection state changes.
+    # The bridge will use the appservice as_token to authorize requests.
+    status_endpoint: null
+    # Endpoint for reporting per-message status.
+    message_send_checkpoint_endpoint: null
+    # Whether asynchronous uploads via MSC2246 should be enabled for media.
+    # Requires a media repo that supports MSC2246.
+    async_media: false
 
 # Application service host/registration related details
 # Changing these values requires regeneration of the registration.
@@ -22,12 +36,19 @@ appservice:
     # Usually 1 is enough, but on high-traffic bridges you might need to increase this to avoid 413s
     max_body_size: 1
 
-    # The full URI to the database. SQLite and Postgres are fully supported.
-    # Other DBMSes supported by SQLAlchemy may or may not work.
+    # The full URI to the database. SQLite and Postgres are supported.
     # Format examples:
-    #   SQLite:   sqlite:///filename.db
+    #   SQLite:   sqlite:filename.db
     #   Postgres: postgres://username:password@hostname/dbname
     database: {{ matrix_mautrix_telegram_appservice_database|to_json }}
+    # Additional arguments for asyncpg.create_pool() or sqlite3.connect()
+    # https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.pool.create_pool
+    # https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
+    # For sqlite, min_size is used as the connection thread pool size and max_size is ignored.
+    # Additionally, SQLite supports init_commands as an array of SQL queries to run on connect (e.g. to set PRAGMAs).
+    database_opts:
+        min_size: 1
+        max_size: 10
 
     # Public part of web server for out-of-Matrix interaction with the bridge.
     # Used for things like login if the user wants to make sure the 2FA password isn't stored in
@@ -61,6 +82,11 @@ appservice:
     bot_displayname: Telegram bridge bot
     bot_avatar: mxc://maunium.net/tJCRmUyJDsgRNgqhOgoiHWbX
 
+    # Whether or not to receive ephemeral events via appservice transactions.
+    # Requires MSC2409 support (i.e. Synapse 1.22+).
+    # You should disable bridge -> sync_with_custom_puppets when this is enabled.
+    ephemeral_events: true
+
     # Authentication tokens for AS <-> HS communication.
     as_token: {{ matrix_mautrix_telegram_appservice_token|to_json }}
     hs_token: {{ matrix_mautrix_telegram_homeserver_token|to_json }}
@@ -70,6 +96,17 @@ metrics:
     enabled: {{ matrix_mautrix_telegram_metrics_enabled | to_json }}
     listen_port: 8000
 
+# Manhole config.
+manhole:
+    # Whether or not opening the manhole is allowed.
+    enabled: false
+    # The path for the unix socket.
+    path: /var/tmp/mautrix-telegram.manhole
+    # The list of UIDs who can be added to the whitelist.
+    # If empty, any UIDs can be specified in the open-manhole command.
+    whitelist:
+    - 0
+
 # Bridge config
 bridge:
     # Localpart template of MXIDs for Telegram users.
@@ -105,12 +142,23 @@ bridge:
     - phone number
     # Maximum length of displayname
     displayname_max_length: 100
+    # Remove avatars from Telegram ghost users when removed on Telegram. This is disabled by default
+    # as there's no way to determine whether an avatar is removed or just hidden from some users. If
+    # you're on a single-user instance, this should be safe to enable.
+    allow_avatar_remove: false
+    # Should contact names and profile pictures be allowed?
+    # This is only safe to enable on single-user instances.
+    allow_contact_info: false
 
     # Maximum number of members to sync per portal when starting up. Other members will be
     # synced when they send messages. The maximum is 10000, after which the Telegram server
     # will not send any more members.
-    # Defaults to no local limit (-> limited to 10000 by server)
-    max_initial_member_sync: 10
+    # -1 means no limit (which means it's limited to 10000 by the server)
+    max_initial_member_sync: 100
+    # Maximum number of participants in chats to bridge. Only applies when the portal is being created.
+    # If there are more members when trying to create a room, the room creation will be cancelled.
+    # -1 means no limit (which means all chats can be bridged)
+    max_member_count: -1
     # Whether or not to sync the member list in channels.
     # If no channel admins have logged into the bridge, the bridge won't be able to sync the member
     # list regardless of this setting.
@@ -119,11 +167,16 @@ bridge:
     skip_deleted_members: true
     # Whether or not to automatically synchronize contacts and chats of Matrix users logged into
     # their Telegram account at startup.
-    startup_sync: true
+    startup_sync: false
     # Number of most recently active dialogs to check when syncing chats.
-    # Dialogs include groups and private chats, but only groups are synced.
     # Set to 0 to remove limit.
-    sync_dialog_limit: 30
+    sync_update_limit: 0
+    # Number of most recently active dialogs to create portals for when syncing chats.
+    # Set to 0 to remove limit.
+    sync_create_limit: 15
+    # Should all chats be scheduled to be created later?
+    # This is best used in combination with MSC2716 infinite backfill.
+    sync_deferred_create_all: false
     # Whether or not to sync and create portals for direct chats at startup.
     sync_direct_chats: false
     # The maximum number of simultaneous Telegram deletions to handle.
@@ -135,52 +188,76 @@ bridge:
     # Allow logging in within Matrix. If false, users can only log in using login-qr or the
     # out-of-Matrix login website (see appservice.public config section)
     allow_matrix_login: true
-    # Whether or not to bridge plaintext highlights.
-    # Only enable this if your displayname_template has some static part that the bridge can use to
-    # reliably identify what is a plaintext highlight.
-    plaintext_highlights: false
     # Whether or not to make portals of publicly joinable channels/supergroups publicly joinable on Matrix.
-    public_portals: true
-    # Whether or not to use /sync to get presence, read receipts and typing notifications when using
-    # your own Matrix account as the Matrix puppet for your Telegram account.
-    sync_with_custom_puppets: true
-    # Shared secret for https://github.com/devture/matrix-synapse-shared-secret-auth
+    public_portals: false
+    # Whether or not to use /sync to get presence, read receipts and typing notifications
+    # when double puppeting is enabled
+    sync_with_custom_puppets: false
+    # Whether or not to update the m.direct account data event when double puppeting is enabled.
+    # Note that updating the m.direct event is not atomic (except with mautrix-asmux)
+    # and is therefore prone to race conditions.
+    sync_direct_chat_list: false
+    # Servers to always allow double puppeting from
+    double_puppet_server_map:
+        "{{ matrix_mautrix_telegram_homeserver_domain  }}": {{ matrix_mautrix_telegram_homeserver_address  }}
+    # Allow using double puppeting from any server with a valid client .well-known file.
+    double_puppet_allow_discovery: false
+    # Shared secrets for https://github.com/devture/matrix-synapse-shared-secret-auth
     #
     # If set, custom puppets will be enabled automatically for local users
     # instead of users having to find an access token and run `login-matrix`
     # manually.
-    login_shared_secret: {{ matrix_mautrix_telegram_login_shared_secret|to_json }}
+    # If using this for other servers than the bridge's server,
+    # you must also set the URL in the double_puppet_server_map.
+    login_shared_secret_map: {{ matrix_mautrix_telegram_bridge_login_shared_secret_map|to_json  }}
     # Set to false to disable link previews in messages sent to Telegram.
     telegram_link_preview: true
-    # Use inline images instead of a separate message for the caption.
-    # N.B. Inline images are not supported on all clients (e.g. Element iOS).
-    inline_images: false
+    # Whether or not the !tg join command should do a HTTP request
+    # to resolve redirects in invite links.
+    invite_link_resolve: false
+    # Send captions in the same message as images. This will send data compatible with both MSC2530 and MSC3552.
+    # This is currently not supported in most clients.
+    caption_in_message: false
     # Maximum size of image in megabytes before sending to Telegram as a document.
     image_as_file_size: 10
-    # Maximum size of Telegram documents in megabytes to bridge.
-    max_document_size: 100
+    # Maximum number of pixels in an image before sending to Telegram as a document. Defaults to 4096x4096 = 16777216.
+    image_as_file_pixels: 16777216
     # Enable experimental parallel file transfer, which makes uploads/downloads much faster by
     # streaming from/to Matrix and using many connections for Telegram.
     # Note that generating HQ thumbnails for videos is not possible with streamed transfers.
+    # This option uses internal Telethon implementation details and may break with minor updates.
     parallel_file_transfer: false
     # Whether or not created rooms should have federation enabled.
     # If false, created portal rooms will never be federated.
     federate_rooms: {{ matrix_mautrix_telegram_federate_rooms|to_json }}
+    # Should the bridge send all unicode reactions as custom emoji reactions to Telegram?
+    # By default, the bridge only uses custom emojis for unicode emojis that aren't allowed in reactions.
+    always_custom_emoji_reaction: false
     # Settings for converting animated stickers.
     animated_sticker:
         # Format to which animated stickers should be converted.
         # disable - No conversion, send as-is (gzipped lottie)
         # png - converts to non-animated png (fastest),
-        # gif - converts to animated gif, but loses transparency
+        # gif - converts to animated gif
         # webm - converts to webm video, requires ffmpeg executable with vp9 codec and webm container support
+        # webp - converts to animated webp, requires ffmpeg executable with webp codec/container support
         target: gif
+        # Should video stickers be converted to the specified format as well?
+        convert_from_webm: false
         # Arguments for converter. All converters take width and height.
-        # GIF converter takes background as a hex color.
         args:
             width: 256
             height: 256
-            background: "020202"  # only for gif
-            fps: 30               # only for webm
+            fps: 25 # only for webm, webp and gif (2, 5, 10, 20 or 25 recommended)
+    # Settings for converting animated emoji.
+    # Same as animated_sticker, but webm is not supported as the target
+    # (because inline images can only contain images, not videos).
+    animated_emoji:
+        target: webp
+        args:
+            width: 64
+            height: 64
+            fps: 25
     # End-to-bridge encryption support options.
     #
     # See https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html for more info.
@@ -190,32 +267,164 @@ bridge:
         # Default to encryption, force-enable encryption in all portals the bridge creates
         # This will cause the bridge bot to be in private chats for the encryption to work properly.
         default: {{ matrix_mautrix_telegram_bridge_encryption_default|to_json }}
-        # Database for the encryption data. If set to `default`, will use the appservice database.
-        database: default
-        # Options for automatic key sharing.
-        key_sharing:
-            # Enable key sharing? If enabled, key requests for rooms where users are in will be fulfilled.
-            # You must use a client that supports requesting keys from other users to use this feature.
-            allow: {{ matrix_mautrix_telegram_bridge_encryption_key_sharing_allow|to_json }}
-            # Require the requesting device to have a valid cross-signing signature?
-            # This doesn't require that the bridge has verified the device, only that the user has verified it.
-            # Not yet implemented.
-            require_cross_signing: false
-            # Require devices to be verified by the bridge?
-            # Verification by the bridge is not yet implemented.
-            require_verification: true
-    # Whether or not to explicitly set the avatar and room name for private
-    # chat portal rooms. This will be implicitly enabled if encryption.default is true.
-    private_chat_portal_meta: false
+        # Whether to use MSC2409/MSC3202 instead of /sync long polling for receiving encryption-related data.
+        appservice: false
+        # Require encryption, drop any unencrypted messages.
+        require: false
+        # Enable key sharing? If enabled, key requests for rooms where users are in will be fulfilled.
+        # You must use a client that supports requesting keys from other users to use this feature.
+        allow_key_sharing: {{ matrix_mautrix_telegram_bridge_encryption_key_sharing_allow|to_json }}
+        # Options for deleting megolm sessions from the bridge.
+        delete_keys:
+            # Beeper-specific: delete outbound sessions when hungryserv confirms
+            # that the user has uploaded the key to key backup.
+            delete_outbound_on_ack: false
+            # Don't store outbound sessions in the inbound table.
+            dont_store_outbound: false
+            # Ratchet megolm sessions forward after decrypting messages.
+            ratchet_on_decrypt: false
+            # Delete fully used keys (index >= max_messages) after decrypting messages.
+            delete_fully_used_on_decrypt: false
+            # Delete previous megolm sessions from same device when receiving a new one.
+            delete_prev_on_new_session: false
+            # Delete megolm sessions received from a device when the device is deleted.
+            delete_on_device_delete: false
+            # Periodically delete megolm sessions when 2x max_age has passed since receiving the session.
+            periodically_delete_expired: false
+            # Delete inbound megolm sessions that don't have the received_at field used for
+            # automatic ratcheting and expired session deletion. This is meant as a migration
+            # to delete old keys prior to the bridge update.
+            delete_outdated_inbound: false
+        # What level of device verification should be required from users?
+        #
+        # Valid levels:
+        #   unverified - Send keys to all device in the room.
+        #   cross-signed-untrusted - Require valid cross-signing, but trust all cross-signing keys.
+        #   cross-signed-tofu - Require valid cross-signing, trust cross-signing keys on first use (and reject changes).
+        #   cross-signed-verified - Require valid cross-signing, plus a valid user signature from the bridge bot.
+        #                           Note that creating user signatures from the bridge bot is not currently possible.
+        #   verified - Require manual per-device verification
+        #              (currently only possible by modifying the `trust` column in the `crypto_device` database table).
+        verification_levels:
+            # Minimum level for which the bridge should send keys to when bridging messages from Telegram to Matrix.
+            receive: unverified
+            # Minimum level that the bridge should accept for incoming Matrix messages.
+            send: unverified
+            # Minimum level that the bridge should require for accepting key requests.
+            share: cross-signed-tofu
+        # Options for Megolm room key rotation. These options allow you to
+        # configure the m.room.encryption event content. See:
+        # https://spec.matrix.org/v1.3/client-server-api/#mroomencryption for
+        # more information about that event.
+        rotation:
+            # Enable custom Megolm room key rotation settings. Note that these
+            # settings will only apply to rooms created after this option is
+            # set.
+            enable_custom: false
+            # The maximum number of milliseconds a session should be used
+            # before changing it. The Matrix spec recommends 604800000 (a week)
+            # as the default.
+            milliseconds: 604800000
+            # The maximum number of messages that should be sent with a given a
+            # session before changing it. The Matrix spec recommends 100 as the
+            # default.
+            messages: 100
+
+            # Disable rotating keys when a user's devices change?
+            # You should not enable this option unless you understand all the implications.
+            disable_device_change_key_rotation: false
+
+    # Whether to explicitly set the avatar and room name for private chat portal rooms.
+    # If set to `default`, this will be enabled in encrypted rooms and disabled in unencrypted rooms.
+    # If set to `always`, all DM rooms will have explicit names and avatars set.
+    # If set to `never`, DM rooms will never have names and avatars set.
+    private_chat_portal_meta: default
+    # Disable generating reply fallbacks? Some extremely bad clients still rely on them,
+    # but they're being phased out and will be completely removed in the future.
+    disable_reply_fallbacks: false
+    # Should cross-chat replies from Telegram be bridged? Most servers and clients don't support this.
+    cross_room_replies: false
     # Whether or not the bridge should send a read receipt from the bridge bot when a message has
     # been sent to Telegram.
     delivery_receipts: false
     # Whether or not delivery errors should be reported as messages in the Matrix room.
-    delivery_error_reports: true
+    delivery_error_reports: false
+    # Should errors in incoming message handling send a message to the Matrix room?
+    incoming_bridge_error_reports: false
+    # Whether the bridge should send the message status as a custom com.beeper.message_send_status event.
+    message_status_events: false
     # Set this to true to tell the bridge to re-send m.bridge events to all rooms on the next run.
     # This field will automatically be changed back to false after it,
     # except if the config file is not writable.
     resend_bridge_info: false
+    # When using double puppeting, should muted chats be muted in Matrix?
+    mute_bridging: false
+    # When using double puppeting, should pinned chats be moved to a specific tag in Matrix?
+    # The favorites tag is `m.favourite`.
+    pinned_tag: null
+    # Same as above for archived chats, the low priority tag is `m.lowpriority`.
+    archive_tag: null
+    # Whether or not mute status and tags should only be bridged when the portal room is created.
+    tag_only_on_create: true
+    # Should leaving the room on Matrix make the user leave on Telegram?
+    bridge_matrix_leave: true
+    # Should the user be kicked out of all portals when logging out of the bridge?
+    kick_on_logout: true
+    # Should the "* user joined Telegram" notice always be marked as read automatically?
+    always_read_joined_telegram_notice: true
+    # Should the bridge auto-create a group chat on Telegram when a ghost is invited to a room?
+    # Requires the user to have sufficient power level and double puppeting enabled.
+    create_group_on_invite: true
+    # Settings for backfilling messages from Telegram.
+    backfill:
+        # Allow backfilling at all?
+        enable: true
+        # Whether or not to enable backfilling in normal groups.
+        # Normal groups have numerous technical problems in Telegram, and backfilling normal groups
+        # will likely cause problems if there are multiple Matrix users in the group.
+        normal_groups: false
+
+        # If a backfilled chat is older than this number of hours, mark it as read even if it's unread on Telegram.
+        # Set to -1 to let any chat be unread.
+        unread_hours_threshold: 720
+
+        # Forward backfilling limits.
+        #
+        # Using a negative initial limit is not recommended, as it would try to backfill everything in a single batch.
+        forward_limits:
+            # Number of messages to backfill immediately after creating a portal.
+            initial:
+                user: 50
+                normal_group: 100
+                supergroup: 10
+                channel: 10
+            # Number of messages to backfill when syncing chats.
+            sync:
+                user: 100
+                normal_group: 100
+                supergroup: 100
+                channel: 100
+        # Timeout for forward backfills in seconds. If you have a high limit, you'll have to increase this too.
+        forward_timeout: 900
+
+        # Settings for incremental backfill of history. These only apply to Beeper, as upstream abandoned MSC2716.
+        incremental:
+            # Maximum number of messages to backfill per batch.
+            messages_per_batch: 100
+            # The number of seconds to wait after backfilling the batch of messages.
+            post_batch_delay: 20
+            # The maximum number of batches to backfill per portal, split by the chat type.
+            # If set to -1, all messages in the chat will eventually be backfilled.
+            max_batches:
+                # Direct chats
+                user: -1
+                # Normal groups. Note that the normal_groups option above must be enabled
+                # for these to be backfilled.
+                normal_group: -1
+                # Supergroups
+                supergroup: 10
+                # Broadcast channels
+                channel: -1
 
     # Overrides for base power levels.
     initial_power_level_overrides:
@@ -232,24 +441,28 @@ bridge:
         #      notices from users listed here will be bridged.
         exceptions: []
 
+    # An array of possible values for the $distinguisher variable in message formats.
+    # Each user gets one of the values here, based on a hash of their user ID.
+    # If the array is empty, the $distinguisher variable will also be empty.
+    relay_user_distinguishers: ["🟦", "🟣", "🟩", "⭕️", "🔶", "⬛️", "🔵", "🟢"]
     # The formats to use when sending messages to Telegram via the relay bot.
-    #
-    # Telegram doesn't have built-in emotes, so the m.emote format is also used for non-relaybot users.
+    # Text msgtypes (m.text, m.notice and m.emote) support HTML, media msgtypes don't.
     #
     # Available variables:
-    #   $sender_displayname    - The display name of the sender (e.g. Example User)
-    #   $sender_username       - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
-    #   $sender_mxid           - The Matrix ID of the sender (e.g. @exampleuser:example.com)
-    #   $message               - The message content as HTML
+    #   $sender_displayname - The display name of the sender (e.g. Example User)
+    #   $sender_username    - The username (Matrix ID localpart) of the sender (e.g. exampleuser)
+    #   $sender_mxid        - The Matrix ID of the sender (e.g. @exampleuser:example.com)
+    #   $distinguisher      - A random string from the options in the relay_user_distinguishers array.
+    #   $message            - The message content
     message_formats:
-        m.text: "<b>$sender_displayname</b>: $message"
-        m.notice: "<b>$sender_displayname</b>: $message"
-        m.emote: "* <b>$sender_displayname</b> $message"
-        m.file: "<b>$sender_displayname</b> sent a file: $message"
-        m.image: "<b>$sender_displayname</b> sent an image: $message"
-        m.audio: "<b>$sender_displayname</b> sent an audio file: $message"
-        m.video: "<b>$sender_displayname</b> sent a video: $message"
-        m.location: "<b>$sender_displayname</b> sent a location: $message"
+        m.text: "$distinguisher <b>$sender_displayname</b>: $message"
+        m.notice: "$distinguisher <b>$sender_displayname</b>: $message"
+        m.emote: "* $distinguisher <b>$sender_displayname</b> $message"
+        m.file: "$distinguisher <b>$sender_displayname</b> sent a file: $message"
+        m.image: "$distinguisher <b>$sender_displayname</b> sent an image: $message"
+        m.audio: "$distinguisher <b>$sender_displayname</b> sent an audio file: $message"
+        m.video: "$distinguisher <b>$sender_displayname</b> sent a video: $message"
+        m.location: "$distinguisher <b>$sender_displayname</b> sent a location: $message"
     # Telegram doesn't have built-in emotes, this field specifies how m.emote's from authenticated
     # users are sent to telegram. All fields in message_formats are supported. Additionally, the
     # Telegram user info is available in the following variables:
@@ -265,14 +478,13 @@ bridge:
     #
     # Set format to an empty string to disable the messages for that event.
     state_event_formats:
-        join: "<b>$displayname</b> joined the room."
-        leave: "<b>$displayname</b> left the room."
-        name_change: "<b>$prev_displayname</b> changed their name to <b>$displayname</b>"
+        join: "$distinguisher <b>$displayname</b> joined the room."
+        leave: "$distinguisher <b>$displayname</b> left the room."
+        name_change: "$distinguisher <b>$prev_displayname</b> changed their name to $distinguisher <b>$displayname</b>"
 
     # Filter rooms that can/can't be bridged. Can also be managed using the `filter` and
     # `filter-mode` management commands.
     #
-    # Filters do not affect direct chats.
     # An empty blacklist will essentially disable the filter.
     filter:
         # Filter mode to use. Either "blacklist" or "whitelist".
@@ -281,10 +493,30 @@ bridge:
         mode: {{ matrix_mautrix_telegram_filter_mode | to_json }}
         # The list of group/channel IDs to filter.
         list: []
+        # How to handle direct chats:
+        # If users is "null", direct chats will follow the previous settings.
+        # If users is "true", direct chats will always be bridged.
+        # If users is "false", direct chats will never be bridged.
+        users: true
 
     # The prefix for commands. Only required in non-management rooms.
     command_prefix: {{ matrix_mautrix_telegram_command_prefix | to_json }}
 
+    # Messages sent upon joining a management room.
+    # Markdown is supported. The defaults are listed below.
+    management_room_text:
+        # Sent when joining a room.
+        welcome: "Hello, I'm a Telegram bridge bot."
+        # Sent when joining a management room and the user is already logged in.
+        welcome_connected: "Use `help` for help."
+        # Sent when joining a management room and the user is not logged in.
+        welcome_unconnected: "Use `help` for help or `login` to log in."
+        # Optional extra text sent when joining a management room.
+        additional_help: ""
+
+    # Send each message separately (for readability in some clients)
+    management_room_multiple_messages: false
+
     # Permissions for using the bridge.
     # Permitted values:
     #   relaybot - Only use the bridge via the relaybot, no access to commands.
@@ -333,6 +565,12 @@ telegram:
     # (Optional) Create your own bot at https://t.me/BotFather
     bot_token: {{ matrix_mautrix_telegram_bot_token|to_json }}
 
+    # Should the bridge request missed updates from Telegram when restarting?
+    catch_up: true
+    # Should incoming updates be handled sequentially to make sure order is preserved on Matrix?
+    sequential_updates: true
+    exit_on_update_error: false
+
     # Telethon connection options.
     connection:
         # The timeout in seconds to be used when connecting.
@@ -354,6 +592,8 @@ telegram:
         # is not recommended, since some requests can always trigger a call fail (such as searching
         # for messages).
         request_retries: 5
+        # Use IPv6 for Telethon connection
+        use_ipv6: false
 
     # Device info sent to Telegram.
     device_info:

From 5c66485c991b8a79a62c105d35eab661da0c2e3e Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 15:40:56 +0200
Subject: [PATCH 25/28] Ensure matrix-bot-mjolnir container network is created

Most addons live in the same network by default (matrix-addons) right now,
so this network would have usually been created by some other addon.

Howevre, if this is the only addon someone uses, it may have remained
uncreated causing a problem.
---
 roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml b/roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml
index 3088fe8bd..085049bdd 100644
--- a/roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-mjolnir/tasks/setup_install.yml
@@ -59,6 +59,11 @@
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 
+- name: Ensure matrix-bot-mjolnir container network is created
+  community.general.docker_network:
+    name: "{{ matrix_bot_mjolnir_container_network }}"
+    driver: bridge
+
 - name: Ensure matrix-bot-mjolnir.service installed
   ansible.builtin.template:
     src: "{{ role_path }}/templates/systemd/matrix-bot-mjolnir.service.j2"

From 55a8f2ee67b7e67e9b7258d6ea1faf1cd25dc10f Mon Sep 17 00:00:00 2001
From: SirHazza <31993698+SirHazza@users.noreply.github.com>
Date: Sat, 20 Jan 2024 13:58:37 +0000
Subject: [PATCH 26/28] Added mention of nginx proxy manager in fronting the
 proxy doc

---
 docs/configuring-playbook-own-webserver.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/configuring-playbook-own-webserver.md b/docs/configuring-playbook-own-webserver.md
index 2295ecb3a..74d0d06c6 100644
--- a/docs/configuring-playbook-own-webserver.md
+++ b/docs/configuring-playbook-own-webserver.md
@@ -181,7 +181,7 @@ matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
 
 Such a configuration would expose all services on a local port `81` and Matrix Federation on a local port `8449`.
 
-Your reverse-proxy configuration needs to send traffic to these ports. The [`examples/reverse-proxies` directory](../examples/reverse-proxies/) contains sample configuration for various webservers (Apache2, Caddy, HAproxy, nginx).
+Your reverse-proxy configuration needs to send traffic to these ports. The [`examples/reverse-proxies` directory](../examples/reverse-proxies/) contains sample configuration for various webservers (Apache2, Caddy, HAproxy, nginx, Nginx Proxy Manager).
 
 It's important that these webservers proxy-pass requests to the correct place and also set the `Host` HTTP header appropriately.
 If you don't pass the `Host` header correctly, you would get a 404 not found error from Traefik.

From 448484a6252b1591194fc6a060b681abd832b045 Mon Sep 17 00:00:00 2001
From: SirHazza <31993698+SirHazza@users.noreply.github.com>
Date: Sat, 20 Jan 2024 13:59:58 +0000
Subject: [PATCH 27/28] Created dedicated guide on Nginx Proxy Manager

---
 .../nginx-proxy-manager/README.md             | 80 +++++++++++++++++++
 examples/reverse-proxies/nginx/README.md      | 74 +----------------
 2 files changed, 81 insertions(+), 73 deletions(-)
 create mode 100644 examples/reverse-proxies/nginx-proxy-manager/README.md

diff --git a/examples/reverse-proxies/nginx-proxy-manager/README.md b/examples/reverse-proxies/nginx-proxy-manager/README.md
new file mode 100644
index 000000000..c349af2c8
--- /dev/null
+++ b/examples/reverse-proxies/nginx-proxy-manager/README.md
@@ -0,0 +1,80 @@
+# Nginx Proxy Manager fronting the playbook's integrated Traefik reverse-proxy
+
+Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/) provides nginx capabilities but inside a pre-built Docker container. With the ability for managing proxy hosts and automatic SSL certificates via a simple web interface.
+
+This page summarizes how to use Nginx Proxy Manager (NPM) to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with another reverse-proxy.
+
+
+## Prerequisite configuration
+
+To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
+
+If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM has access to ports 443, 80 and 81, but you would also need to **provide access to the federation ports** `8448` and `8449`.
+
+
+## Using Nginx Proxy Manager
+
+You'll need to create two proxy hosts in NPM for matrix web and federation traffic.
+
+Open the 'Proxy Hosts' page in the NPM web interface and select `Add Proxy Host`, the first being for matrix web traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix web proxy config
+Domain Names: matrix.DOMAIN
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 81
+
+# Custom locations
+# Add one custom location
+Define location: /
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 81
+Custom config:
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Real-IP $remote_addr;
+    client_max_body_size 50M;
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+```
+
+Again, under the 'Proxy Hosts' page select `Add Proxy Host`, this time for your federation traffic. Apply the proxys configuration like this:
+
+```md
+# Details
+# Matrix Federation proxy config
+Domain Names: matrix.DOMAIN:8448
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 8449
+
+# Custom locations
+# Add one custom location
+Define location: /
+Scheme: http
+Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
+Forward Port: 8449
+Custom config:
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    client_max_body_size 50M;
+
+# SSL
+# Either 'Request a new certificate' or select an existing one
+SSL Certificate: matrix.DOMAIN or *.DOMAIN
+Force SSL: true
+HTTP/2 Support: true
+
+# Advanced
+# Allows NPM to listen on the federation port
+Custom Nginx Configuration: listen 8448 ssl http2;
+```
+
+Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.
\ No newline at end of file
diff --git a/examples/reverse-proxies/nginx/README.md b/examples/reverse-proxies/nginx/README.md
index 246d24ed3..fd7df72af 100644
--- a/examples/reverse-proxies/nginx/README.md
+++ b/examples/reverse-proxies/nginx/README.md
@@ -14,76 +14,4 @@ Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modi
 
 This configuration **disables SSL certificate retrieval**, so you will **need to obtain SSL certificates manually** (e.g. by using [certbot](https://certbot.eff.org/)) and set the appropriate path in `matrix.conf`. In the example nginx configuration, a single certificate is used for all subdomains (`matrix.DOMAIN`, `element.DOMAIN`, etc.). For your setup, may wish to change this and use separate `server` blocks and separate certificate files for each host.
 
-Also note that your copy of the `matrix.conf` file has to be adapted to whatever services you are using. For example, remove `element.domain.com` from the `server_name` list if you don't use [Element](../../../docs/configuring-playbook-client-element.md) web client or add `dimension.domain.com` to it if you do use the [Dimension](../../../docs/configuring-playbook-dimension.md) integration manager.
-
-## Using Nginx Proxy Manager
-
-Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/) provides nginx capabilities but inside a pre-built Docker container. With the ability for managing proxy hosts and automatic SSL certificates via a simple web interface.
-
-If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM has access to ports 443, 80 and 81, but you would also need to **provide access to the fedderation ports** `8448` and `8449`.
-
-
-### Creating proxy hosts in Nginx Proxy Manager
-
-Open the 'Proxy Hosts' page in the NPM web interface and select `Add Proxy Host`, the first being for matrix web traffic. Apply the proxys configuration like this:
-
-```md
-# Details
-# Matrix web proxy config
-Domain Names: matrix.DOMAIN
-Scheme: http
-Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
-Forward Port: 81
-
-# Custom locations
-# Add one custom location
-Define location: /
-Scheme: http
-Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
-Forward Port: 81
-Custom config:
-    proxy_set_header X-Forwarded-For $remote_addr;
-    proxy_set_header X-Forwarded-Proto $scheme;
-    proxy_set_header X-Real-IP $remote_addr;
-    client_max_body_size 50M;
-
-# SSL
-# Either 'Request a new certificate' or select an existing one
-SSL Certificate: matrix.DOMAIN or *.DOMAIN
-Force SSL: true
-HTTP/2 Support: true
-```
-
-Again, under the 'Proxy Hosts' page select `Add Proxy Host`, this time for your federation traffic. Apply the proxys configuration like this:
-
-```md
-# Details
-# Matrix Federation proxy config
-Domain Names: matrix.DOMAIN:8448
-Scheme: http
-Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
-Forward Port: 8449
-
-# Custom locations
-# Add one custom location
-Define location: /
-Scheme: http
-Forward Hostname/IP: IP-ADDRESS-OF-YOUR-MATRIX
-Forward Port: 8449
-Custom config:
-    proxy_set_header X-Forwarded-For $remote_addr;
-    proxy_set_header X-Forwarded-Proto $scheme;
-    client_max_body_size 50M;
-
-# SSL
-# Either 'Request a new certificate' or select an existing one
-SSL Certificate: matrix.DOMAIN or *.DOMAIN
-Force SSL: true
-HTTP/2 Support: true
-
-# Advanced
-# Allows NPM to listen on the federation port
-Custom Nginx Configuration: listen 8448 ssl http2;
-```
-
-Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.
+Also note that your copy of the `matrix.conf` file has to be adapted to whatever services you are using. For example, remove `element.domain.com` from the `server_name` list if you don't use [Element](../../../docs/configuring-playbook-client-element.md) web client or add `dimension.domain.com` to it if you do use the [Dimension](../../../docs/configuring-playbook-dimension.md) integration manager.
\ No newline at end of file

From 60a01622cfbdbb328d979aac3206b6943b1803ef Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sat, 20 Jan 2024 16:09:14 +0200
Subject: [PATCH 28/28] Minor improvements to the nginx-proxy-manager docs

---
 examples/reverse-proxies/nginx-proxy-manager/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/reverse-proxies/nginx-proxy-manager/README.md b/examples/reverse-proxies/nginx-proxy-manager/README.md
index c349af2c8..38de85897 100644
--- a/examples/reverse-proxies/nginx-proxy-manager/README.md
+++ b/examples/reverse-proxies/nginx-proxy-manager/README.md
@@ -2,14 +2,14 @@
 
 Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/) provides nginx capabilities but inside a pre-built Docker container. With the ability for managing proxy hosts and automatic SSL certificates via a simple web interface.
 
-This page summarizes how to use Nginx Proxy Manager (NPM) to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with another reverse-proxy.
+This page summarizes how to use Nginx Proxy Manager (NPM) to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver.
 
 
 ## Prerequisite configuration
 
 To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.<your-domain>/vars.yml`).
 
-If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM has access to ports 443, 80 and 81, but you would also need to **provide access to the federation ports** `8448` and `8449`.
+If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM already exposes ports `80` and `443`, but you would also need to **additionally expose the Matrix Federation port** (as it appears on the public side): `8448`.
 
 
 ## Using Nginx Proxy Manager
@@ -77,4 +77,4 @@ HTTP/2 Support: true
 Custom Nginx Configuration: listen 8448 ssl http2;
 ```
 
-Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.
\ No newline at end of file
+Also note, NPM would need to be configured for whatever other services you are using. For example, you would need to create additional proxy hosts for `element.DOMAIN` or `jitsi.DOMAIN`, which would use the forwarding port `81`.