a6d84190eb
This setup is a way to manage workers with systemd. It does however not require workers. You can use this setup without workers. You just have to make sure that the homeserver is forking and writes its PID file to the location the service is looking in. The currently distributed setup in the debian package does not work in conjunction with workers. * Adds changelog * Lets systemd handle the forking Sets all services to `type=simple` and disables daemonizing on the synapse side. * Formats readme to 80 columns per line * Allows for full restart of all workers * Changes README to reflect the new setup * Adds dot to end of changelog file * Removes surplus word Co-Authored-By: targodan <targodan@users.noreply.github.com> * Adds missing word Co-Authored-By: targodan <targodan@users.noreply.github.com> * Fixes linebreak Co-Authored-By: targodan <targodan@users.noreply.github.com> * Fixes unit type |
||
|---|---|---|
| .. | ||
| system | ||
| workers | ||
| README.md | ||
Setup Synapse with Workers and Systemd
This is a setup for managing synapse with systemd including support for
managing workers. It provides a matrix-synapse, as well as a
matrix-synapse-worker@ service for any workers you require. Additionally to
group the required services it sets up a matrix.target. You can use this to
automatically start any bot- or bridge-services. More on this in
Bots and Bridges.
See the folder system for any service and target files.
The folder workers contains an example configuration for the
federation_reader worker. Pay special attention to the name of the
configuration file. In order to work with the matrix-synapse-worker@.service
service, it needs to have the exact same name as the worker app.
This setup expects neither the homeserver nor any workers to fork. Forking is handled by systemd.
Setup
- Adjust your matrix configs. Make sure that the worker config files have the
exact same name as the worker app. Compare
matrix-synapse-worker@.servicefor why. You can find an example worker config in the workers folder. See below for relevant settings in thehomeserver.yaml. - Copy the
*.serviceand*.targetfiles in system to/etc/systemd/system. systemctl enable matrix-synapse.servicethis adds the homeserver app to thematrix.target- Optional.
systemctl enable matrix-synapse-worker@federation_reader.servicethis adds the federation_reader app to thematrix-synapse.service - Optional. Repeat step 4 for any additional workers you require.
- Optional. Add any bots or bridges by enabling them.
- Start all matrix related services via
systemctl start matrix.target - Optional. Enable autostart of all matrix related services on system boot
via
systemctl enable matrix.target
Usage
After you have setup you can use the following commands to manage your synapse installation:
# Start matrix-synapse, all workers and any enabled bots or bridges.
systemctl start matrix.target
# Restart matrix-synapse and all workers (not necessarily restarting bots
# or bridges, see "Bots and Bridges")
systemctl restart matrix-synapse.service
# Stop matrix-synapse and all workers (not necessarily restarting bots
# or bridges, see "Bots and Bridges")
systemctl stop matrix-synapse.service
# Restart a specific worker (i. e. federation_reader), the homeserver is
# unaffected by this.
systemctl restart matrix-synapse-worker@federation_reader.service
# Add a new worker (assuming all configs are setup already)
systemctl enable matrix-synapse-worker@federation_writer.service
systemctl restart matrix-synapse.service
The Configs
Make sure the worker_app is set in the homeserver.yaml and it does not fork.
worker_app: synapse.app.homeserver
daemonize: false
None of the workers should fork, as forking is handled by systemd. Hence make sure this is present in all worker config files.
worker_daemonize: false
The config files of all workers are expected to be located in
/etc/matrix-synapse/workers. If you want to use a different location you have
to edit the provided *.service files accordingly.
Bots and Bridges
Most bots and bridges do not care if the homeserver goes down or is restarted. Depending on the implementation this may crash them though. So look up the docs or ask the community of the specific bridge or bot you want to run to make sure you choose the correct setup.
Whichever configuration you choose, after the setup the following will enable
automatically starting (and potentially restarting) your bot/bridge with the
matrix.target.
systemctl enable <yourBotOrBridgeName>.service
Note that from an inactive synapse the bots/bridges will only be started with
synapse if you start the matrix.target, not if you start the
matrix-synapse.service. This is on purpose. Think of matrix-synapse.service
as just synapse, but matrix.target being anything matrix related, including
synapse and any and all enabled bots and bridges.
Start with synapse but ignore synapse going down
If the bridge can handle shutdowns of the homeserver you'll want to install the
service in the matrix.target and optionally add a
After=matrix-synapse.service dependency to have the bot/bridge start after
synapse on starting everything.
In this case the service file should look like this.
[Unit]
# ...
# Optional, this will only ensure that if you start everything, synapse will
# be started before the bot/bridge will be started.
After=matrix-synapse.service
[Service]
# ...
[Install]
WantedBy=matrix.target
Stop/restart when synapse stops/restarts
If the bridge can't handle shutdowns of the homeserver you'll still want to
install the service in the matrix.target but also have to specify the
After=matrix-synapse.service and BindsTo=matrix-synapse.service
dependencies to have the bot/bridge stop/restart with synapse.
In this case the service file should look like this.
[Unit]
# ...
# Mandatory
After=matrix-synapse.service
BindsTo=matrix-synapse.service
[Service]
# ...
[Install]
WantedBy=matrix.target