deploy: e4f545c452

develop/workers.html

@@ -209,13 +209,21 @@ the processes.</p>
 need its own configuration file and can take all of its configuration from the
 shared configuration file.</p>
 <h3 id="shared-configuration"><a class="header" href="#shared-configuration">Shared configuration</a></h3>
-<p>Normally, only a couple of changes are needed to make an existing configuration
-file suitable for use with workers. First, you need to enable an
+<p>Normally, only a few changes are needed to make an existing configuration
+file suitable for use with workers:</p>
+<ul>
+<li>First, you need to enable an
 <a href="usage/configuration/config_documentation.html#listeners">&quot;HTTP replication listener&quot;</a>
-for the main process; and secondly, you need to enable
-<a href="usage/configuration/config_documentation.html#redis">redis-based replication</a>.
-Optionally, a <a href="usage/configuration/config_documentation.html#worker_replication_secret">shared secret</a>
-can be used to authenticate HTTP traffic between workers. For example:</p>
+for the main process</li>
+<li>Secondly, you need to enable
+<a href="usage/configuration/config_documentation.html#redis">redis-based replication</a></li>
+<li>You will need to add an <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a> 
+with the <code>main</code> process defined, as well as the relevant connection information from 
+it's HTTP <code>replication</code> listener (defined in step 1 above). Note that the <code>host</code> defined 
+is the address the worker needs to look for the <code>main</code> process at, not necessarily the same address that is bound to.</li>
+<li>Optionally, a <a href="usage/configuration/config_documentation.html#worker_replication_secret">shared secret</a>
+can be used to authenticate HTTP traffic between workers. For example:</li>
+</ul>
 <pre><code class="language-yaml"># extend the existing `listeners` section. This defines the ports that the
 # main process will listen on.
 listeners:
@@ -231,6 +239,11 @@ worker_replication_secret: &quot;&quot;
 
 redis:
     enabled: true
+
+instance_map:
+    main:
+        host: 'localhost'
+        port: 9093
 </code></pre>
 <p>See the <a href="usage/configuration/config_documentation.html">configuration manual</a>
 for the full documentation of each option.</p>
@@ -247,22 +260,18 @@ is configured</li>
 <li>The type of worker (<a href="usage/configuration/config_documentation.html#worker_app"><code>worker_app</code></a>).
 The currently available worker applications are listed <a href="#available-worker-applications">below</a>.</li>
 <li>A unique name for the worker (<a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>).</li>
-<li>The HTTP replication endpoint that it should talk to on the main synapse process
-(<a href="usage/configuration/config_documentation.html#worker_replication_host"><code>worker_replication_host</code></a> and
-<a href="usage/configuration/config_documentation.html#worker_replication_http_port"><code>worker_replication_http_port</code></a>).</li>
 <li>If handling HTTP requests, a <a href="usage/configuration/config_documentation.html#worker_listeners"><code>worker_listeners</code></a> option
 with an <code>http</code> listener.</li>
 <li><strong>Synapse 1.72 and older:</strong> if handling the <code>^/_matrix/client/v3/keys/upload</code> endpoint, the HTTP URI for
 the main process (<code>worker_main_http_uri</code>). This config option is no longer required and is ignored when running Synapse 1.73 and newer.</li>
+<li><strong>Synapse 1.83 and older:</strong> The HTTP replication endpoint that the worker should talk to on the main synapse process
+(<a href="usage/configuration/config_documentation.html#worker_replication_host"><code>worker_replication_host</code></a> and
+<a href="usage/configuration/config_documentation.html#worker_replication_http_port"><code>worker_replication_http_port</code></a>). If using Synapse 1.84 and newer, these are not needed if <code>main</code> is defined on the <a href="#shared-configuration">shared configuration</a> <code>instance_map</code></li>
 </ul>
 <p>For example:</p>
 <pre><code class="language-yaml">worker_app: synapse.app.generic_worker
 worker_name: generic_worker1
 
-# 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: 8083
@@ -516,15 +525,22 @@ effects of bursts of events from that bridge on events sent by normal users.</p>
 <h4 id="stream-writers"><a class="header" href="#stream-writers">Stream writers</a></h4>
 <p>Additionally, the writing of specific streams (such as events) can be moved off
 of the main process to a particular worker.</p>
-<p>To enable this, the worker must have a
-<a href="usage/configuration/config_documentation.html#listeners">HTTP <code>replication</code> listener</a> configured,
-have a <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>
+<p>To enable this, the worker must have:</p>
+<ul>
+<li>An <a href="usage/configuration/config_documentation.html#listeners">HTTP <code>replication</code> listener</a> configured,</li>
+<li>Have a <a href="usage/configuration/config_documentation.html#worker_name"><code>worker_name</code></a>
 and be listed in the <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a>
-config. The same worker can handle multiple streams, but unless otherwise documented,
+config. </li>
+<li>Have the main process declared on the <a href="usage/configuration/config_documentation.html#instance_map"><code>instance_map</code></a> as well.</li>
+</ul>
+<p>Note: The same worker can handle multiple streams, but unless otherwise documented,
 each stream can only have a single writer.</p>
 <p>For example, to move event persistence off to a dedicated worker, the shared
 configuration would include:</p>
 <pre><code class="language-yaml">instance_map:
+    main:
+        host: localhost
+        port: 8030
     event_persister1:
         host: localhost
         port: 8034