---
title: "Deploy Synapse"
description: "Matrix homeserver for decentralised, end-to-end encrypted chat"
category: "Other"
url: https://railway.com/deploy/synapse
---

# Deploy Synapse

Matrix homeserver for decentralised, end-to-end encrypted chat

**[Deploy Synapse on Railway](https://railway.com/template/synapse)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/synapse/manifest.json

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### synapse https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/matrix-synapse-light.svg

- **Source:** https://github.com/gridalpha/synapse-railway
- **Health check:** /health

### proxy https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/caddy.svg

- **Source:** https://github.com/gridalpha/synapse-railway
- **Health check:** /healthz
- **Public domain:** Yes

### synapse-worker https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/matrix-synapse-light.svg

- **Source:** https://github.com/gridalpha/synapse-railway
- **Health check:** /health

## Documentation

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

![Diagram of the Synapse, worker, proxy, Postgres and Redis services](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789552024/synapse-architecture.webp)

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

![Matrix room conversation between two users with the member list open](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789552040/synapse-release-planning-room.webp)

![Creating a federated Matrix room with encryption and access options](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789552053/synapse-create-room.webp)

![Synapse admin API listing the homeserver's two registered accounts](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789552066/synapse-admin-api-users.webp)

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

| Variable | Purpose |
|---|---|
| `SYNAPSE_SERVER_NAME` | The homeserver's identity; permanent once set |
| `SYNAPSE_ADMIN_USER` / `SYNAPSE_ADMIN_PASSWORD` | The admin account created on first boot |
| `SYNAPSE_ENABLE_REGISTRATION` | Open signup; `0` (closed) by default |
| `SYNAPSE_REGISTRATION_REQUIRES_TOKEN` | Require an invite token when signup is open |
| `SYNAPSE_FEDERATION_ENABLED` | Join the wider Matrix network; `1` by default |
| `SYNAPSE_MAX_UPLOAD_SIZE` | Largest accepted media upload, default `50M` |
| `SYNAPSE_PRESENCE_ENABLED` | Online/offline presence, expensive at scale |

### Deployment Dependencies

- Source: [github.com/element-hq/synapse](https://github.com/element-hq/synapse)
- Docs: [element-hq.github.io/synapse](https://element-hq.github.io/synapse/latest/)
- Federation checker: [federationtester.matrix.org](https://federationtester.matrix.org)

## Hardware Requirements for Self-Hosting Synapse

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU per Synapse service | 2 vCPU main, 2 vCPU worker |
| RAM | 1 GB main, 512 MB worker | 2 GB main, 1 GB worker |
| Storage | 5 GB volume | 20 GB+, grows with media and state |
| Database | Postgres 13+, `C` collation | Postgres 18 |

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.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/synapse