Make Your Matrix Synapse Server Reachable for Federation

To make a Matrix Synapse homeserver federate, make its server name discoverable and reachable from the public internet over HTTPS, then route Matrix server-to-server requests to Synapse. In a common setup, a reverse proxy handles TLS on port 443 and a /.well-known/matrix/server file points your Matrix domain to that proxy. If Synapse already answers on your server-name domain at port 8448, you may not need delegation.

This walkthrough uses example.com as the permanent Matrix server name and matrix.example.com as the machine or proxy endpoint. Replace both with your own names. A homeserver stores Matrix accounts and rooms; federation lets homeservers communicate. DNS, firewall rules, proxy syntax, container networking, and certificates depend on your host.

Before you change configuration

Decide whether users’ Matrix IDs should look like @name:example.com or @name:matrix.example.com. The value of server_name in homeserver.yaml becomes part of Matrix IDs and room addresses. Synapse’s installation documentation says to choose it before installation because it cannot later be changed without consequences. If Synapse is already in use, do not change it just to match a web address; use delegation to keep existing IDs.

A YAML editor displays server_name: example.com and a reminder to choose the value before installation.
The server name is part of Matrix IDs, so confirm it before continuing.

Before editing, make sure you can access Synapse, the proxy, and public DNS, and have a valid TLS certificate for the federation endpoint. Back up homeserver.yaml and the signing key, which establishes the homeserver’s identity. Keep that key safe; routine federation setup does not call for regenerating it.

Set up the public route

1. Confirm Synapse’s HTTP listener

Synapse commonly listens for HTTP on port 8008 behind a reverse proxy. In the listener that accepts proxy traffic, set x_forwarded: true so Synapse can use the proxy’s forwarded client address and scheme. The proxy must set the appropriate X-Forwarded-For and X-Forwarded-Proto headers, rather than passing arbitrary values supplied by outside clients.

A YAML listener excerpt shows Synapse on HTTP port 8008 with x_forwarded enabled and a loopback bind address.
The listener accepts HTTP from a local proxy and enables Synapse’s forwarded-header handling.

Binding to 127.0.0.1 is suitable when the proxy runs on the same host. It is not suitable when the proxy is in another container or machine unless that address is reachable from the proxy. In a container deployment, use the network address or service name that the proxy can reach, and restrict access through the container network or firewall. Keep the existing listener structure and edit the relevant values; do not paste a fragment blindly over the rest of your configuration.

2. Route Matrix paths through the proxy

Configure the proxy’s HTTPS virtual host to forward both /_matrix and /_synapse/client to Synapse’s HTTP listener. The first path carries Matrix APIs, including federation; the second is used for Synapse client endpoints. Follow the official example for your proxy software, preserve the request path, and send the forwarded headers Synapse expects. Do not normalize, decode, or rewrite URI paths: Matrix request signatures can fail if a proxy changes the encoded path.

A reverse proxy configuration editor shows Matrix API and Synapse client paths routed to localhost port 8008 with forwarded headers.
The proxy must pass both Matrix API paths to Synapse without rewriting the URI.

The exact configuration differs across Nginx, Caddy, Apache, load balancers, and managed hosting. Use the vendor’s current syntax and the Synapse reverse-proxy documentation as the reference. A proxy rule that serves the web client but omits the federation API path is not enough.

3. Make DNS, HTTPS, and the chosen port agree

For the example, matrix.example.com must resolve to the proxy or load balancer, and port 443 must be reachable from outside. The proxy needs a valid certificate for matrix.example.com. If you instead serve federation directly at example.com:8448, publish that route and certificate and open port 8448. Use either direct port 8448, the conventional default, or delegation to another host and port such as 443.

Confirm DNS, firewall or cloud security-group rules, and the certificate from outside your private network. If a CDN or tunnel sits in front, whether it supports the required Matrix traffic depends on that service’s current configuration; check its documentation and test the actual route rather than assuming compatibility.

Publish federation discovery when needed

4. Add server delegation for a separate endpoint

If the Matrix ID domain is example.com but Synapse is reachable at matrix.example.com:443, serve this JSON over HTTPS at https://example.com/.well-known/matrix/server:

{
  "m.server": "matrix.example.com:443"
}
A browser-style JSON view at example.com/.well-known/matrix/server contains the m.server value matrix.example.com:443.
This federation discovery record delegates example.com to the HTTPS endpoint at matrix.example.com on port 443.

Port 443 is explicit in this example; if you omit a port, Matrix discovery defaults to 8448. Do not confuse this file with /.well-known/matrix/client, which helps clients find the client-server API and is separate from server-to-server federation. Synapse can serve a server well-known file itself when the server-name domain is routed directly to Synapse, but with a separate endpoint you normally publish the file on the server-name domain’s web server.

Federation discovery is specified by Matrix and documented by Synapse. The Matrix specification allows discovery through /.well-known/matrix/server; check the Synapse delegation instructions before choosing a different method such as an SRV record, which also affects TLS expectations.

Test from outside the server

5. Verify the record, then run a federation check

Request the discovery URL from a machine outside the server’s private network. It should return the JSON object above over HTTPS without a login page, HTML redirect, certificate warning, or unrelated website. Then check that the delegated hostname resolves, its certificate is valid, and its advertised port reaches Synapse. Use your proxy’s config checker and reload procedure before testing.

Finally, enter your server name (for example, example.com, not the delegated hostname unless that is your server_name) in the official Matrix Federation Tester. The Synapse federation guide also suggests testing by joining a public room such as #synapse:matrix.org. A successful check confirms that common discovery and reachability checks passed; it does not guarantee every remote server or every room operation will work, because remote policies and network conditions vary.

If the tester reports that your server cannot be reached, check the domain and port it tried, DNS, firewall rules, certificate name, proxy paths, forwarded headers, and whether a redirect changed the request. The current Synapse federation documentation specifically warns that Synapse’s federating servers may not follow HTTP 308 redirects in some cases. Avoid relying on a 308 redirect for the federation endpoint and retest after correcting it. Consult documentation matching your installed Synapse release for version-specific behavior.

Federation requires remote homeservers to discover and reach your federation API. Whether that works for every remote server cannot be known from configuration alone. Confirm the route with the tester and a real room join, then investigate the specific failing endpoint or error.

These interface panels are schematic examples of configuration and discovery data, not screenshots from a live server. Documentation references checked October 10, 2026.

Leave a Comment

Resolve Matrix Room Admin Permission Errors by Action

Trace M_FORBIDDEN to room power levels, membership, or Synapse server-admin access, then restore only the permission the blocked action needs.

Make Your Matrix Synapse Server Reachable for Federation

Make Your Matrix Synapse Server Reachable for Federation

Configure Synapse discovery, HTTPS, and proxy routing so other Matrix homeservers can find and contact your server.

Connect Element Web to Keycloak Through Synapse OIDC

Configure a Keycloak OIDC client and Synapse provider so Element Web users can sign in through your identity server without exposing client secrets.

Set Up Element Key Backup and Cross-Signing Safely

Set Up Element Key Backup and Cross-Signing Safely

Save a recovery key, verify your Element sessions, and check that encrypted message keys can be restored without confusing backup with your account password.

Stop Matrix Synapse Memory Crashes During Client Sync

Diagnose Synapse out-of-memory failures during sync, adjust caching safely, identify request backlogs, and verify stable memory use.

Resolve Synapse Federation TLS Certificate Errors

Trace Matrix federation certificate failures to the correct server, repair the TLS chain or CA trust, and verify the fix without disabling security checks.

Put a Synapse Matrix Server Behind Cloudflare Safely

Put a Synapse Matrix Server Behind Cloudflare Safely

Route Matrix clients and federation through Cloudflare on HTTPS 443, preserve Synapse discovery, and avoid caching API traffic or breaking media uploads.

Restore Matrix Synapse Safely with a PostgreSQL Dump

Back up Synapse with pg_dump, protect its signing key and media, and restore into a clean PostgreSQL database without reusing stale one-time keys.

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Run Mjölnir as a Matrix Room Moderation Bot with Docker

Set up Mjölnir with a dedicated Matrix account, encrypted management room, Docker Compose, policy list, and permission checks.

Enable Native Matrix Sliding Sync for Faster Mobile Loading

Enable Native Matrix Sliding Sync for Faster Mobile Loading

Skip the retired proxy and configure Synapse’s built-in Sliding Sync. Check client discovery, then measure room-list loading and reconnect behavior on a compatible phone.