finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Edit documentation related to server delegation (#3773)

Browse Source 
* Update docs/configuring-playbook-base-domain-serving.md: add an anchor link to docs/configuring-dns.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* 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 <acioustick@noreply.codeberg.org>

* Apply suggestions from code review

Co-authored-by: Slavi Pantaleev <slavi@devture.com>

* Update docs/configuring-dns.md: iterate

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Fix an anchor link to howto-srv-server-delegation.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Minor rewording

* Minor rewording

* Minor rewording

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Suguru Hirahara
2024-11-16 16:19:17 +09:00
committed by GitHub
parent 774f3de863
commit f19cbe6dd4
4 changed files with 39 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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