Add a dockerfile for running a set of Synapse worker processes

changelog.d/9162.misc

@@ -0,0 +1 @@
+Add a dockerfile for running Synapse in worker-mode under Complement.

docker/Dockerfile-workers

@@ -0,0 +1,25 @@
+# Inherit from the official Synapse docker image
+FROM matrixdotorg/synapse
+
+# Install deps
+RUN apt-get update
+RUN apt-get install -y supervisor redis nginx
+
+# Remove the default nginx sites
+RUN rm /etc/nginx/sites-enabled/default
+
+# Copy the worker process and log configuration files
+COPY ./docker/conf/worker.yaml.j2 /conf/worker.yaml.j2
+
+# Expose nginx listener port
+EXPOSE 8080/tcp
+
+# Volume for user-editable config files, logs etc.
+VOLUME ["/data"]
+
+# A script to read environment variables and create the necessary
+# files to run the desired worker configuration. Will start supervisord.
+COPY ./docker/configure_workers_and_start.py /configure_workers_and_start.py
+ENTRYPOINT ["/configure_workers_and_start.py"]
+
+# TODO: Healthcheck? Which worker to ask? Can we ask supervisord?

docker/README.md

@@ -205,3 +205,51 @@ healthcheck:
   timeout: 10s
   retries: 3
 ```
+
+### Running all worker processes in a single container
+
+Anyone looking to run Synapse workers with docker in production should use one container
+per Synapse process, specifying a different worker config per container.
+However, if for some reason you want to run all Synapse processes in the same
+container, [Dockerfile-workers](Dockerfile-workers) will provide that functionality (the
+team currently use this image for
+[Complement testing](https://github.com/matrix-org/complement), which requires a complete
+homeserver bundled in a single docker image).
+
+The Dockerfile will create a container with any desired Synapse worker processes, as well as
+a nginx to route traffic accordingly, a redis for worker communication and a supervisord
+instance to start up and monitor all processes. You will need to provide your own postgres
+container to connect to. TLS is not handled by the container. A reverse proxy should be 
+placed in front the exposed HTTP port for the purposes of TLS termination.
+
+Note that the worker Dockerfile is based off the main `[Dockerfile](Dockerfile)`. If you
+would like to build from the current checkout, first build the main Synapse docker image
+using the instructions in [Building the image](#building-the-image), then afterwards build the
+worker image:
+
+```
+docker build -t matrixdotorg/synapse:workers -f docker/Dockerfile-workers .
+```
+
+To start a container, use the following:
+
+```
+docker run -d --name synapse \
+    --mount type=volume,src=synapse-data,dst=/data \
+    -p 8008:8080 \
+    -e SYNAPSE_SERVER_NAME=my.matrix.host \
+    -e SYNAPSE_REPORT_STATS=yes \
+    -e SYNAPSE_WORKERS=synchrotron,media_repository,user_dir \
+    matrixdotorg/synapse:workers
+```
+
+The `SYNAPSE_WORKERS` environment variable is a comma-separated list of workers to use
+when running the container. All possible worker names are defined by the keys of the
+`WORKERS_CONFIG` variable in [this script](configure_workers_and_start.py), which the
+Dockerfile makes use of to generate appropriate worker, nginx and supervisord config files.
+
+Otherwise, `SYNAPSE_WORKERS` can be set to `*` to use all possible workers, or either left
+empty or unset to spawn no workers. The container is configured to use redis-based worker mode.
+
+Note that currently only one instance of a worker can be spun up at once, but this may
+improve in the future.

docker/conf/homeserver.yaml

@@ -40,7 +40,7 @@ listeners:
         compress: false
   {% endif %}
 
-  - port: 8008
+  - port: {{ SYNAPSE_PORT or 8008 }}
     tls: false
     bind_addresses: ['::']
     type: http

docker/conf/worker.yaml.j2

@@ -0,0 +1,24 @@
+# This is a configuration template for a single worker instance, and is
+# used by Dockerfile-workers.
+# Values will be change depending on whichever workers are selected when
+# running that image.
+
+worker_app: "{{ app }}"
+worker_name: "{{ name }}"
+
+# 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: {{ port }}
+{% if listener_resources %}
+    resources:
+      - names:
+{%- for resource in listener_resources %}
+        - {{ resource }}
+{%- endfor %}
+{% endif %}
+
+{{ worker_extra_conf }}