synapse/contrib/docker_compose_workers/README.md

# Setting up Synapse with Workers using Docker Compose

This directory describes how deploy and manage Synapse and workers via [Docker Compose](https://docs.docker.com/compose/).

Example worker configuration files can be found [here](workers).

All examples and snippets assume that your Synapse service is called `synapse` in your Docker Compose file.

An example Docker Compose file can be found [here](docker-compose.yaml).

## Worker Service Examples in Docker Compose

In order to start the Synapse container as a worker, you must specify an `entrypoint` that loads both the `homeserver.yaml` and the configuration for the worker (`synapse-generic-worker-1.yaml` in the example below). You must also include the worker type in the environment variable `SYNAPSE_WORKER` or alternatively pass `-m synapse.app.generic_worker` as part of the `entrypoint` after `"/start.py", "run"`).

### Generic Worker Example

```yaml
synapse-generic-worker-1:
  image: matrixdotorg/synapse:latest
  container_name: synapse-generic-worker-1
  restart: unless-stopped
  entrypoint: ["/start.py", "run", "--config-path=/data/homeserver.yaml", "--config-path=/data/workers/synapse-generic-worker-1.yaml"]
  healthcheck:
    test: ["CMD-SHELL", "curl -fSs http://localhost:8081/health || exit 1"]
    start_period: "5s"
    interval: "15s"
    timeout: "5s"
  volumes:
    - ${VOLUME_PATH}/data:/data:rw # Replace VOLUME_PATH with the path to your Synapse volume
  environment:
    SYNAPSE_WORKER: synapse.app.generic_worker
  # Expose port if required so your reverse proxy can send requests to this worker
  # Port configuration will depend on how the http listener is defined in the worker configuration file
  ports:
    - 8081:8081
  depends_on:
    - synapse
```

### Federation Sender Example

Please note: The federation sender does not receive REST API calls so no exposed ports are required.

```yaml
synapse-federation-sender-1:
  image: matrixdotorg/synapse:latest
  container_name: synapse-federation-sender-1
  restart: unless-stopped
  entrypoint: ["/start.py", "run", "--config-path=/data/homeserver.yaml", "--config-path=/data/workers/synapse-federation-sender-1.yaml"]
  healthcheck:
    disable: true
  volumes:
    - ${VOLUME_PATH}/data:/data:rw # Replace VOLUME_PATH with the path to your Synapse volume
  environment:
    SYNAPSE_WORKER: synapse.app.federation_sender
  depends_on:
    - synapse
```

## `homeserver.yaml` Configuration

### Enable Redis

Locate the `redis` section of your `homeserver.yaml` and enable and configure it:

```yaml
redis:
  enabled: true
  host: redis
  port: 6379
  # password: <secret_password>  
```

This assumes that your Redis service is called `redis` in your Docker Compose file.

### Add a replication Listener

Locate the `listeners` section of your `homeserver.yaml` and add the following replication listener:

```yaml
listeners:
  # Other listeners

  - port: 9093
    type: http
    resources:
      - names: [replication]
```

This listener is used by the workers for replication and is referred to in worker config files using the following settings:

```yaml
worker_replication_host: synapse
worker_replication_http_port: 9093
```

### Add Workers to `instance_map`

Locate the `instance_map` section of your `homeserver.yaml` and populate it with your workers:

```yaml
instance_map:
  synapse-generic-worker-1:        # The worker_name setting in your worker configuration file
    host: synapse-generic-worker-1 # The name of the worker service in your Docker Compose file
    port: 8034                     # The port assigned to the replication listener in your worker config file
  synapse-federation-sender-1:
    host: synapse-federation-sender-1
    port: 8034
```

### Configure Federation Senders

This section is applicable if you are using Federation senders (synapse.app.federation_sender). Locate the `send_federation` and `federation_sender_instances` settings in your `homeserver.yaml` and configure them:

```yaml
# This will disable federation sending on the main Synapse instance
send_federation: false

federation_sender_instances:
  - synapse-federation-sender-1 # The worker_name setting in your federation sender worker configuration file
```

## Other Worker types

Using the concepts shown here it is possible to create other worker types in Docker Compose. See the [Workers](https://matrix-org.github.io/synapse/latest/workers.html#available-worker-applications) documentation for a list of available workers.