dendrite/docs/installation/2_domainname.md

title	parent	nav_order	permalink
Setting up the domain	Installation	2	/installation/domainname

Setting up the domain

Every Matrix server deployment requires a server name which uniquely identifies it. For example, if you are using the server name example.com, then your users will have usernames that take the format @user:example.com.

For federation to work, the server name must be resolvable by other homeservers on the internet — that is, the domain must be registered and properly configured with the relevant DNS records.

Matrix servers usually discover each other when federating using the following methods:

1. If a well-known delegation exists on example.com, use the domain and port from the well-known file to connect to the remote homeserver;
2. If a DNS SRV delegation exists on example.com, use the IP address and port from the DNS SRV record to connect to the remote homeserver;
3. If neither well-known or DNS SRV delegation are configured, attempt to connect to the remote homeserver by connecting to example.com port TCP/8448 using HTTPS.

The exact details of how server name resolution works can be found in the spec.

TLS certificates

Matrix federation requires that valid TLS certificates are present on the domain. You must obtain certificates from a publicly accepted Certificate Authority (CA). LetsEncrypt is an example of such a CA that can be used. Self-signed certificates are not suitable for federation and will typically not be accepted by other homeservers.

A common practice to help ease the management of certificates is to install a reverse proxy in front of Dendrite which manages the TLS certificates and HTTPS proxying itself. Software such as NGINX and HAProxy can be used for the task. Although the finer details of configuring these are not described here, you must reverse proxy all /_matrix paths to your Dendrite server.

It is possible for the reverse proxy to listen on the standard HTTPS port TCP/443 so long as your domain delegation is configured to point to port TCP/443.

Delegation

Delegation allows you to specify the server name and port that your Dendrite installation is reachable at, or to host the Dendrite server at a different server name to the domain that is being delegated.

For example, if your Dendrite installation is actually reachable at matrix.example.com port 8448, you will be able to delegate from example.com to matrix.example.com so that your users will have @user:example.com user names instead of @user:matrix.example.com usernames.

Delegation can be performed in one of two ways:

• Well-known delegation (preferred): A well-known text file is served over HTTPS on the domain name that you want to use, pointing to your server on matrix.example.com port 8448;
• DNS SRV delegation (not recommended): See the SRV delegation section below for details.

If you are using a reverse proxy to forward /_matrix to Dendrite, your well-known or delegation must refer to the hostname and port that the reverse proxy is listening on instead.

Well-known delegation

Using well-known delegation requires that you are running a web server at example.com which is listening on the standard HTTPS port TCP/443.

Assuming that your Dendrite installation is listening for HTTPS connections at matrix.example.com on port 8448, the delegation file must be served at https://example.com/.well-known/matrix/server and contain the following JSON document:

{
    "m.server": "matrix.example.com:8448"
}

You can also serve .well-known with Dendrite itself by setting the well_known_server_name config option to the value you want for m.server. This is primarily useful if Dendrite is exposed on example.com:443 and you don't want to set up a separate webserver just for serving the .well-known file.

global:
...
   well_known_server_name: "example.com:443"

DNS SRV delegation

This method is not recommended, as the behavior of SRV records in Matrix is rather unintuitive: SRV records will only change the IP address and port that other servers connect to, they won't affect the domain name. In technical terms, the Host header and TLS SNI of federation requests will still be example.com even if the SRV record points at matrix.example.com.

In practice, this means that the server must be configured with valid TLS certificates for example.com, rather than matrix.example.com as one might intuitively expect. If there's a reverse proxy in between, the proxy configuration must be written as if it's example.com, as the proxy will never see the name matrix.example.com in incoming requests.

This behavior also means that if example.com and matrix.example.com point at the same IP address, there is no reason to have a SRV record pointing at matrix.example.com. It can still be used to change the port number, but it won't do anything else.

If you understand how SRV records work and still want to use them, the service name is _matrix and the protocol is _tcp.