First bit of documentation of the reverse nginx proxy for Synapse with workers.

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.

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