Skip to main content

Delegation

Your own instance?

Don't have your own Matrix instance yet? You'll find the right hosting with us.

In Matrix federation, finding a homeserver is based by default on the domain in server_name (e.g., your-domain.com) and requires it to be reachable via HTTPS. If this is not possible, federation traffic must be delegated so that other servers know where to send requests.

.well-known delegation​

The recommended method of delegation is a .well-known file. This involves providing a special file at, for example, https://your-domain.com/.well-known/matrix/server, which announces the destination of the federation traffic in JSON format. The directory is /.well-known/matrix/, the file name is server.

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

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

For easier configuration of clients such as Element, the following file can optionally be created at the URL https://your-domain.com/.well-known/matrix/client (the directory is the same as above, the file name is client):

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

Similar to an email client, the client file tells Matrix-compatible apps the path to the Matrix server 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.
  • Provided by Synapse itself: If the domain name points directly to the Synapse server and 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,
  • it offers 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 .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. A DNS provider with API access that appears in the list of supported ACME DNS providers is therefore mandatory.