Document room complexity guard for constrained Synapse setups

docs/configuring-playbook-synapse.md

@@ -80,6 +80,29 @@ A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component
 
 In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/element-hq/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
 
+### Limit joining heavy rooms on constrained hosts
+
+If your server is underpowered, joining heavy rooms can cause Synapse to consume a lot of resources and be unavailable for long (while it catches up).
+
+To avoid this, Synapse can be configured to reject joins for remote rooms that are too complex before users enter them.
+
+Complexity is computed as `current_state_events / 500` (Synapse state event count for current room state). When the resulting value is higher than `matrix_synapse_limit_remote_rooms_complexity` and `matrix_synapse_limit_remote_rooms_enabled` is `true`, Synapse blocks joining the room.
+
+We recommend using this as a guardrail on low-resource servers:
+
+```yaml
+matrix_synapse_limit_remote_rooms_enabled: true
+
+# Tweak as necessary
+matrix_synapse_limit_remote_rooms_complexity: 1.0
+
+# Uncomment and tweak if necessary
+# matrix_synapse_limit_remote_rooms_complexity_error: "Your homeserver is unable to join rooms this large or complex. Please speak to your server administrator, or upgrade your instance to join this room."
+
+# If you'd like your admins to be exempt from this limit, uncomment the line below
+# matrix_synapse_limit_remote_rooms_admins_can_join: true
+```
+
 ### Synapse + OpenID Connect for Single-Sign-On
 
 💡 An alternative to setting up OIDC in Synapse is to use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS). Newer clients (like Element X) only support SSO-based authentication via MAS and not via the legacy Synapse OIDC setup described below. That said, MAS is still a new experimental service which comes with its own downsides. Consult its documentation to learn if it will be a good fit for your deployment.

docs/faq.md

@@ -305,14 +305,23 @@ See [Serving the base domain](configuring-playbook-base-domain-serving.md).
 
 ### How do I optimize this setup for a low-power server?
 
+For a low-power server, it's best to use an alternative homeserver implementation (other than [Synapse](configuring-playbook-synapse.md)).
+
 You can disable some not-so-important services to save on memory.
 
 ```yaml
 # Disabling this will prevent email-notifications and other such things from working.
 exim_relay_enabled: false
+```
 
-# This makes Synapse not keep track of who is online/offline.
-#
+If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by default), there are additional optimizations listed on its documentation page that you can perform.
+
+
+#### Synapse-specific optimizations
+
+If you're using [Synapse](configuring-playbook-synapse.md), you can also consider the following optimizations:
+
+```yaml
 # Keeping track of this and announcing such online-status in federated rooms with
 # hundreds of servers inside is insanely heavy (https://github.com/matrix-org/synapse/issues/3971).
 #
@@ -320,16 +329,14 @@ exim_relay_enabled: false
 matrix_synapse_presence_enabled: false
 ```
 
-You can also consider implementing a restriction on room complexity, in order to prevent users from joining very heavy rooms:
+You can also consider [implementing a restriction on room complexity](configuring-playbook-synapse.md#limit-joining-heavy-rooms-on-constrained-hosts), in order to prevent users from joining very heavy rooms:
 
 ```yaml
+# See: docs/configuring-playbook-synapse.md#limit-joining-heavy-rooms-on-constrained-hosts
 matrix_synapse_limit_remote_rooms_enabled: true
-matrix_synapse_limit_remote_rooms_complexity: 1.0 # this limits joining complex (~large) rooms
-# can be increased, but larger values can require more RAM
+matrix_synapse_limit_remote_rooms_complexity: 1.0
 ```
 
-If you've installed [Jitsi](configuring-playbook-jitsi.md) (not installed by default), there are additional optimizations listed on its documentation page that you can perform.
-
 ### I already have Docker on my server. Can you stop installing Docker via the playbook?
 
 Yes, we can stop installing Docker ourselves. Just use this in your `vars.yml` file:

docs/installing.md

@@ -146,6 +146,7 @@ After completing the installation, you can:
 - or learn how to [maintain your server](faq.md#maintenance)
 - or join some Matrix rooms:
   * via the *Explore rooms* feature in Element Web or some other clients, or by discovering them using this [matrix-static list](https://view.matrix.org). **Note**: joining large rooms may overload small servers.
+    For tuning guidance on constrained hosts, see [Limit joining heavy rooms on constrained hosts](configuring-playbook-synapse.md#limit-joining-heavy-rooms-on-constrained-hosts).
   * or come say Hi in our support room — [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com). You might learn something or get to help someone else new to Matrix hosting.
 - or help make this playbook better by contributing (code, documentation, or [coffee/beer](https://liberapay.com/s.pantaleev/donate))
 

docs/maintenance-synapse.md

@@ -83,6 +83,8 @@ You should then be able to browse the adminer database administration GUI at htt
 
 Synapse's presence feature which tracks which users are online and which are offline can use a lot of processing power. You can disable presence by adding `matrix_synapse_presence_enabled: false` to your `vars.yml` file.
 
+On smaller servers, consider limiting joins to very complex rooms with [the room complexity guard](configuring-playbook-synapse.md#limit-joining-heavy-rooms-on-constrained-hosts).
+
 If you have enough compute resources (CPU & RAM), you can make Synapse better use of them by [enabling load-balancing with workers](configuring-playbook-synapse.md#load-balancing-with-workers).
 
 [Tuning your PostgreSQL database](maintenance-postgres.md#tuning-postgresql) could also improve Synapse performance. The playbook tunes the integrated Postgres database automatically, but based on your needs you may wish to adjust tuning variables manually. If you're using an [external Postgres database](configuring-playbook-external-postgres.md), you will also need to tune Postgres manually.

examples/vars.yml

@@ -52,3 +52,11 @@ devture_systemd_docker_base_ipv6_enabled: true
 # Changing this value subsequently requires manual work.
 # The value used here must be shorter than 100 characters.
 postgres_connection_password: ''
+
+# You can limit heavy room joins on constrained hosts.
+# See:
+# docs/configuring-playbook-synapse.md#limit-joining-heavy-rooms-on-constrained-hosts
+#
+# matrix_synapse_limit_remote_rooms_enabled: true
+# matrix_synapse_limit_remote_rooms_complexity: 1.0
+# matrix_synapse_limit_remote_rooms_admins_can_join: false