mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-10-31 07:17:57 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation related to server delegation

Browse Source 
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 <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
2024-11-15 01:28:09 +09:00
parent cbf382c806
commit 64fcf85246
4 changed files with 36 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/configuring-dns.md
View File

@@ -4,16 +4,22 @@
To set up Matrix on your domain, you'd need to do some DNS configuration.
To use an identifier like `@<username>: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 `@<username>: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

11
docs/configuring-playbook-base-domain-serving.md
View File

@@ -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:

17
docs/configuring-well-known.md
View File

@@ -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

19
docs/howto-server-delegation.md
View File

@@ -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