Add documentation for the dockerfile

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 SYNASPE_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.