How to Set Up Federation on Matrix Synapse: A Step-by-Step Guide

Matrix federation lets a Synapse homeserver exchange room events with other homeservers so people using different servers can participate in the same room. To set it up, make Synapse’s federation API reachable over HTTPS, publish the correct server discovery information, allow the required network traffic, and test the public endpoint. Simply starting Synapse or opening port 8448 is not enough if DNS, TLS, or proxy routing is wrong.

This guide uses a typical reverse-proxy deployment: the Matrix identity domain is example.org, Synapse runs at matrix.example.org, and the proxy handles TLS on port 443. Replace both example domains with your own. If Synapse is already reachable over HTTPS on example.org:8448, you usually do not need delegation. Commands and file paths depend on whether you installed Synapse from a package, a virtual environment, or a container.

What must be true before federation can work?

• Your Synapse server has a stable public server_name. This name appears in Matrix IDs such as @alex:example.org; changing it later is not a routine hostname edit.
• Other homeservers can reach the federation API over HTTPS and validate the TLS certificate.
• Server discovery leads remote homeservers to the correct host and port. The standard federation port is 8448; delegation can point to HTTPS on 443.
• Firewall rules allow inbound traffic on the federation endpoint you chose and outbound federation connections.

Federation is about server-to-server communication. It does not automatically make private rooms public or invite other users. Users still need to join or be invited to rooms, and room membership and room settings determine who can participate. Start by deciding what your Matrix IDs should look like, then use that same domain as Synapse’s server_name.

Step 1: Check the Synapse server name and deployment

Open the active homeserver.yaml and confirm that server_name is the domain you intend to keep. A common arrangement is:

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

server_name determines the domain in users’ Matrix IDs. public_baseurl is the public client-facing URL, such as the URL people enter into a client; behind a reverse proxy it should name the proxy URL. They serve different purposes, so do not replace the server name with a backend container name or change it just to match a subdomain. If the server is already in use, back up its configuration and database before changing networking settings.

Check how Synapse is installed and managed. A systemd service, Docker Compose stack, Kubernetes deployment, and managed hosting product use different restart and networking procedures. Apply the examples below to the correct configuration file and preserve any existing listeners and custom settings.

Step 2: Choose direct federation on 8448 or delegation to 443

There are two common routes for incoming federation:

• Use the default port 8448: point DNS for the server_name domain to the server, expose HTTPS on port 8448, and present a certificate valid for that domain. If the APIs are available at the domain named by server_name on port 8448, Synapse documentation says delegation is not needed.
• Use port 443 with delegation: serve https://example.org/.well-known/matrix/server with JSON directing other servers to the actual endpoint, for example {"m.server":"matrix.example.org:443"}. The delegated hostname must resolve publicly and present a valid certificate for matrix.example.org.

Port 8448 is not mandatory in every deployment. If you use delegation to 443, inbound federation can use 443 instead. If outbound connections are restricted by an egress firewall, allow both 443 and 8448 because remote servers may use either. Choose one incoming route and make the DNS record, TLS certificate, reverse proxy, and firewall agree with it.

Step 3: Route Synapse’s federation API through the reverse proxy

Synapse commonly listens on HTTP port 8008 behind a reverse proxy. The proxy terminates HTTPS and forwards the Matrix endpoints to Synapse. In the relevant homeserver.yaml listener, ensure the HTTP listener includes both the client and federation resources and trusts the proxy headers:

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

This is an example listener, not a drop-in replacement for every installation’s full configuration. If Synapse runs in a container, binding to 127.0.0.1 inside the container may prevent the proxy container from reaching it; use the service network and a suitable bind address instead. Keep the backend listener private and expose only the proxy as intended.

Configure the proxy to forward requests for /_matrix and /_synapse/client to port 8008, setting X-Forwarded-For and X-Forwarded-Proto. For NGINX, the essential location can look like this:

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

Use the correct upstream address for your host or container network. Do not append a rewritten path to proxy_pass; Synapse’s proxy guidance warns that normalizing encoded request paths can cause federation signature-verification errors. Align the proxy upload-size limit with the Synapse media upload setting if users need to upload larger files.

Step 4: Configure TLS and DNS

Obtain a publicly trusted TLS certificate for the hostname that serves federation. With the reverse-proxy setup above, that is matrix.example.org when using delegation to that host. Confirm that the proxy serves the full certificate chain, renews certificates automatically, and presents the right certificate on the port remote servers will contact. A self-signed certificate or a certificate for the wrong hostname will fail validation on other homeservers.

Create a public A record and, if you use IPv6, an AAAA record for matrix.example.org pointing to the proxy. Verify that both records reach the intended service; an incorrect AAAA record can cause failures for IPv6-capable remote servers even when IPv4 works. If you use port 8448 directly, DNS for example.org must lead to the listener and its certificate must match example.org.

Step 5: Publish server discovery information

For the delegated example, make the HTTPS URL below return status 200 and JSON with the exact endpoint:

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

Serve it as application/json. Check that it is publicly readable without login, that it does not redirect in a loop, and that the hostname and port match the TLS proxy. Do not publish matrix.example.org in the file if the proxy actually routes federation somewhere else.

Synapse can serve this file itself with serve_server_wellknown: true only when requests to https://<server_name>/ are routed to Synapse appropriately. If your server name is example.org but Synapse is hosted at matrix.example.org, a static web server or reverse proxy on example.org is often the more suitable place to serve the delegation response.

A common mix-up is treating /.well-known/matrix/client and /.well-known/matrix/server as interchangeable. The server file helps other homeservers discover incoming federation. The client file advertises a client-facing homeserver URL and is optional for federation. Set it up separately only if you want compatible clients to discover the client URL from users’ Matrix IDs.

Step 6: Open the required firewall paths

For direct incoming federation, allow inbound TCP 8448 to the TLS listener or proxy. For the delegated example, allow inbound TCP 443 to the proxy. Client connections also normally use HTTPS on 443. If outbound network access is restricted, permit Synapse to connect to remote homeservers over TCP 443 and 8448. Do not open the Synapse backend port 8008 to the public internet when the reverse proxy is intended to be the public entry point.

If the server is behind a cloud firewall, router, container network, and host firewall, check each layer. A successful local request to port 8008 proves only that Synapse responds locally; it does not prove a remote Matrix server can resolve your domain, validate TLS, or reach the public listener.

Step 7: Restart safely and verify the public endpoints

Validate the YAML before restarting, using the validation command supported by your installation method. Then restart the Synapse service or deployment and inspect its logs for configuration or listener errors. From a machine outside your private network, request the discovery file and the federation version endpoint:

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

For the first command, expect an HTTPS response with a JSON body containing the correct m.server. For the second, expect a successful HTTPS response from Synapse rather than a proxy error, certificate warning, or connection timeout. The exact response body can vary by Synapse version.

Next, enter your Matrix server_name (for example, example.org, not necessarily the proxy hostname) in the Matrix Federation Tester. Fix any reported DNS, delegation, certificate, or endpoint errors and run the test again. Finally, invite a user on another homeserver to a test room or join a room hosted elsewhere. A successful tester result is a useful public connectivity check, but it does not guarantee that every remote server, room policy, firewall, or client configuration will behave identically.

Misconceptions that lead to broken or unexpected setups

• “I must always expose port 8448.” No. The default is 8448, but server delegation can direct incoming federation to 443. Open the port your published discovery route actually uses.
• “The client well-known file enables federation.” It does not. Federation discovery uses the server well-known endpoint or supported DNS fallback; the client endpoint serves a different purpose.
• “Federation makes every local room public.” No. Federation enables server communication. Room visibility and membership still govern participation; invite a remote account to a test room to confirm the use case you need.
• “A green local health check proves federation.” No. Local checks do not test public DNS, external TLS validation, NAT, cloud firewall rules, or proxy routing. Test from outside and use the federation tester.

The maintained Synapse documentation recommends a reverse proxy for TLS termination and explains the separate client and federation ports. See the official guides for reverse-proxy configuration, incoming federation delegation, Synapse configuration options, and firewall and security guidance. For server discovery rules, consult the Matrix Server-Server API specification. Examples here assume standard Synapse behind an HTTPS reverse proxy; container networking, managed deployments, and customized listener layouts may need different values.