Skip to main content

Delegation

Own instance?

Don't have your own Matrix instance yet? Feel free to book [your hosting with us].(https://ossrox.org/store/matrix)!

In Matrix, finding a home server in the Federation Protocol or Matrix Federation is based by default on the domain in server_name (e.g., your-domain.com) and expects accessibility via HTTPS. If this is not possible, the network traffic of the federation must be delegated so that other servers know where to send requests.

.well-known delegation​

The most recommended method of delegation is to use a .well-known file. This involves providing a special file at, for example, https://your-domain.de/.well-known/matrix/server, which is formatted as JSON and announces the destination of the federation traffic. (the directory is /.well-known/matrix/, the file name is server)

{
	"m.server": "matrix.your-domain.de:443"
}

Here, m.server points to the actual Matrix server and, optionally, to another port that accepts the requests.

For easier client configuration, e.g. Element, the following file can optionally be created under the URL https://your-domain.de/.well-known/matrix/client (the directory is the same as above, the file name is client):

{
    "m.homeserver": {
        "base_url": "https://matrix.your-domain.de/",
        "server_name": "your-domain.de"
    }
}

Similar to an email client, the client file reveals the path to the Matrix server to Matrix-compatible apps as soon as the main domain is entered.

Setup options​

  • External web server / reverse proxy: Your own web server or proxy configuration (e.g., nginx, Apache, HAProxy) delivers the .well-known file.
  • Synapse's own provisioning: If the domain name points directly to the Synapse server and the federation runs on port 443, the Matrix server (Synapse) can also provide this file itself; we will configure it accordingly.

SRV DNS record delegation​

Not recommended

Delegation via SRV DNS record is an exceptional case and significantly limits central configuration options for Matrix clients. We recommend using .well-known delegation.

As an alternative to the .well-known file, federation traffic can also be redirected via an SRV DNS record. However, this is less common and not recommended because:

  • TLS certificates are more difficult to configure correctly,
  • there are no advantages over .well-known delegation,
  • global client settings (e.g., default Jitsi server) still have to be managed via .well-known endpoints despite SRV records.

If a .well-known delegation is not possible for your order, for example because your web host does not support it, we will be happy to assist you.

For automatic certificate renewal, it is necessary to use DNS-01 challenges for SRV DNS delegation. Therefore, a DNS provider with API access supported by ACME is a mandatory requirement for this.