anonymousland-synapse/docker/README-testing.md
Andrew Morgan 7e460ec2a5
Add a dockerfile for running a set of Synapse worker processes (#9162)
This PR adds a Dockerfile and some supporting files to the `docker/` directory. The Dockerfile's intention is to spin up a container with:

* A Synapse main process.
* Any desired worker processes, defined by a `SYNAPSE_WORKERS` environment variable supplied at runtime.
* A redis for worker communication.
* A nginx for routing traffic.
* A supervisord to start all worker processes and monitor them if any go down.

Note that **this is not currently intended to be used in production**. If you'd like to use Synapse workers with Docker, instead make use of the official image, with one worker per container. The purpose of this dockerfile is currently to allow testing Synapse in worker mode with the [Complement](https://github.com/matrix-org/complement/) test suite.

`configure_workers_and_start.py` is where most of the magic happens in this PR. It reads from environment variables (documented in the file) and creates all necessary config files for the processes. It is the entrypoint of the Dockerfile, and thus is run any time the docker container is spun up, recreating all config files in case you want to use a different set of workers. One can specify which workers they'd like to use by setting the `SYNAPSE_WORKERS` environment variable (as a comma-separated list of arbitrary worker names) or by setting it to `*` for all worker processes. We will be using the latter in CI.

Huge thanks to @MatMaul for helping get this all working 🎉 This PR is paired with its equivalent on the Complement side: https://github.com/matrix-org/complement/pull/62.

Note, for the purpose of testing this PR before it's merged: You'll need to (re)build the base Synapse docker image for everything to work (`matrixdotorg/synapse:latest`). Then build the worker-based docker image on top (`matrixdotorg/synapse:workers`).
2021-04-14 13:54:49 +01:00

6.2 KiB

Running tests against a dockerised Synapse

It's possible to run integration tests against Synapse using Complement. Complement is a Matrix Spec compliance test suite for homeservers, and supports any homeserver docker image configured to listen on ports 8008/8448. This document contains instructions for building Synapse docker images that can be run inside Complement for testing purposes.

Note that running Synapse's unit tests from within the docker image is not supported.

Testing with SQLite and single-process Synapse

Note that scripts-dev/complement.sh is a script that will automatically build and run an SQLite-based, single-process of Synapse against Complement.

The instructions below will set up Complement testing for a single-process, SQLite-based Synapse deployment.

Start by building the base Synapse docker image. If you wish to run tests with the latest release of Synapse, instead of your current checkout, you can skip this step. From the root of the repository:

docker build -t matrixdotorg/synapse -f docker/Dockerfile .

This will build an image with the tag matrixdotorg/synapse.

Next, build the Synapse image for Complement. You will need a local checkout of Complement. Change to the root of your Complement checkout and run:

docker build -t complement-synapse -f "dockerfiles/Synapse.Dockerfile" dockerfiles

This will build an image with the tag complement-synapse, which can be handed to Complement for testing via the COMPLEMENT_BASE_IMAGE environment variable. Refer to Complement's documentation for how to run the tests, as well as the various available command line flags.

Testing with PostgreSQL and single or multi-process Synapse

The above docker image only supports running Synapse with SQLite and in a single-process topology. The following instructions are used to build a Synapse image for Complement that supports either single or multi-process topology with a PostgreSQL database backend.

As with the single-process image, build the base Synapse docker image. If you wish to run tests with the latest release of Synapse, instead of your current checkout, you can skip this step. From the root of the repository:

docker build -t matrixdotorg/synapse -f docker/Dockerfile .

This will build an image with the tag matrixdotorg/synapse.

Next, we build a new image with worker support based on matrixdotorg/synapse:latest. Again, from the root of the repository:

docker build -t matrixdotorg/synapse-workers -f docker/Dockerfile-workers .

This will build an image with the tag matrixdotorg/synapse-workers.

It's worth noting at this point that this image is fully functional, and can be used for testing against locally. See instructions for using the container under Running the Dockerfile-worker image standalone below.

Finally, build the Synapse image for Complement, which is based on matrixdotorg/synapse-workers. You will need a local checkout of Complement. Change to the root of your Complement checkout and run:

docker build -t matrixdotorg/complement-synapse-workers -f dockerfiles/SynapseWorkers.Dockerfile dockerfiles

This will build an image with the tag complement-synapse, which can be handed to Complement for testing via the COMPLEMENT_BASE_IMAGE environment variable. Refer to Complement's documentation for how to run the tests, as well as the various available command line flags.

Running the Dockerfile-worker image standalone

For manual testing of a multi-process Synapse instance in Docker, Dockerfile-workers is a Dockerfile that will produce an image bundling all necessary components together for a workerised homeserver instance.

This includes any desired Synapse worker processes, 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, and TLS is not handled by the container.

Once you've built the image using the above instructions, you can run it. Be sure you've set up a volume according to the usual Synapse docker instructions. Then run something along the lines of:

docker run -d --name synapse \
    --mount type=volume,src=synapse-data,dst=/data \
    -p 8008:8008 \
    -e SYNAPSE_SERVER_NAME=my.matrix.host \
    -e SYNAPSE_REPORT_STATS=no \
    -e POSTGRES_HOST=postgres \
    -e POSTGRES_USER=postgres \
    -e POSTGRES_PASSWORD=somesecret \
    -e SYNAPSE_WORKER_TYPES=synchrotron,media_repository,user_dir \
    -e SYNAPSE_WORKERS_WRITE_LOGS_TO_DISK=1 \
    matrixdotorg/synapse-workers

...substituting POSTGRES* variables for those that match a postgres host you have available (usually a running postgres docker container).

The SYNAPSE_WORKER_TYPES 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, which the Dockerfile makes use of to generate appropriate worker, nginx and supervisord config files.

Sharding is supported for a subset of workers, in line with the worker documentation. To run multiple instances of a given worker type, simply specify the type multiple times in SYNAPSE_WORKER_TYPES (e.g SYNAPSE_WORKER_TYPES=event_creator,event_creator...).

Otherwise, SYNAPSE_WORKER_TYPES can either be left empty or unset to spawn no workers (leaving only the main process). The container is configured to use redis-based worker mode.

Logs for workers and the main process are logged to stdout and can be viewed with standard docker logs tooling. Worker logs contain their worker name after the timestamp.

Setting SYNAPSE_WORKERS_WRITE_LOGS_TO_DISK=1 will cause worker logs to be written to <data_dir>/logs/<worker_name>.log. Logs are kept for 1 week and rotate every day at 00: 00, according to the container's clock. Logging for the main process must still be configured by modifying the homeserver's log config in your Synapse data volume.