Added the files for snippets and conf.d in nginx, with a bit of comment.

matrix/nginx/workers/README.md

@@ -25,6 +25,16 @@ 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.
 
+*Important consideration*
+
+This part isn't a quick "put these files in place and you're done": a
+worker-based Synapse is tailor-made, there's no one-size-fits-all. This
+documentation give hints and examples, but in the end it's you who has to
+decide what types of workers to use and how many, all depending on your
+specific use case and the available hardware.
+
+
+
 
 # Optimizations
 
@@ -129,8 +139,8 @@ satisfy all;
 ```
 
 Of course, subsitute these random addresses for the ones you trust. The
-dedicated nameserver (if you have one) should be configured in
-`conf.d/resolver.conf`:
+dedicated nameserver (if you have one, which is strongly recommended) should
+be configured in `conf.d/resolver.conf`:
 
 ```
 resolver [::1] 127.0.0.1 valid=60;
@@ -185,7 +195,7 @@ See a complete example of maps in the file [maps.conf](maps.conf).
 
 # Upstreams
 
-In our configuration, nginx is not only a reverse proxy, it's a load balancer.
+In our configuration, nginx is not only a reverse proxy, it's also a load balancer.
 Just like what `haproxy` does, it can forward requests to "servers" behind it.
 Such a server is the inbound UNIX socket of a worker, and there can be several
 of them in one group.
@@ -203,7 +213,7 @@ upstream login {
 Ater this definition, we can forward traffic to `login`. What traffic to
 forward is decided in the `location` statements, see further.
 
-A more complex example are the sync workers. Under [#Maps] we split sync
+A more complex example are the sync workers. Under [Maps](#Maps) we split sync
 requests into two different types; those different types are handled by
 different worker pools. In our case we have 2 workers for the initial_sync
 requests, and 3 for the normal ones:
@@ -255,8 +265,7 @@ We forward that to our worker with this `location` definition, using the
 `proxy_forward` settings we defined earlier:
 
 ```
-location ~ ^(/_matrix/client/(api/v1|r0|v3|unstable)/login|/_matrix/client/(r0|v3|unstable)/register|/_matrix/client/(r0|v3|unstable)/register/available|/_matrix/client/v1/register/m.login.registration_token/validity|/_matrix/client/(r0|v3|unstable)/password_policy)$
-{
+location ~ ^(/_matrix/client/(api/v1|r0|v3|unstable)/login|/_matrix/client/(r0|v3|unstable)/register|/_matrix/client/(r0|v3|unstable)/register/available|/_matrix/client/v1/register/m.login.registration_token/validity|/_matrix/client/(r0|v3|unstable)/password_policy)$ {
     include snippets/proxy.conf;
     proxy_pass http://login;
 }

matrix/nginx/workers/conn_optimizations.conf

@@ -0,0 +1,13 @@
+# These settings optimize the connection handling. Store this file under /etc/nginx/conf.d, because
+# it should be loaded by default.
+
+client_body_buffer_size 32m;
+client_header_buffer_size 32k;
+client_max_body_size 1g;
+http2_max_concurrent_streams 128;
+keepalive_timeout 65;
+keepalive_requests 100;
+large_client_header_buffers 4 16k;
+server_names_hash_bucket_size 128;
+tcp_nodelay on;
+server_tokens off;

matrix/nginx/workers/locations.conf

@@ -1,3 +1,7 @@
+# This file describes the forwarding of (almost) every endpoint to a worker or pool of
+# workers. This file should go in /etc/nginx/snippets, because we need to load it once, on
+# the right place in our site-definition.
+
 # Account-data
 location ~ ^(/_matrix/client/(r0|v3|unstable)/.*/tags|/_matrix/client/(r0|v3|unstable)/.*/account_data) {
     include snippets/proxy.conf;

matrix/nginx/workers/maps.conf

@@ -1,3 +1,6 @@
+# These maps set all kinds of variables we can use later in our configuration. This fil
+# should be stored under /etc/nginx/conf.d so that it is loaded whenever nginx starts.
+
 # List of allowed origins, can only send one.
 map $http_origin $allow_origin { 
         ~^https?://element.example.com$ $http_origin;

matrix/nginx/workers/private.conf

@@ -0,0 +1,13 @@
+# This file defines the "safe" IP addresses that are allowed to use the admin endpoints
+# of our installation. Store this file under /etc/nginx/snippets, so you can load it on
+# demand for the bits you want/need to protect.
+
+allow 127.0.0.1;
+allow ::1;
+allow 12.23.45.78;
+allow 87.65.43.21;
+allow dead:beef::/48;
+allow 2a10:1234:abcd::1;
+deny all;
+satisfy all;
+

matrix/nginx/workers/proxy.conf

@@ -0,0 +1,8 @@
+# These are a few proxy settings that should be default. These are not used in the proxy_forward to
+# our workers, we don't want buffering there. Store this file under /etc/nginx/conf.d because it contains
+# defaults.
+
+proxy_buffer_size 128k;
+proxy_buffers 4 256k;
+proxy_busy_buffers_size 256k;
+

matrix/nginx/workers/proxy_forward.conf

@@ -1,3 +1,6 @@
+# Settings that we want for every proxy_forward to our workers. This file should live
+# under /etc/nginx/snippets, because it should not be loaded automatically but on demand.
+
 proxy_connect_timeout 2s;
 proxy_buffering off;
 proxy_http_version 1.1;

matrix/synapse/workers/README.md

@@ -46,10 +46,14 @@ With workers, PostgreSQL's configuration should be changed accordingly: see
 server](https://tcpipuk.github.io/postgres/tuning/index.html) for hints and
 examples.
 
+A worker-based Synapse is tailor-made, there is no one-size-fits-all approach.
+All we can do here is explain how things work, what to consider and how to
+build what you need by providing examples.
+
 
 # Redis
 
-Workers need Redis as part of their communication, so our first step is
+Workers need Redis as part of their communication, so our first step will be
 to install Redis.
 
 ```