So, you have decided to install your own matrix server and are reading INSTALL.md - the official matrix-synapse install manual.

The first heading you will come across invites you to choose your matrix server name. The section notes you have to choose your server name before proceeding, and by the way, your server name cannot be changed later - so you better choose wisely.

Indeed, the first step of the installation process requires you to provide your server name as an initial argument.

python -m synapse.app.homeserver \
    --server-name my.domain.name \
    --config-path homeserver.yaml \
    --generate-config \
    --report-stats=[yes|no]

There's no way to proceed without settling on the final, permanent unchangeable server name which will be stuck with you for the lifetime of you server.

You go back to read the docs, and get a couple of vague sentences covering some superficial details and a link off to 'advanced' configuration.

If, like me, you are new to matrix then you might be left scratching your head, or worse - stuck in a spot of analysis paralysis trying to understand the implications of various options for a server name.

What's in a Server Name Anyway?

At base, your server name uniquely identifies your matrix server and is the fully qualified domain name (FQDN) at which your matrix server is reachable.*

  • Federated matrix servers communicate with one another by making http(s) requests on port 8448 to the domain matching your server_name. E.g https://<server_name>:8448.
  • Users log in to your Matrix home server by specifying the url of your home server. E.g. https://<server_name>. This is the Homeserver URL.
  • Your server name acts as a namespace for users and rooms E.g. rooms and users will be #room:<server_name> and @user:<server_name> respectively.

*See delegation below for the one exception to this rule.

A Basic Example

If your server_name is example.com then

  • Federated Matrix servers will try to connect to https://example.com:8448 to sync data with your server.
  • Users on your server will be namespaced as @user:example.com and rooms will be namespaced to #room:example.com.
  • When signing up or signing in to your matrix server via riot web, desktop or mobile, your users will need to specify https://example.com as their Homeserver URL.

I will provide these values in a tabulated format as we go for quick reference and simple comparison.

Property Value
Server Name example.com
Usernames @user:example.com
Rooms #room:example.com
Homeserver URL (Users) https://example.com
Homeserver URL (Servers) https://example.com:8448

Limitations

If you were hosting your website at https://example.com then you would not also be able to host your Matrix server at example.com on port 443. If you want to host your matrix server on the same domain you could either expose your matrix server on an different port and require users to provide the port number in the url (yuck), or better, host Matrix on a subdomain.

Hosting Matrix on a Subdomain

If for example, you decide to host your matrix server at https://matrix.example.com then, correspondingly, you would set your server_name to matrix.example.com.

Again, this is because Federated home servers wishing to communicate with your homeserver will used your server_name to find your Homeserver URL.

Property Value
Server Name matrix.example.com
Usernames @user:matrix.example.com
Rooms #room:matrix.example.com
Homeserver URL (Users) https://matrix.example.com
Homeserver URL (Servers) https://matrix.example.com:8448

Limitations

The down side of this is that the namespace of users and rooms on your Matrix home server is a little bit longer now that it includes the subdomain.

On the bright side the namespace will rarely be visible and are only displayed if there is a need to disambiguate public rooms on different servers which have the same name (for example, #devops:mozilla.org and #devops:amazon.com) and users in the same room with the same first part of their username (for example, @alice:example.com and @alice:matrix.org).

If your matrix server is private and not federated or there is no clash requiring disambiguation, then the rooms and users will simply appear as #devops and @alice respectively.

There is one more option though.

Best of both worlds with 'Delegation'

Matrix does allow you to host your server at a domain or subdomain other than your server_name through a mechanism called Delegation.

For example, you could use example.com for your server_name  but host your Martix home server at https://matrix.example.com - thus avoiding any potential clashes with a website hosted at https://example.com while sill benefiting from a shorter, cleaner server_name.

Property Value
Server Name example.com
Usernames @user:example.com
Rooms #room:example.com
Homeserver URL (User) https://matrix.example.com
Homeserver URL (Server) https://matrix.example.com:8448

The way this works is by setting up a redirect of sorts from the server_name (E.g. example.com) to the actual address where matrix is hosted (e.g https://matrix.example.com).

Federated Matrix servers which come looking for your matrix server at https://example.com and will follow the delegation to the actual address. This does mean that you need to have control over the domain/subdomains you use both for server_name and where the Matrix server is actually hosted.

For implementation details see the docs.

Limitations

Delegation isn't without it's own drawbacks though. As shown in the table above, the URL that users need to use when logging in to your homeserver is the full URL of the Matrix server behind the redirect, not the server name.

You should be mindful of this fact when selecting the subdomain or domain that the matrix server is hosted at. It should be memorable and clearly identifiable as relevant or affiliated with the server_name  -  or you/your organization's identity. A subdomain of server_name is probably a good option in most cases.

You may wish to provide documentation to your users to ensure they know the correct value to use for the Homeserver url in this case.

Mitigation

You may choose to host your own instance of riot-web. Among aesthetic customization such as being able to brand and theme a self hosted instance of riot-web it can also be configured to use the correct Homeserver URL by default - thus saving your users the trouble of remembering and typing in the correct Homeserver URL in manually.

This configuration, however does not extend to riot desktop, riot mobile or riot.im/app. Users of the desktop and mobile apps will still need to enter the correct Homeserver URL.

Self Hosting Riot

If you plan on self hosting a riot-web client for your users, there are some extra considerations.

You may be tempted to host riot at the same domain or at a subdomain of the matrix server but, heed this Important Security Note - running riot and matrix from the same domain or subdomains of one another opens up vulnerability to XSS attacks.

Not OK

Service Domain
Matrix example.com
Riot riot.example.com
Service Domain
Matrix matrix.example.com
Riot example.com

It is, however, safe to host both matrix and riot on unique subdomains of the same domain.

OK

Service Domain
Riot riot.example.com
Matrix matrix.example.com

As such, you either need to:

  • Use matrix.example.com as the server_name at the time of installation as per the 'Hosting Matrix on a Subdomain' section above. Or;
  • Configure Delegation from example.com to matrix.example.com as per the 'Best of both worlds with 'Delegation'' section above.

Browser Redirection

When users visit your matrix server in the browser you want them to be presented with the slick riot-web interface.

If users try to visit the matrix Homeserver url in the browser we can simply redirect them to the to the riot-web client with a HTTP 302 redirect as follows

location / {
    return 302 https://riot.example.com$request_uri;
}

This works because the matrix API routes are all nested under the /_matrix context path E.g https://matrix.example.com/_matrix/. As such it's safe to redirect from https://matrix.example.com at the / location, to https://riot.example.com/.

A Model Scenario

Imagine you are implementing a matrix server for a start up company. They want to host a public server where their engineers/sales reps and current and potential clients can all hang out, and collaborate.

They already have their flash startup website hosted at https://example.com.

They would prefer to keep everything under the example.com domain or a subdomain for brand identity.

Without delegation

Property Value
Server Name matrix.example.com
Usernames @user:matrix.example.com
Rooms #room:matrix.example.com
Homeserver URL (User) https://matrix.example.com
Homeserver URL (Server) https://matrix.example.com:8448
riot-web https://riot.example.com

With delegation

Property Value
Server Name example.com
Usernames @user:example.com
Rooms #room:example.com
Homeserver URL (User) https://matrix.example.com
Homeserver URL (Server) https://matrix.example.com:8448
riot-web https://riot.example.com

Start with a test server and domain

With Matrix it's particularly important not to pollute the namespace you might eventually use for production. This is because once your matrix server interacts with other federated servers, some of your state is replicated those servers.

If you mess up or decide to reset your test server at any point you can blow away all your database but servers which replicated your state will now be inconsistent and things can get weird - fast. In the worst case scenario, your matrix server may just cease to work with other matrix servers that have previously replicated your data.

It's safer to do your learning and experimentation in a completely separate namespace until you are ready to build your production service. This approach gives you total freedom to try and fail without any risk or impact on your future server.

If you are setting up a matrix server for evaluation, learning, as a demo or proof of concept, start by setting up a test server with a test server_name, hosted on a domain name unique from anything you might use for your production setup.

Personally, I registered a cheap .xyz domain for $1 USD from Namecheap to use as a namespace for learning and testing purposes.

"There are only two hard things in Computer Science: cache invalidation and naming things"

-- Phil Karlton