synapse/docs/systemd-with-workers
Richard van der Hoff 70ea9593ff
example systemd config: propagate reloads to units (#9463)
It should be possible to reload `synapse.target` to have the reload propagate
to all the synapse units.
2021-02-22 18:43:17 +00:00
..
system example systemd config: propagate reloads to units (#9463) 2021-02-22 18:43:17 +00:00
workers Fixup worker doc (again) (#8000) 2020-08-06 10:35:59 +01:00
README.md Fix typo in docs/systemd-with-workers/README.md (#9035) 2021-01-07 15:31:01 +00:00

Setting up Synapse with Workers and Systemd

This is a setup for managing synapse with systemd, including support for managing workers. It provides a matrix-synapse service for the master, as well as a matrix-synapse-worker@ service template for any workers you require. Additionally, to group the required services, it sets up a matrix-synapse.target.

See the folder system for the systemd unit files.

The folder workers contains an example configuration for the federation_reader worker.

Synapse configuration files

See workers.md for information on how to set up the configuration files and reverse-proxy correctly. You can find an example worker config in the workers folder.

Systemd manages daemonization itself, so ensure that none of the configuration files set either daemonize or worker_daemonize.

The config files of all workers are expected to be located in /etc/matrix-synapse/workers. If you want to use a different location, edit the provided *.service files accordingly.

There is no need for a separate configuration file for the master process.

Set up

  1. Adjust synapse configuration files as above.
  2. Copy the *.service and *.target files in system to /etc/systemd/system.
  3. Run systemctl daemon-reload to tell systemd to load the new unit files.
  4. Run systemctl enable matrix-synapse.service. This will configure the synapse master process to be started as part of the matrix-synapse.target target.
  5. For each worker process to be enabled, run systemctl enable matrix-synapse-worker@<worker_name>.service. For each <worker_name>, there should be a corresponding configuration file. /etc/matrix-synapse/workers/<worker_name>.yaml.
  6. Start all the synapse processes with systemctl start matrix-synapse.target.
  7. Tell systemd to start synapse on boot with systemctl enable matrix-synapse.target.

Usage

Once the services are correctly set up, you can use the following commands to manage your synapse installation:

# Restart Synapse master and all workers
systemctl restart matrix-synapse.target

# Stop Synapse and all workers
systemctl stop matrix-synapse.target

# Restart the master alone
systemctl start matrix-synapse.service

# Restart a specific worker (eg. federation_reader); the master is
# unaffected by this.
systemctl restart matrix-synapse-worker@federation_reader.service

# Add a new worker (assuming all configs are set up already)
systemctl enable matrix-synapse-worker@federation_writer.service
systemctl restart matrix-synapse.target