From cbf382c806c2059715512c3a7548b542d27b76ac Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 9 Nov 2024 21:15:00 +0900 Subject: [PATCH 1/5] Update docs/configuring-playbook-base-domain-serving.md: add an anchor link to docs/configuring-dns.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-base-domain-serving.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-base-domain-serving.md b/docs/configuring-playbook-base-domain-serving.md index 3f883b744..99dd248d5 100644 --- a/docs/configuring-playbook-base-domain-serving.md +++ b/docs/configuring-playbook-base-domain-serving.md @@ -12,7 +12,7 @@ Usually, there are 2 options: This documentation page tells you how to do the latter. With some easy changes, we make it possible to serve the base domain from the Matrix server via the integrated webserver. -Just **adjust your DNS records**, so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.example.com/vars.yml` file: +Just [**adjust your DNS records**](configuring-dns.md), so that your base domain is pointed to the Matrix server's IP address (using a DNS `A` record) **and then add the following configuration** to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_static_files_container_labels_base_domain_enabled: true From 64fcf85246f706ee5f4b7d58c671b4effac06f54 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 15 Nov 2024 01:28:09 +0900 Subject: [PATCH 2/5] Update documentation related to server delegation Summary: - Add explanation about server delegation and DNS setting for it to docs/configuring-dns.md; "delegation" is a technical term and it is worth being explained simply - Edit explanation about delegation to docs/configuring-playbook-base-domain-serving.md - Use common expressions - Simplify explanation about delegation on docs/configuring-well-known.md and move explanation about the alternative which avoids involving the base domain from that page to its upper documentation, which is docs/howto-server-delegation.md Signed-off-by: Suguru Hirahara --- docs/configuring-dns.md | 18 ++++++++++++------ ...onfiguring-playbook-base-domain-serving.md | 11 +++++++++-- docs/configuring-well-known.md | 17 ++++------------- docs/howto-server-delegation.md | 19 +++++++++++-------- 4 files changed, 36 insertions(+), 29 deletions(-) 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 From 998cc6cba0c1a2a943b24012a187f34b1f38fbe5 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 16 Nov 2024 11:23:10 +0900 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Slavi Pantaleev --- docs/configuring-dns.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 340697a10..a5b20ff3c 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -8,16 +8,16 @@ To set up Matrix on your domain, you'd need to do some DNS configuration. In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user identifier like `@:example.com`. -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". +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 also known as "delegation". As we discuss in [Server Delegation](howto-server-delegation.md), server delegation 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. +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file, instead of using DNS SRV records. -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. +If you choose the recommended method, you do not need to configure DNS SRV records to enable server delegation. We'll revisit this topic in [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) From 74c1ba998a49344d5b45cbeda985f1f4001d23b4 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 16 Nov 2024 11:51:00 +0900 Subject: [PATCH 4/5] Update docs/configuring-dns.md: iterate Signed-off-by: Suguru Hirahara --- docs/configuring-dns.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index a5b20ff3c..283f6fd86 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -4,7 +4,7 @@ To set up Matrix on your domain, you'd need to do some DNS configuration. -## DNS settings for server delegation +## DNS setting for server delegation (optional) In the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), we recommend to use a short user identifier like `@:example.com`. @@ -15,9 +15,9 @@ As we discuss in [Server Delegation](howto-server-delegation.md), server delegat - 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, instead of using DNS SRV records. +For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file, instead of using a DNS SRV record. -If you choose the recommended method, you do not need to configure DNS SRV records to enable server delegation. We'll revisit this topic in [finalizing the installation](installing.md#finalize-the-installation), after installing and starting Matrix services. +If you choose the recommended method, you do not need to configure the DNS record to enable server delegation. You will need to add a necessary configuration later, when you [finalize 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) From 6e66f8aaa21b5cfd5c16c6dcf302319b143ba0c3 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 16 Nov 2024 02:28:51 +0900 Subject: [PATCH 5/5] Fix an anchor link to howto-srv-server-delegation.md Signed-off-by: Suguru Hirahara --- docs/howto-server-delegation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index 0d307b14c..2bbe1a091 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -50,7 +50,7 @@ To use DNS SRV record validation, you need to: - ensure that you are serving the Matrix Federation API (tcp/8448) with a certificate for `example.com` (not `matrix.example.com`!). Getting this certificate to the `matrix.example.com` server may be complicated. The playbook's automatic SSL obtaining/renewal flow will likely not work and you'll need to copy certificates around manually. See below. -For more details on [how to configure the playbook to work with SRV delegation](howto-srv-server-delegation.md) +For more details on how to configure the playbook to work with SRV delegation, take a look at this documentation: [Server Delegation via a DNS SRV record (advanced)](howto-srv-server-delegation.md) ### Obtaining certificates