Official guidance requires TURN for reliable voice and video routing across real-world networks.

Communications guide

Self-Host Matrix Synapse: Decide the Domain Before Docker

Q: Is Synapse a complete chat app?

No. Synapse is a Matrix homeserver backend; users still need a Matrix client such as Element.

Q: Can the server name change later?

Treat it as an identity decision made before launch because Matrix user IDs and federation depend on it.

Q: What must be backed up?

Protect Postgres, the media store, signing keys, configuration, secrets, and deployment files as one recovery set.

Plan a Matrix Synapse homeserver around its identity domain, client, Postgres, reverse proxy, TURN, signing keys, media, and tested recovery.

Published and reviewed by OpenAlt · September 25, 2026

A group of people discussing ideas around laptops in a bright, modern office space. — Photo by Ivan S on Pexels

TL;DR

Choose the permanent Matrix identity domain before deploying Synapse. That domain becomes part of every user ID, such as @alex:example.org, and changing it later is a migration project rather than a routine configuration edit.

A practical production design has five parts: Synapse as the homeserver, a Matrix client such as Element, PostgreSQL for application data, a reverse proxy for HTTPS and federation, and TURN for reliable voice and video calls. Store the database, media, signing keys, and configuration in durable backups, then prove that restoration works before trusting the server.

Synapse is the server backend, not the complete chat application. After the architecture is settled, review OpenAlt’s Synapse profile, the team chat directory, and Slack alternatives.

Choose the identity domain first

The domain in server_name is the most important decision in a Synapse deployment. It determines the namespace users see in Matrix IDs and participates in room and federation identity. Pick a domain your organization controls and expects to keep for years.

The identity domain does not have to be the hostname of the Docker server. You can host Synapse at a separate service hostname and use DNS plus Matrix well-known delegation to tell clients and other homeservers where to connect. That separation is useful, but it does not make the identity domain disposable.

Decide these points before generating configuration:

Will users be @name:company.example or use another permanent domain?
Will the server federate with outside homeservers?
Will people use voice and video calls?
Who owns DNS, TLS certificates, backups, and upgrades?
Is the service private to one organization or open to external rooms?

The official Synapse installation documentation emphasizes that the chosen server name is central to production setup. Treat it as an architectural decision, not a value to experiment with after launch.

Map the architecture

Component	Responsibility	Decision
Synapse homeserver	Accounts, rooms, events, federation	Official Synapse image
Matrix client	User interface for chat and calls	Element or another compatible client
PostgreSQL	Durable application database	Use for production deployments
Reverse proxy	HTTPS termination and public routing	Required for a clean public endpoint
TURN server	Relays media when direct calls fail	Required for reliable VoIP

This separation clarifies what self-hosting means. Installing Synapse alone does not provide a polished desktop or mobile experience; users still need a client. PostgreSQL protects the transactional data, while Synapse’s media store contains uploaded files and attachments. The proxy exposes the service safely, and TURN handles difficult network conditions.

Deploy with Docker Compose

Use the official Synapse image and a separate PostgreSQL service. The official documentation lists matrixdotorg/synapse and ghcr.io/element-hq/synapse as official images and includes a Compose example under contrib/docker. Start from that maintained structure, generate the Synapse configuration with the final server name, and pin an image release before production use.

A conceptual Compose layout looks like this:

services:
  synapse:
    image: matrixdotorg/synapse
    restart: unless-stopped
    depends_on:
      - postgres
    volumes:
      - ./synapse-data:/data

  postgres:
    image: postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: synapse
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
    secrets:
      - postgres_password
    volumes:
      - postgres-data:/var/lib/postgresql/data

secrets:
  postgres_password:
    file: ./secrets/postgres_password

volumes:
  postgres-data:

This illustrates the service relationship, not a complete production configuration. Configure Synapse’s database connection to use the same PostgreSQL credential through your deployment’s secret-injection method. Generate the password securely; never commit it to Compose, homeserver.yaml, or a public repository.

Keep Synapse data and PostgreSQL data on durable storage. Restrict database access to the application network, expose only the proxy publicly, and make container restarts predictable. Before inviting users, confirm that Synapse can create accounts, send messages, upload media, and restart without losing state.

An IT professional operates a computer in a server room, managing network systems and connected devices. — Photo by panumas nikhomkhai on Pexels

Detailed image of illuminated server racks showcasing modern technology infrastructure. — Photo by panumas nikhomkhai on Pexels

Publish well-known and federation endpoints

Federation is optional, but the decision should be explicit. A private server can communicate only among its own users; a federated server can exchange rooms and events with other Matrix homeservers.

For a public deployment, configure DNS, HTTPS, and the reverse proxy together. Matrix clients and remote servers may need well-known responses that map the identity domain to the actual homeserver location. Check both client discovery and server discovery from outside your network, then test registration, login, room creation, and a federation flow with a trusted external account.

Follow the official reverse proxy guidance for routing and TLS behavior. Do not assume that a working local container means the public federation path is correct. Firewalls, certificate chains, proxy headers, and DNS delegation all matter.

Add TURN for calls

TURN is required for reliable VoIP routing because many users cannot establish a direct media connection. Text chat may work without it, while calls fail only on particular networks, mobile connections, or restrictive corporate firewalls.

Deploy a TURN service, create credentials according to its configuration, and connect those settings to Synapse. Test calls from different networks, including a mobile connection. The official TURN documentation explains the required Synapse settings and operational considerations.

If calls are not part of the service, document that limitation instead of silently assuming they will work. If calls matter, treat TURN as a first-class production dependency.

Back up and test restoration

A useful backup contains more than PostgreSQL. Protect these four categories:

The PostgreSQL database, including users, rooms, events, and state.
Synapse’s media store, including uploads and attachments.
Federation signing keys, which establish the server’s cryptographic identity.
homeserver.yaml and related configuration, including carefully protected secrets.

Use encrypted, access-controlled storage and retain versions rather than one constantly overwritten copy. Backups should be independent of the host running Docker; a disk snapshot on the same machine is not enough protection from host loss or operator error.

Perform a restoration test on a separate environment. Restore the database, media, signing keys, and configuration, then start Synapse and verify login, room history, media downloads, and federation identity. The official backup and restore documentation should be your recovery reference.

Upgrade deliberately

Pin the Synapse image used in production, record the current version, and take a verified backup before upgrading. Review the release instructions, start the new container, watch logs for migrations or configuration errors, and test login, messaging, media, and calls.

Rollback should be a tested recovery procedure, not merely changing the image tag back. Database migrations can make an immediate binary downgrade unsafe. Keep the previous image available, but rely on a tested backup and restore path when a failed upgrade requires more than a quick correction.

When managed Matrix is saner

Managed Matrix is usually the better choice when your organization lacks dependable operations coverage, needs high availability, or cannot own the burden of federation, TURN, backups, TLS, and upgrades. It is also sensible when the goal is simply dependable team messaging rather than infrastructure control.

Self-hosting is compelling when you need control over data location, identity, retention, integrations, or network boundaries and have someone responsible for maintenance. Make that trade deliberately. A low-cost server can still require meaningful time during outages, upgrades, and recovery tests.

FAQ

Is Synapse a complete chat app?

No. Synapse is the homeserver backend. Users connect through a Matrix client such as Element, which provides the chat interface and client-side calling experience.

Can the server name change later?

Not casually. The server name is embedded in Matrix identities and federation relationships. A change may be possible through a carefully planned migration, but choose the permanent domain before generating production configuration.

Is TURN required?

TURN is required for reliable voice and video routing across restrictive networks. It is not required for basic text messaging, but calls may fail unpredictably without it.

What must be backed up?

Back up PostgreSQL, the media store, federation signing keys, and Synapse configuration. Protect backup credentials separately, and regularly restore the complete set in an isolated environment.

Does self-hosting require federation?

No. You can run a private homeserver for users under your control. Federation is an intentional capability; enable and test it only when your organization needs communication with other Matrix servers.