From 2ef437e13c7940d4285fa1cf71acc2781d867244 Mon Sep 17 00:00:00 2001
From: Hans van Zijst <hans@procolix.com>
Date: Mon, 23 Dec 2024 19:03:46 +0100
Subject: [PATCH] First bit of documentation of the reverse nginx proxy for
Synapse with workers.
---
matrix/nginx/{ => conf}/call.conf | 0
matrix/nginx/{ => conf}/domain.conf | 0
matrix/nginx/{ => conf}/elementweb.conf | 0
matrix/nginx/{ => conf}/livekit.conf | 0
matrix/nginx/{ => conf}/revproxy.conf | 0
matrix/nginx/{ => conf}/synapse-admin.conf | 0
matrix/nginx/workers/README.md | 62 ++++++++++++++++++++++
matrix/synapse/workers.md | 2 +
8 files changed, 64 insertions(+)
rename matrix/nginx/{ => conf}/call.conf (100%)
rename matrix/nginx/{ => conf}/domain.conf (100%)
rename matrix/nginx/{ => conf}/elementweb.conf (100%)
rename matrix/nginx/{ => conf}/livekit.conf (100%)
rename matrix/nginx/{ => conf}/revproxy.conf (100%)
rename matrix/nginx/{ => conf}/synapse-admin.conf (100%)
create mode 100644 matrix/nginx/workers/README.md
diff --git a/matrix/nginx/call.conf b/matrix/nginx/conf/call.conf
similarity index 100%
rename from matrix/nginx/call.conf
rename to matrix/nginx/conf/call.conf
diff --git a/matrix/nginx/domain.conf b/matrix/nginx/conf/domain.conf
similarity index 100%
rename from matrix/nginx/domain.conf
rename to matrix/nginx/conf/domain.conf
diff --git a/matrix/nginx/elementweb.conf b/matrix/nginx/conf/elementweb.conf
similarity index 100%
rename from matrix/nginx/elementweb.conf
rename to matrix/nginx/conf/elementweb.conf
diff --git a/matrix/nginx/livekit.conf b/matrix/nginx/conf/livekit.conf
similarity index 100%
rename from matrix/nginx/livekit.conf
rename to matrix/nginx/conf/livekit.conf
diff --git a/matrix/nginx/revproxy.conf b/matrix/nginx/conf/revproxy.conf
similarity index 100%
rename from matrix/nginx/revproxy.conf
rename to matrix/nginx/conf/revproxy.conf
diff --git a/matrix/nginx/synapse-admin.conf b/matrix/nginx/conf/synapse-admin.conf
similarity index 100%
rename from matrix/nginx/synapse-admin.conf
rename to matrix/nginx/conf/synapse-admin.conf
diff --git a/matrix/nginx/workers/README.md b/matrix/nginx/workers/README.md
new file mode 100644
index 00000000..1f9b8ab9
--- /dev/null
+++ b/matrix/nginx/workers/README.md
@@ -0,0 +1,62 @@
+---
+gitea: none
+include_toc: true
+---
+
+# Reverse proxy for Synapse with workers
+
+Changing nginx's configuration from a reverse proxy for a normal, monolithi
+Synapse to one for a Synapse that uses workers, quite a lot has to be changed.
+
+As mentioned in [Synapse with workers](../synapse/workers.md#synapse), we're
+changing from network sockets to UNIX sockets.
+
+Because we're going to have to forward a lot of specific requests to all kinds
+of workers, we'll split the configuration into a few bits:
+
+** all `proxy_forward` settings
+** all `location` definitions
+** maps that define variables
+** upstreams that point to the correct socket(s) with the correct settings
+** settings for private access
+** connection optimizations
+
+Some of these go into `/etc/nginx/conf.d` because they are part of the
+configuration of nginx itself, others go into `/etc/nginx/snippets` because we
+need to include them several times in different places.
+
+
+# Maps
+
+A map sets a variable based on, usually, another variable. One case we use is
+determining the type of sync a client is doing. A normal sync, simply
+updating an existing session, is a rather lightweight operation.
+
+An initial sync, meaning a full sync because the session is brand new, is not
+so lightweight.
+
+A normal sync can be recognised by the `since` bit in the request: it tells
+the server when its last sync was. If there is no `since`, we're dealing with
+an initial sync.
+
+Initial syncs are forwarded to the `initial_sync` workers, the normal syncs to
+`normal_sync`.
+
+We decide to which type of worker to forward the sync request to by looking at
+the presence or absence of `since`: if it's there, it's a normal sync and we
+set the variable `$sync` to `normal_sync`. If it's not there, we set `$sync` to
+`initial_sync`.
+
+The last bit is to foward the request to the upstream `$sync`. This is what
+that map looks like:
+
+```
+map $arg_since $sync {
+ default normal_sync;
+ '' initial_sync;
+}
+```
+
+We filter the argument `since` by using `$arg_since`, see [the index of
+variables in nginx](https://nginx.org/en/docs/varindex.html) for more
+variables we can use.
diff --git a/matrix/synapse/workers.md b/matrix/synapse/workers.md
index 282eaf60..ee5e38cd 100644
--- a/matrix/synapse/workers.md
+++ b/matrix/synapse/workers.md
@@ -585,3 +585,5 @@ See [Deploying a Synapse Homeserver with
Docker](https://tcpipuk.github.io/synapse/deployment/nginx.html) for the
inspiration. This details a Docker installation, which we don't have, but the
reasoning behind it applies to our configuration too.
+
+Here's [how to configure nginx for use with workers](../nginx/workers).