Deploy Synapse

Deploy and Host Synapse on Railway

Synapse is the reference Matrix homeserver — the server half of Matrix, the open standard for decentralised, end-to-end encrypted communication. It stores your accounts, rooms and message history and federates with every other Matrix server, so your users reach people on matrix.org or any other deployment without either side giving up control of its data. Self-host Synapse and you own the database while keeping the whole network. Deploy Synapse on Railway and it federates on day one, with no DNS or reverse-proxy work.

This template runs Synapse in the scaled shape the project recommends, not the single-container demo. Five services are pre-configured: synapse is the main process, owning registration, the admin API and replication; synapse-worker is a generic_worker absorbing sync and read traffic, the endpoints that dominate a busy homeserver; proxy is the only public service, a Caddy router splitting Matrix paths between those two and serving the .well-known files that make federation work on 443; Postgres is the database and Redis the replication bus. Everything but the proxy stays private.

Getting Started with Synapse on Railway

Your homeserver's name is its public Railway domain, and it is permanent — it is the suffix of every user ID and room ID, so changing it later orphans the data. An admin account is created on first boot from SYNAPSE_ADMIN_USER and SYNAPSE_ADMIN_PASSWORD; set a password you choose at deploy time. Registration is closed by default, which is right for a public URL — set SYNAPSE_ENABLE_REGISTRATION to 1 only once you know who may sign up, ideally with SYNAPSE_REGISTRATION_REQUIRES_TOKEN.

Synapse ships no web interface, so point a Matrix client at it: in Element, Cinny or FluffyChat, choose "Edit" or "Change homeserver" on the sign-in screen, enter your Railway URL, and log in as the admin. Create a room, send a message and invite a second account to confirm the worker is serving sync. To check federation, paste your domain into federationtester.matrix.org. The admin API under /_synapse/admin takes your admin access token and is how you create users, deactivate accounts and inspect rooms.

About Hosting Synapse

Matrix solves a problem most chat tools do not: conversations live on a server you control and still reach everyone else. A team self-hosting Synapse keeps history, media and account data in its own database while its users talk to contractors on matrix.org and communities on their own servers. Synapse is the implementation the Matrix specification is written against, so clients, bridges and moderation tools target it first.

Key features:

• End-to-end encryption by default in private rooms, with cross-signing and key backup
• Full federation: rooms and users addressable across every Matrix server
• VoIP and video call signalling, including group calls via Element Call
• Bridges to Slack, Discord, IRC, Telegram and WhatsApp
• A complete admin API, plus SSO via OIDC, SAML and CAS

The worker split is worth understanding. A single Synapse process handles everything, and the endpoints that saturate first are /sync and the federation read paths. Moving those to a generic_worker lets the main process concentrate on writes and replication — how Synapse is designed to scale. Both share Postgres and coordinate over Redis, so adding capacity means duplicating the worker and extending the proxy's routes.

Why Deploy Synapse on Railway

Railway removes the parts of self-hosting Matrix that usually stop people.

• TLS, DNS and the public domain are handled for you
• Federation runs over 443 via .well-known delegation — no port 8448
• Postgres and Redis are provisioned and wired up already
• The main/worker split is pre-configured, not left as an exercise
• Volumes keep media and signing keys across deploys
• Scale the worker or database from the dashboard

Common Use Cases

• A private company homeserver — internal chat your organisation owns, with encrypted rooms, SSO and reach to partners on other Matrix servers.
• A community server — a public or invite-only homeserver for a project, university or interest group, organised with Spaces.
• A bridge hub — Slack, Discord, IRC and WhatsApp in one Matrix account.

Dependencies for Synapse

• ghcr.io/element-hq/synapse:v1.161.0 — the homeserver, run as both main process and worker
• caddy:2-alpine — the public router and .well-known server
• ghcr.io/railwayapp-templates/postgres-ssl:18 — the database
• redis:8.2 — the replication bus between the two Synapse processes

Postgres is not optional here: Synapse supports SQLite only for tiny single-process installs, and workers require Postgres outright. Redis carries the replication stream — without it sync goes stale. The proxy exists because Matrix splits across two processes by URL path, and it serves the .well-known files telling other servers to reach you on 443.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/element-hq/synapse
• Docs: element-hq.github.io/synapse
• Federation checker: federationtester.matrix.org

Hardware Requirements for Self-Hosting Synapse

Synapse's memory use tracks the number and size of rooms users join, not the user count — a few large public rooms cost more than a hundred private ones.

Self-Hosting Synapse

Synapse needs a generated config before it starts. This writes homeserver.yaml and the signing key into a data volume:

docker run -it --rm \
  -v synapse-data:/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  ghcr.io/element-hq/synapse:v1.161.0 generate

Point the database block in homeserver.yaml at Postgres, start the server, then create your first administrator with the bundled CLI:

docker run -d --name synapse -v synapse-data:/data -p 8008:8008 \
  ghcr.io/element-hq/synapse:v1.161.0

docker exec -it synapse register_new_matrix_user \
  -u admin -a -c /data/homeserver.yaml http://localhost:8008

Running the worker split by hand adds a second container with its own config, a shared Redis and a reverse proxy routing each Matrix path — what this template already assembles.

How Much Does Synapse Cost to Self-Host?

Synapse is free and open source under AGPL-3.0, with no paid tier, seat limit or feature gating — the full federation, encryption and moderation feature set is in the release you deploy. Element, which maintains it, sells hosting and support, but nothing is withheld from self-hosters. On Railway you pay only for the compute, database and storage the services use.

FAQ

What is Synapse? Synapse is the reference homeserver implementation for Matrix, an open standard for decentralised, end-to-end encrypted communication. It stores your users, rooms and messages and federates with other Matrix servers.

What does this Railway template deploy? Five services: the Synapse main process, a generic_worker handling sync and read traffic, a Caddy router that is the only public service, Postgres, and Redis for replication between the two Synapse processes.

Why does the template include Postgres and Redis? Synapse requires Postgres for any deployment using workers — SQLite is supported only for small single-process installs. Redis carries the replication stream keeping the worker in sync; without it it never sees new events.

How do I connect a client to my self-hosted Synapse? On the sign-in screen of Element, Cinny or FluffyChat, choose to change the homeserver, enter your Railway URL, and sign in. There is no web UI on the server itself.

Can I change the server name after deploying Synapse? No. It is the suffix of every user ID and room ID, so changing it invalidates every account and room. Decide it before creating your first user.

Does federation work on Railway without opening port 8448? Yes. The proxy serves /.well-known/matrix/server, telling other homeservers to reach yours on 443, so federation runs over standard HTTPS with the certificate Railway manages.