From a5da63908edeac20e6705d77fc4d52bf172cef61 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 11:38:04 +0200
Subject: [PATCH 1/6] Add some cross references to worker documentation (#36)

---
 docs/workers.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/workers.md b/docs/workers.md
index 40b18523137c..8b15fb97a98e 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -93,7 +93,6 @@ listener" for the main process; and secondly, you need to enable redis-based
 replication. Optionally, a shared secret can be used to authenticate HTTP
 traffic between workers. For example:
 
-
 ```yaml
 # extend the existing `listeners` section. This defines the ports that the
 # main process will listen on.
@@ -129,7 +128,8 @@ In the config file for each worker, you must specify:
  * The HTTP replication endpoint that it should talk to on the main synapse process
    (`worker_replication_host` and `worker_replication_http_port`)
  * If handling HTTP requests, a `worker_listeners` option with an `http`
-   listener, in the same way as the `listeners` option in the shared config.
+   listener, in the same way as the [`listeners`](usage/configuration/config_documentation.md#listeners)
+   option in the shared config.
  * If handling the `^/_matrix/client/v3/keys/upload` endpoint, the HTTP URI for
    the main process (`worker_main_http_uri`).
 
@@ -285,8 +285,9 @@ For multiple workers not handling the SSO endpoints properly, see
 [#7530](https://github.com/matrix-org/synapse/issues/7530) and
 [#9427](https://github.com/matrix-org/synapse/issues/9427).
 
-Note that a HTTP listener with `client` and `federation` resources must be
-configured in the `worker_listeners` option in the worker config.
+Note that a [HTTP listener](usage/configuration/config_documentation.md#listeners)
+with `client` and `federation` `resources` must be configured in the `worker_listeners`
+option in the worker config.
 
 #### Load balancing
 
@@ -536,7 +537,8 @@ file to stop the main synapse running background jobs related to managing the
 media repository. Note that doing so will prevent the main process from being
 able to handle the above endpoints.
 
-In the `media_repository` worker configuration file, configure the http listener to
+In the `media_repository` worker configuration file, configure the
+[HTTP listener](usage/configuration/config_documentation.md#listeners) to
 expose the `media` resource. For example:
 
 ```yaml

From efbdc95cdf9579803a6ff218fb27aee7774394f1 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:02:04 +0200
Subject: [PATCH 2/6] newsfile

---
 changelog.d/13974.doc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/13974.doc

diff --git a/changelog.d/13974.doc b/changelog.d/13974.doc
new file mode 100644
index 000000000000..c4ab17db53d6
--- /dev/null
+++ b/changelog.d/13974.doc
@@ -0,0 +1 @@
+Add some cross references to worker documentation.

From 3767d82d09aff8bcb64d8068c8323509041bdffe Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:06:05 +0200
Subject: [PATCH 3/6] add a link

---
 docs/workers.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/workers.md b/docs/workers.md
index 8b15fb97a98e..3ed298e90909 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -327,7 +327,8 @@ effects of bursts of events from that bridge on events sent by normal users.
 Additionally, the writing of specific streams (such as events) can be moved off
 of the main process to a particular worker.
 
-To enable this, the worker must have a HTTP replication listener configured,
+To enable this, the worker must have a
+[HTTP `replication` listener](usage/configuration/config_documentation.md#listeners) configured,
 have a `worker_name` and be listed in the `instance_map` config. The same worker
 can handle multiple streams, but unless otherwise documented, each stream can only
 have a single writer.

From 5fe5b6144d571b101f38606ab342ec3f4535a7ae Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:13:13 +0200
Subject: [PATCH 4/6] Create media_worker.yaml

---
 .../systemd-with-workers/workers/media_worker.yaml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 docs/systemd-with-workers/workers/media_worker.yaml

diff --git a/docs/systemd-with-workers/workers/media_worker.yaml b/docs/systemd-with-workers/workers/media_worker.yaml
new file mode 100644
index 000000000000..eb34d1249231
--- /dev/null
+++ b/docs/systemd-with-workers/workers/media_worker.yaml
@@ -0,0 +1,14 @@
+worker_app: synapse.app.media_repository
+worker_name: media_worker
+
+# The replication listener on the main synapse process.
+worker_replication_host: 127.0.0.1
+worker_replication_http_port: 9093
+
+worker_listeners:
+  - type: http
+    port: 8085
+    resources:
+      - names: [media]
+
+worker_log_config: /etc/matrix-synapse/media-worker-log.yaml

From 38e9d21830c7475b15c1d62973a0acd9e4576052 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:14:37 +0200
Subject: [PATCH 5/6] add example for media worker

---
 docs/workers.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/docs/workers.md b/docs/workers.md
index 3ed298e90909..c4a78cbaf423 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -543,12 +543,7 @@ In the `media_repository` worker configuration file, configure the
 expose the `media` resource. For example:
 
 ```yaml
-worker_listeners:
- - type: http
-   port: 8085
-   resources:
-     - names:
-       - media
+{{#include systemd-with-workers/workers/media_worker.yaml}}
 ```
 
 Note that if running multiple media repositories they must be on the same server

From f1274f150d02b8b4e2ec4ba23a6bcd46c1f7e55b Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 30 Sep 2022 12:21:56 +0200
Subject: [PATCH 6/6] add information which workes does not handle REST

---
 docs/workers.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/workers.md b/docs/workers.md
index c4a78cbaf423..25f2e13237f8 100644
--- a/docs/workers.md
+++ b/docs/workers.md
@@ -412,7 +412,7 @@ the stream writer for the `presence` stream:
 There is also support for moving background tasks to a separate
 worker. Background tasks are run periodically or started via replication. Exactly
 which tasks are configured to run depends on your Synapse configuration (e.g. if
-stats is enabled).
+stats is enabled). This worker doesn't handle any REST endpoints itself.
 
 To enable this, the worker must have a `worker_name` and can be configured to run
 background tasks. For example, to move background tasks to a dedicated worker,
@@ -459,8 +459,8 @@ worker application type.
 #### Notifying Application Services
 
 You can designate one generic worker to send output traffic to Application Services.
-
-Specify its name in the shared configuration as follows:
+Doesn't handle any REST endpoints itself, but you should specify its name in the
+shared configuration as follows:
 
 ```yaml
 notify_appservices_from_worker: worker_name