Matrix Synapse with PostgreSQL

The reference Matrix homeserver — wired to PostgreSQL out of the box.

Service #chat#messaging#matrix#federation#postgresql

Matrix Synapse is the reference homeserver implementation of the Matrix protocol — an open, decentralized, federated standard for real-time chat, voice, video, and end-to-end encrypted messaging. This template ships Synapse plus a PostgreSQL backend (the only production-supported database for Synapse), pre-wired so federation and large rooms perform correctly from day one.

Deploy with Pier

1 Open the Pier dashboard and click Add service.
2 Pick Matrix Synapse with PostgreSQL from the template list.
3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is Matrix Synapse?

Matrix is an open standard for decentralized, federated real-time communication — chat, voice, video, files, end-to-end encryption. Synapse is the reference homeserver: the original implementation, maintained by the Matrix.org Foundation in Python, and the one that ships every spec feature first.

Run a Synapse homeserver and your users (alice:example.com, bob:example.com) can chat with users on any other Matrix server — like email but for chat. Bridges link Matrix rooms to Telegram, Discord, Slack, WhatsApp, Signal, IRC and more, so a single Element client can show every conversation.

How Pier deploys it

This template runs Synapse plus a dedicated PostgreSQL backend in one Compose stack. Postgres is the only production-supported database for Synapse — SQLite cannot keep up with federation joins on busy rooms.

Default ports: 8008 (HTTP, behind Traefik). You attach a custom domain at Pier and Traefik handles TLS. Synapse needs the Matrix server name to match a .well-known/matrix/server file on the apex domain; configure it in the Pier env vars or serve it from a separate Pier service.

After the first launch, create the admin user with register_new_matrix_user via docker exec. From there, point any Element client at your homeserver URL to log in.

When NOT to use Matrix Synapse

If you only need single-org closed chat (no federation, no bridges), a lighter alternative like Mattermost is simpler to operate. If you want the cutting-edge spec features but a smaller server, try matrix-synapse-sqlite (this catalog) for personal/test use, or Dendrite / Conduit for an experimental lightweight homeserver. Synapse remains the right answer for any federation-heavy or bridge-heavy deployment.

Key features

Federated by design

Your homeserver talks to every other Matrix server on the open network. Users on your domain can join rooms hosted anywhere, and vice versa — like email, but for chat.

End-to-end encryption

Native E2EE via the Olm/Megolm Double Ratchet. Direct messages and private rooms are encrypted with per-device keys; the server never sees plaintext.

Bridges to everything

Matrix bridges connect rooms to Telegram, Discord, Slack, WhatsApp, Signal, IRC, XMPP, Mattermost — run your team chat on Matrix without forcing every contact to migrate.

Voice, video, and conferencing

1-to-1 calls via WebRTC; group calls via Element Call or Jitsi bridge. Conferencing scales to dozens of participants with SFU.

PostgreSQL backend

The only production-supported database for Synapse — SQLite cannot keep up with federation traffic. This template wires Synapse to a dedicated Postgres so you skip the most common scaling pitfall.

Open governance

Spec maintained by the Matrix.org Foundation (non-profit). Anyone can run a homeserver, anyone can implement a client. No vendor controls the protocol.

Use cases

Self-hosted team chat

Replace Slack / Discord / Teams with a homeserver your org owns. Element web/mobile/desktop clients give a polished UX without losing data sovereignty.

Community / project chat

Run a community Matrix server for an open-source project, university, or DAO. Federation means users keep their existing Matrix identity if they have one.

Secure messaging for high-trust environments

Governments (France, Germany, Sweden), defense contractors, and healthcare orgs deploy Matrix for E2EE messaging where Slack/Teams cannot be approved.

Bridged team workspace

One Element client showing your Matrix rooms + bridged Telegram, WhatsApp, and Discord channels. Stop tab-juggling between four chat apps.

Bot platforms and ChatOps

Matrix's open API and bot frameworks (matrix-bot-sdk, maubot) make automation simpler than walled-garden alternatives.

Code examples

First-user registration (admin) bash

docker exec -it pier-synapse-synapse \
  register_new_matrix_user \
    -u alice \
    -p strongpassword \
    -a \
    -c /data/homeserver.yaml \
    http://localhost:8008

Federation test bash

curl https://federationtester.matrix.org/api/report?server_name=matrix.example.com | jq .

Discovery .well-known files bash

# /.well-known/matrix/server (port 443 of matrix.example.com)
{"m.server": "matrix.example.com:443"}

# /.well-known/matrix/client
{
  "m.homeserver": { "base_url": "https://matrix.example.com" },
  "m.identity_server": { "base_url": "https://vector.im" }
}

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"deactivated": true}' \
  https://matrix.example.com/_synapse/admin/v1/deactivate/@spammer:matrix.example.com

How it compares

vs Element (the client) + Synapse (the server)	Element is the most popular Matrix client; Synapse is the reference server. This template ships the server. Element clients (web, iOS, Android, desktop) connect from anywhere — point them at your homeserver URL.
vs Dendrite, Conduit	Alternative Matrix homeservers in Go and Rust. Lighter than Synapse but less feature-complete. Synapse remains the production default for federation-heavy deployments.
vs Mattermost / Rocket.Chat	Closed federation (one server per org). Easier to operate but no cross-org federation, no Matrix bridges, no E2EE by default. Choose Matrix when you need open federation; Mattermost/Rocket for a single-org closed deployment.
vs Slack / Discord / Teams	SaaS-only, no self-host, no E2EE, walled gardens. Matrix is the open alternative — federated, self-hosted, E2EE-by-default in DMs.

Frequently asked questions

Why PostgreSQL and not SQLite?

SQLite is fine for tiny single-user homeservers but cannot keep up with federation joins on busy rooms (matrix.org HQ,

What domain configuration do I need?

Synapse needs a Matrix server name (e.g. matrix.example.com) that matches the .well-known/matrix/server file served at example.com. The server name is permanent — you cannot change it without re-registering every user.

How do I disable open registration?

Set enable_registration to false in homeserver.yaml (default). Use the registration secret to create users via the admin script, or set up a registration token system.

What about voice and video?

1-to-1 calls work out of the box (WebRTC). For group calls and conferences, run Element Call or pair Synapse with a Jitsi instance. A TURN server (coturn) is needed for users behind strict NAT.

How big can a single Synapse get?

Synapse scales vertically well into thousands of active users on a single node with workers. Beyond that, federation joins on huge rooms (10k+ members) are the bottleneck — consider an alternate homeserver (Dendrite/Conduit) for very small or very experimental deployments.

Bridges to other platforms?

matrix.org maintains bridges for Telegram (mautrix-telegram), Discord, WhatsApp, Signal, IRC, XMPP, Slack, and more. Each bridge is a separate service that talks to Synapse via the appservice API.

Backups?

Back up the PostgreSQL database (pg_dump) plus the Synapse media store volume. Restore both onto a fresh server with the same domain to get a working homeserver back online.

Related services

Deploy on your VPS

Deploy this service →