Synapse single process vs workers

The Synapse workers documentation recommends that small instances run in the default monolith mode, and it suggests splitting functionality into multiple Python processes only for larger deployments where performance is a concern. The decision to split therefore starts with evidence that the monolith is the bottleneck, not with an assumed user count. Before any change, the team should be able to name the constraint it expects workers to remove, such as slow client sync, delayed federation traffic or a busy event writer.

Start with baseline measurements on the existing homeserver: CPU and memory per process, PostgreSQL load, request latency for client and federation endpoints, and the time it takes users to join large rooms and complete sync. Separate client traffic from federation traffic, since the generic worker and the reverse proxy routing treat them differently. Check whether load is concentrated in a few expensive room joins or spread evenly, and whether the spikes line up with particular federated servers. Confirm these figures in the client's own environment, because the traffic patterns of one organization rarely match another's.

Once workers are on the table, weigh the operating effort against the gain. A split deployment adds Redis for replication, a reverse proxy that routes each request path to the correct worker, extra process supervision and a more involved upgrade path, and the upgrade notes warn that rolling back can be difficult because of schema changes. DeployOpen would confirm the measured bottleneck, the expected gain and the ongoing support load in writing before recommending any change, and would ask for a rollback plan and a staged test on a copy of production data first.

The main cost of a worker build is not the software, which is open source, but the people and infrastructure that run it. Each worker process, the Redis server that relays replication between processes, and the PostgreSQL database all need their own compute, memory, monitoring and patching. The Synapse workers documentation says Redis carries the replication stream and can also serve as a shared cache, so Redis is a component you must size, secure and keep available, not an optional extra. Ask for each process to be listed with its host or container, its resource allocation, and who owns its backups and patching. Synapse workers also require PostgreSQL, so any database sizing and high availability design is part of the same bill, and it should be quoted separately so the database cost is visible.

The reverse proxy is where most of the one-time build work sits. The Synapse workers documentation says an HTTP reverse proxy such as nginx or HAProxy must route each request path to the correct worker or the main process. Someone has to write those routing rules, map every client, federation and admin path, and test each route, including the paths that only appear under real federation traffic. Ask the vendor to name the test cases, the environments where routing will be exercised, and whether load and failover tests are included. Recurring work follows from every Synapse upgrade, because new endpoints and changed stream assignments can require routing updates. A quote should show the one-time build and the expected operations as separate line items, with the upgrade process described in the written scope.

Upgrades are the largest recurring cost. The Synapse upgrade notes warn that rolling back can be difficult because of database schema changes between releases, and that Synapse drops support for Python and PostgreSQL versions when they reach upstream end of life. A worker estate multiplies this work, since every process must move to the same release in a coordinated order. Before signing, confirm who writes the upgrade runbook, who holds the database backups needed for a safe rollback, and whether monitoring and on-call coverage are included. Fixed-scope build work and an ongoing support arrangement should be priced separately, so you can see which part you pay once and which part recurs for as long as the deployment runs.

Moving from a single process to workers later is an infrastructure project, not a configuration tweak. A working PostgreSQL-backed Synapse must gain a Redis server that carries the replication stream, worker processes such as the generic worker or dedicated stream writers, and an HTTP reverse proxy such as nginx or HAProxy that routes each request path to the correct process. Each of those components changes how traffic flows, so the migration touches the proxy, the homeserver configuration and the monitoring at once. Confirm with your team which of these pieces already exist in your environment, such as a Redis service or a proxy with path-based routing, before you estimate the work.

Rollback is the risk to plan for first. The Synapse upgrade notes warn that rolling back can be difficult because database schema changes between releases may not reverse cleanly, so a version change combined with a topology change compounds that exposure. Take a verified PostgreSQL backup and record the exact Synapse version before any change. Keep the monolith configuration in version control so you can restart it without rebuilding from memory. Check the Synapse upgrade notes for the release you run before you start, and confirm the expected rollback path with Element or your implementation partner in writing.

Run the change first in a non-production environment built from a recent copy of production data, with the same Synapse, PostgreSQL and Redis versions. Test client login, message send and receive, federation if enabled, and media upload through the new proxy routes, then time a rollback from the workers layout back to the monolith. We recommend treating that rehearsal as a gate: do not schedule the production change until the rollback has been performed successfully at least once and the team has written down who makes the call to revert. This staged approach reduces risk, but it does not guarantee a clean migration in every environment.