Added overview of configured workers and a bit of background.

matrix/synapse/workers.md

@@ -71,12 +71,22 @@ mkdir /run/matrix-synapse
 dpkg-statoverride --add --update matrix-synapse clubmatrix 2770 /run/matrix-synapse
 ```
 
+First we change Synapse from listening on `localhost:8008` to listening on a
+socket. We'll do most of our workers work in `conf.d/listeners.yaml`, so let's
+put the new configuration for the main proccess there:
+
 Add a replication listener:
 
 ```
 listeners:
-
-  ...
+  - path: /run/matrix-synapse/inbound_main.sock
+    mode: 0660
+    type: http
+    resources:
+      - names:
+        - client
+        - consent
+        - federation
 
   - path: /run/matrix-synapse/replication.sock
     mode: 0660
@@ -86,8 +96,26 @@ listeners:
         - replication 
 ```
 
-Check if the socket is created and has the correct permissions. Now point
-Synapse at Redis in `conf.d/redis.yaml`:
+This means Synapse will create two sockets under `/run/matrix/synapse`: one
+for incoming traffic that is forwarded by nginx (`inbound_main.sock`), and one for
+communicating with all the other workers (`replication.sock`).
+
+If you restart Synapse now, it won't do anything anymore, because nginx is
+still forwarding its traffic to `localhost:8008`. We'll get to nginx later,
+but you'd have to change
+
+```
+proxy_forward http://localhost:8008;
+```
+
+to
+
+```
+proxy_forward http://unix:/run/matrix-synapse/inbound_main.sock;
+```
+
+If you've done this, restart Synapse, check if the socket is created and has
+the correct permissions. Now point Synapse at Redis in `conf.d/redis.yaml`:
 
 ```
 redis:
@@ -107,10 +135,87 @@ synapse.replication.tcp.redis - 141 - INFO - subscribe-replication-0 - Successfu
 synapse.replication.tcp.redis - 146 - INFO - subscribe-replication-0 - REPLICATE successfully sent
 ```
 
+
+# Worker overview
+
+Every worker is, in fact, a Synapse server, only with a limited set of tasks.
+Some tasks can be handled by a number of workers, others only by one. Every
+worker starts as a normal Synapse process, reading all the normal
+configuration files, and then a bit of configuration for the specific worker
+itself.
+
+Workers need to communicate with each other and the main process, they do that
+via the `replication` sockets under `/run/matrix-synapse`.
+
+Most worker also need a way to be fed traffic by nginx, they have an `inbound`
+socket for that, in the same directory.
+
+Finally, all those replicating workers need to be registered in the main
+process: all workers and their  replication sockets are listed inin the `instance_map`.
+
+
 Every worker has its own configuration file, we'll put those under
 `/etc/matrix-synapse/workers`. Create it, and then one systemd service file for
 all workers:
 
+
+## Types of workers
+
+We'll make separate workers for almost every task, and several for the
+heaviest tasks: synchronising. An overview of what endpoints are to be
+forwarded to a worker is in [Synapse's documentation](https://element-hq.github.io/synapse/latest/workers.html#available-worker-applications).
+
+We'll create the following workers:
+
+* login
+* federation_sender
+* mediaworker
+* userdir
+* pusher
+* push_rules
+* typing
+* todevice
+* accountdata
+* presence
+* receipts
+* initial_sync: 1 and 2
+* normal_sync: 1, 2 and 3
+
+Some of them are `stream_writers`, and the [documentation about
+stream_witers](https://element-hq.github.io/synapse/latest/workers.html#stream-writers)
+says:
+
+```
+Note: The same worker can handle multiple streams, but unless otherwise documented, each stream can only have a single writer.
+```
+
+So, stream writers must have unique tasks: you can't have two or more workers
+writing to the same stream. Stream writers have to be listed in `stream_writers`:
+
+```
+stream_writers:
+  account_data:
+    - accountdata
+  presence:
+    - presence
+  receipts:
+    - receipts
+  to_device:
+    - todevice
+  typing:
+    - typing
+  push_rules:
+    - push_rules
+```
+
+As you can see, we've given the stream workers the name of the stream they're
+writing to. We could combine all those streams into one worker, which would
+probably be enough for most instances.
+
+We could define a worker with the name streamwriter and list it under all
+streams instead of a single worker for every stream.
+
+
 ```
 [Unit]
 Description=Synapse %i