summary refs log tree commit diff
path: root/contrib/docker_compose_workers/README.md
blob: bdd3dd32e07fae16f874c4a90de143a154ba7364 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# 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
```

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