Finished the bit about workers.

matrix/synapse/workers.md

@@ -301,7 +301,8 @@ what you need:
 * inbound socket (not every worker needs this)
 * log configuration
 
-One worker we use handles the login actions, this is how it's configured:
+One worker we use handles the login actions, this is how it's configured in
+/etc/matrix-synapse/workers/login.yaml`:
 
 ```
 worker_app: "synapse.app.generic_worker"
@@ -323,13 +324,13 @@ worker_listeners:
       - names: [replication]
 ```
 
-First listener is the socket where nginx sends all traffic related to logins
+The first line defines the type of worker. In the past there were quite a few
-to. You have to configure nginx to do that, we'll get to that later.
-
-First line defines the type of worker. In the past there were quite a few
 different types, but most of them have been phased out in favour of one
 generic worker.
 
+The first listener is the socket where nginx sends all traffic related to logins
+to. You have to configure nginx to do that, we'll get to that later.
+
 The `worker_log_config` defines how and where the worker logs. Of course you'll
 need to configure that too, see further.
 
@@ -339,7 +340,8 @@ related traffic to. Make sure nginx can write to this socket. The
 
 The second `listener` is used for communication with the other workers and the
 main thread. The only `resource` it needs is `replication`. This socket needs
-to be listed in the `instance_map` in the main thread.
+to be listed in the `instance_map` in the main thread, the inbound socket does
+not.
 
 Of course, if you need to scale up to the point where you need more than one
 machine, these listeners can no longer use UNIX sockets, but will have to use
@@ -371,9 +373,7 @@ worker_listeners:
   - path: "/run/matrix-synapse/inbound_mediaworker.sock"
     type: http
     resources:
-      - names:
+      - names: [media]
-        - media
-        - federation
 
   - path: "/run/matrix-synapse/replication_mediaworker.sock"
     type: http
@@ -392,6 +392,12 @@ file. As with the definitions of the workers themselves, you need a directory fo
 that. We'll use `/etc/matrix-synapse/logconf.d` for that; make it and fix the
 permissions.
 
+```
+mkdir /etc/matrix-synapse/logconf.d
+chgrp matrix-synapse /etc/matrix-synapse/logconf.d
+chmod 750 /etc/matrix-synapse/logconf.d
+```
+
 There's a lot you can configure for logging, but for now we'll give every
 worker the same layout. Here's the configuration for the `login` worker:
 
@@ -440,8 +446,8 @@ root:
 
 The only thing you need to change if the filename to which the logs are
 written. You could create only one configuration and use that in every worker,
-but that would mean all logs will end up in the same file, which may not be
+but that would mean all logs will end up in the same file, which is probably
-what you want.
+not what you want.
 
 See the [Python
 documentation](https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema)
@@ -469,26 +475,53 @@ WantedBy=multi-user.target
 ```
 
 First add `matrix-synapse.service` to this target by overriding the `WantedBy`
-in the unit file (`systemctl edit matrix-synapse.service`):
+in the unit file. We're overriding and adding a bit more.
 
 ```
+systemctl edit matrix-synapse.service
+```
+
+Add this to the overrides:
+
+```
+[Unit]
+PartOf=matrix-synapse.target
+Before=matrix-synapse-worker
+ReloadPropagatedFrom=matrix-synapse.target
+
+[Service]
+RuntimeDirectory=matrix-synapse
+RuntimeDirectoryMode=0775
+RuntimeDirectoryPreserve=yes
+
 [Install]
-WantedBy=matrix.target
+WantedBy=matrix-synapse.target
 ```
 
-The same `WantedBy` need to go in the unit files for every worker. For the
+The additions under `Unit` mean that `matrix-synapse.service` is part of the
-workers we're using a template instead of separate unit files for every single
+target we created earlier, and that is should start before the workers.
-one. Create the template:
+Restarting the target means this service must be restarted too.
+
+Under `Service` we define the directory where the sockets live (`/run` is
+prefixed automatically), its permissions and that it should not be removed if
+the service is stopped.
+
+The `WantedBy` under `Install` includes it in the target. The target itself is
+included in `multi-user.target`, so it should always be started in the multi-user
+runlevel.
+
+For the workers we're using a template instead of separate unit files for every
+single one. Create the template:
 
 ```
 systemctl edit --full --force matrix-synapse-worker@
 ```
 
-Fill it with this content:
+Mind the `@` at the end, that's not a typo. Fill it with this content:
 
 ```
 [Unit]
-Description=Synapse %i
+Description=Synapse worker %i
 AssertPathExists=/etc/matrix-synapse/workers/%i.yaml
 
 # This service should be restarted when the synapse target is restarted.
@@ -503,8 +536,8 @@ After=matrix-synapse.service
 Type=notify
 NotifyAccess=main
 User=matrix-synapse
+Group=matrix-synapse
 WorkingDirectory=/var/lib/matrix-synapse
-EnvironmentFile=-/etc/default/matrix-synapse
 ExecStart=/opt/venvs/matrix-synapse/bin/python -m synapse.app.generic_worker --config-path=/etc/matrix-synapse/homeserver.yaml --config-path=/etc/matrix-synapse/conf.d/ --config-path=/etc/matrix-synapse/workers/%i.yaml
 ExecReload=/bin/kill -HUP $MAINPID
 Restart=always
@@ -515,12 +548,28 @@ SyslogIdentifier=matrix-synapse-%i
 WantedBy=matrix-synapse.target
 ```
 
+Now you can start/stop/restart every worker individually. Starting the `login`
+worker would be done by:
+
+```
+systemctl start matrix-synapse-worker@login
+```
+
 Every worker needs to be enabled and started individually. Quickest way to do
 that, is to run a loop in the directory:
 
 ```
 cd /etc/matrix-synapse/workers
-for worker in `ls *yaml`; do systemctl enable --now matrix-synapse-worker@$worker; done
+for worker in `ls *yaml | sed -n 's/\.yaml//p'`; do systemctl enable matrix-synapse-worker@$worker; done
 ```
 
-After a reboot, Synapse and all its workers should be started.
+After a reboot, Synapse and all its workers should be started. But starting
+the target should also do that:
+
+```
+systemctl start matrix-synapse.target
+```
+
+This should start `matrix-synapse.service` first, the main worker. After that
+all the workers should be started too. Check if the correct sockets appear and
+if there are any error messages in the logs.