138 lines
5.7 KiB
Markdown
138 lines
5.7 KiB
Markdown
# Running tests against a dockerised Synapse
|
|
|
|
It's possible to run integration tests against Synapse
|
|
using [Complement](https://github.com/matrix-org/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.
|
|
|
|
## Using the Complement launch script
|
|
|
|
`scripts-dev/complement.sh` is a script that will automatically build
|
|
and run Synapse against Complement.
|
|
Consult the [contributing guide][guideComplementSh] for instructions on how to use it.
|
|
|
|
|
|
[guideComplementSh]: https://matrix-org.github.io/synapse/latest/development/contributing_guide.html#run-the-integration-tests-complement
|
|
|
|
## Building and running the images manually
|
|
|
|
Under some circumstances, you may wish to build the images manually.
|
|
The instructions below will lead you to doing that.
|
|
|
|
Note that these images can only be built using [BuildKit](https://docs.docker.com/develop/develop-images/build_enhancements/),
|
|
therefore BuildKit needs to be enabled when calling `docker build`. This can be done by
|
|
setting `DOCKER_BUILDKIT=1` in your environment.
|
|
|
|
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:
|
|
|
|
```sh
|
|
docker build -t matrixdotorg/synapse -f docker/Dockerfile .
|
|
```
|
|
|
|
Next, build the workerised Synapse docker image, which is a layer over the base
|
|
image.
|
|
|
|
```sh
|
|
docker build -t matrixdotorg/synapse-workers -f docker/Dockerfile-workers .
|
|
```
|
|
|
|
Finally, build the multi-purpose image for Complement, which is a layer over the workers image.
|
|
|
|
```sh
|
|
docker build -t complement-synapse -f docker/complement/Dockerfile docker/complement
|
|
```
|
|
|
|
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](https://github.com/matrix-org/complement/#running) for
|
|
how to run the tests, as well as the various available command line flags.
|
|
|
|
See [the Complement image README](./complement/README.md) for information about the
|
|
expected environment variables.
|
|
|
|
|
|
## Running the Dockerfile-worker image standalone
|
|
|
|
For manual testing of a multi-process Synapse instance in Docker,
|
|
[Dockerfile-workers](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](README.md).
|
|
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).
|
|
|
|
|
|
### Workers
|
|
|
|
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](configure_workers_and_start.py), 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](../docs/workers.md). 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 will only be configured to use Redis-based worker mode if there are
|
|
workers enabled.
|
|
|
|
### Logging
|
|
|
|
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.
|
|
|
|
|
|
### Application Services
|
|
|
|
Setting the `SYNAPSE_AS_REGISTRATION_DIR` environment variable to the path of
|
|
a directory (within the container) will cause the configuration script to scan
|
|
that directory for `.yaml`/`.yml` registration files.
|
|
Synapse will be configured to load these configuration files.
|
|
|
|
|
|
### TLS Termination
|
|
|
|
Nginx is present in the image to route requests to the appropriate workers,
|
|
but it does not serve TLS by default.
|
|
|
|
You can configure `SYNAPSE_TLS_CERT` and `SYNAPSE_TLS_KEY` to point to a
|
|
TLS certificate and key (respectively), both in PEM (textual) format.
|
|
In this case, Nginx will additionally serve using HTTPS on port 8448.
|