diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 203590c97..340697a10 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -4,16 +4,22 @@ To set up Matrix on your domain, you'd need to do some DNS configuration. -To use an identifier like `@:example.com`, you don't actually need to install anything on the actual `example.com` server. +## DNS settings for server delegation -You do, however, need to instruct the Matrix network that Matrix services for `example.com` are delegated over to `matrix.example.com`. +In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user identifier like `@:example.com`. -As we discuss in [Server Delegation](howto-server-delegation.md), there are 2 different ways to set up such delegation: +To use such an identifier, you don't need to install anything on the actual `example.com` server. Instead, you need to instruct the Matrix network that Matrix services for `example.com` are redirected over to `matrix.example.com`. This redirection is called as "delegation". -- either by serving a `https://example.com/.well-known/matrix/server` file (from the base domain!) -- or by using a `_matrix._tcp` DNS SRV record (don't confuse this with the `_matrix-identity._tcp` SRV record described below) +As we discuss in [Server Delegation](howto-server-delegation.md), server delegation can be configured in either way: -This playbook mostly discusses the well-known file method, because it's easier to manage with regard to certificates. If you decide to go with the alternative method ([Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced)), please be aware that the general flow that this playbook guides you through may not match what you need to do. +- Setting up a `/.well-known/matrix/server` file on the base domain (`example.com`) +- Setting up a `_matrix._tcp` DNS SRV record + +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. + +If you choose this method, you do not need to set anything to enable server delegation for now. We'll revisit this topic on [finalizing the installation](installing.md#finalize-the-installation), after installing and starting Matrix services. + +On the other hand, if you choose the other method (setting the DNS SRV record), you need to configure the additional DNS record. Take a look at this documentation for more information: [Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced) ## DNS settings for services enabled by default diff --git a/docs/configuring-playbook-base-domain-serving.md b/docs/configuring-playbook-base-domain-serving.md index 99dd248d5..d65a3bbc3 100644 --- a/docs/configuring-playbook-base-domain-serving.md +++ b/docs/configuring-playbook-base-domain-serving.md @@ -1,8 +1,15 @@ # Serving the base domain (optional) -This playbook sets up services on your Matrix server (`matrix.example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up [Server Delegation](howto-server-delegation.md). This is normally done by [configuring well-known](configuring-well-known.md) files on the base domain. +By default, this playbook sets up services on your Matrix server (`matrix.example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up server delegation / redirection. -People who don't have a separate server to dedicate to the base domain have trouble arranging this. +As we discuss in [Server Delegation](howto-server-delegation.md), server delegation / redirection can be configured in either way: + +- Setting up a `/.well-known/matrix/server` file on the base domain (`example.com`) +- Setting up a `_matrix._tcp` DNS SRV record + +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. + +However, those who don't have a separate server to dedicate to the base domain have trouble arranging this. Usually, there are 2 options: diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md index 2dc66e8bf..0dab9c6c6 100644 --- a/docs/configuring-well-known.md +++ b/docs/configuring-well-known.md @@ -1,6 +1,6 @@ # Configuring Service Discovery via .well-known -Service discovery is a way for the Matrix network to discover where a Matrix server is. +This documentation page explains how to configure Service discovery via `/.well-known/` files. Service discovery is a way for the Matrix network to discover where a Matrix server is. ## Types of well-known service discovery mechanism @@ -16,20 +16,11 @@ There are 3 types of well-known service discovery mechanism that Matrix makes us All services created by this playbook are meant to be installed on their own server (such as `matrix.example.com`), instead of the base domain (`example.com`). -As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a short Matrix user identifier like `@user:example.com` while hosting services on a subdomain such as `matrix.example.com`, the Matrix network needs to be instructed of such delegation/redirection. +As [per the Server-Server specification](https://matrix.org/docs/spec/server_server/r0.1.0.html#server-discovery), to use a short Matrix user identifier like `@user:example.com` while hosting services on a subdomain such as `matrix.example.com`, the Matrix network needs to be instructed of [server delegation](howto-server-delegation.md) / redirection. -As the playbook recommends in the sample `vars.yml` (`examples/vars.yml`) to use a short user identifier, you would need to configure the delegation so that your server will be federated with other Matrix servers. +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. -Server delegation can be configured by: - -- Setting up a `/.well-known/matrix/server` file on the base domain (`example.com`) -- Setting up a DNS SRV record - -Both methods have their place and will continue to do so. You only need to use just one of these delegation methods. - -For simplicity reasons, our setup advocates for the `/.well-known/matrix/server` method and guides you into using that. If you need to use the other method, you can check this documentation: [Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced) - -**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain - `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ. +If you set up the DNS SRV record for server delegation instead, take a look at this documentation for more information: [Server Delegation via a DNS SRV record (advanced)](howto-server-delegation.md#server-delegation-via-a-dns-srv-record-advanced) ### Client Server Discovery diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index 7b61553d1..0d307b14c 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -1,20 +1,23 @@ # Server Delegation -To have a server on a subdomain (e.g. `matrix.example.com`) handle Matrix federation traffic for the base domain (`example.com`), we need to instruct the Matrix network of such a delegation. +By default, this playbook sets up services on your Matrix server (`matrix.example.com`). To have this server officially be responsible for Matrix services for the base domain (`example.com`), you need to set up server delegation / redirection. -By default, this playbook guides you into setting up [Server Delegation via a well-known file](#server-delegation-via-a-well-known-file). However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation. +Server delegation can be configured in either way: -It is a complicated matter, so unless you are affected by the [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation), we suggest you stay on the simple/default path. +- [Setting up a `/.well-known/matrix/server` file](#server-delegation-via-a-well-known-file) on the base domain (`example.com`) +- [Setting up a `_matrix._tcp` DNS SRV record](#server-delegation-via-a-dns-srv-record-advanced) +Both methods have their place and will continue to do so. You only need to use just one of these delegation methods. + +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file. However, that method may have some downsides that are not to your liking. Hence this guide about alternative ways to set up Server Delegation. + +**Note**: as an alternative, it is possible to install the server such that it uses only the `matrix.example.com` domain (instead of identifying as the shorter base domain - `example.com`). This should be helpful if you are not in control of anything on the base domain (`example.com`). In this case, you would not need to configure server delegation, but you would need to add other configuration. For more information, see [How do I install on matrix.example.com without involving the base domain?](faq.md#how-do-i-install-on-matrix-example-com-without-involving-the-base-domain) on our FAQ. ## Server Delegation via a well-known file -Serving a `/.well-known/matrix/server` file from the base domain is the most straightforward way to set up server delegation, but it suffers from some problems that we list in [Downsides of well-known-based Server Delegation](#downsides-of-well-known-based-server-delegation). - -As we already mention in [Configuring DNS](configuring-dns.md) and [Configuring Service Discovery via .well-known](configuring-well-known.md), this playbook already properly guides you into setting up such delegation by means of a `/.well-known/matrix/server` file served from the base domain (`example.com`). - -If this is okay with you, feel free to not read ahead. +This playbook recommends you to set up server delegation by means of a `/.well-known/matrix/server` file served from the base domain (`example.com`), as this is the most straightforward way to set up the delegation. +To configure server delegation with the well-known file, check this section on [Configuring Service Discovery via .well-known](configuring-well-known.md): [Installing well-known files on the base domain's server](configuring-well-known.md#installing-well-known-files-on-the-base-domain-s-server) ### Downsides of well-known-based Server Delegation