Choose the server name
The user-facing server name can be difficult to change later. Understand delegation and the well-known records used by your deployment. Test client discovery and federation rather than assuming a successful web login proves both.
Use a supported stack
Synapse commonly uses PostgreSQL for production data, with supporting services depending on scale and configuration. Follow current upstream recommendations. Keep workers, database and reverse proxy timeouts compatible with the load.
Keep encryption claims accurate
End-to-end encryption protects content in supported encrypted rooms between participating clients. The homeserver can still process metadata and non-encrypted content. Client key backup, verification and account recovery need their own explanation.
Maintain the instance
Restrict registration when appropriate, protect administrative and shared-secret interfaces and set deliberate media and event retention. Back up the database, configuration and signing keys consistently, then test recovery.
Test the client and federation paths separately
A client such as Element reaches the homeserver’s client API, while other homeservers use federation discovery and endpoints. A reverse-proxy change can break one while leaving the other working. Test a new account, a local room and an authorised federated room, then verify encryption and recovery behaviour from the client.
Official documentation: Current Synapse installation guide
Keep durable identity material
The database is not the entire homeserver identity. Preserve the signing key and relevant configuration and secrets with a consistent backup. Check which external media and history are retained and set a policy suitable for your community. Monitor storage and worker queues before growth becomes an outage.
Separate the account name from the hosting endpoint
Decide the Matrix server_name before account creation: it becomes part of user and room identifiers. The web hostname serving Synapse can differ when discovery/delegation is configured correctly. Plan both client discovery and server-to-server discovery, a valid certificate and the address family actually reachable. Element is a client, not a replacement for the homeserver. Keep an independent administrator route and a recovery contact outside the homeserver.
- Choose a supported Synapse release and a production-appropriate PostgreSQL deployment.
- Keep the database and administrative listeners private.
- Define registration and federation policy explicitly.
Official documentation: Synapse installation · Matrix delegation
Build discovery and the proxy as part of the service
Generate configuration for the selected release, persist the signing key and database, and configure the proxy according to the official Synapse guidance. The externally visible origin, forwarded headers and request paths must agree. If delegation is used, serve the required well-known documents from the identity domain. Do not expose the raw internal API port to solve a proxy error. Keep registration secrets out of the browser client configuration.
Official documentation: Synapse reverse proxy
Test a client session and a federation session
Create a test account, connect a supported client, send a local message and upload a small file. Verify client discovery independently from federation discovery, then test a room with another permitted server if federation is intended. In an encrypted room, exercise verification and the client’s key-recovery flow. Homeserver backup does not automatically restore every client-held decryption key. Explain which metadata the server retains and which rooms are encrypted.
# Discovery checks use your identity domain and HTTPS:
curl --fail https://example.com/.well-known/matrix/client
curl --fail https://example.com/.well-known/matrix/serverUse the error location to narrow the repair
If Element cannot discover the server, inspect the client well-known response and TLS origin. If local messaging works but federation fails, inspect federation delegation, reachable addresses, certificates and policy. Repeated media failures can involve upload limits or storage. Preserve the database, media, configuration and signing keys consistently; test restore without federation enabled first, so an exercise does not create a competing copy of the production identity.