matrix-docker-ansible-deploy/docs/configuring-well-known.md

190 lines
11 KiB
Markdown
Raw Normal View History

# Configuring Service Discovery via .well-known
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.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
## Types of well-known service discovery mechanism
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
There are 3 types of well-known service discovery mechanism that Matrix makes use of:
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
- (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. With the default playbook configuration specified on the sample `vars.yml` ([`examples/vars.yml`](../examples/vars.yml)), this is necessary for federation to work. Without a proper configuration, your server will effectively not be part of the Matrix network.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
- (less important) **Client Server discovery** (`/.well-known/matrix/client`) -- assists programs that you use to connect to your server (e.g. Element Web), so that they can make it more convenient for you by automatically configuring the "Homeserver URL" and "Identity Server URL" addresses.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
- (optional) **Support service discovery** (`/.well-known/matrix/support`) -- returns server admin contact and support page of the domain.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
### Federation Server Discovery
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
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 [server delegation](howto-server-delegation.md) / redirection.
For simplicity reasons, this playbook recommends you to set up server delegation via a `/.well-known/matrix/server` file.
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)
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
### Client Server Discovery
Client Server Service discovery lets various client programs which support it, to receive a full user ID (e.g. `@username:example.com`) and determine where the Matrix server is automatically (e.g. `https://matrix.example.com`).
This lets you (and your users) easily connect to your Matrix server without having to customize connection URLs. When using client programs that support it, you won't need to point them to `https://matrix.example.com` in Custom Server options manually anymore. The connection URL would be discovered automatically from your full username.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
Without /.well-known/matrix/client, the client will make the wrong "homeserver URL" assumption (it will default to using https://example.com, and users will need to notice and adjust it manually (changing it to https://matrix.example.com).
As [per the Client-Server specification](https://matrix.org/docs/spec/client_server/r0.4.0.html#server-discovery) Matrix does Client Server service discovery using a `/.well-known/matrix/client` file hosted on the base domain (e.g. `example.com`).
However, this playbook installs your Matrix server on another domain (e.g. `matrix.example.com`) and not on the base domain (e.g. `example.com`), so it takes a little extra manual effort to set up the file.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
### (Optional) Support Service Discovery
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
[MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929), which was added to [Matrix Specification version v1.10](https://spec.matrix.org/v1.10/client-server-api/#getwell-knownmatrixsupport), specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service. Automated services may also index this information and use it for abuse reports, etc.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
```yaml
# Enable generation of `/.well-known/matrix/support`.
matrix_static_files_file_matrix_support_enabled: true
# Homeserver admin contacts as per MSC 1929 https://github.com/matrix-org/matrix-spec-proposals/pull/1929
matrix_static_files_file_matrix_support_property_m_contacts:
- matrix_id: "@admin1:{{ matrix_domain }}"
email_address: admin@example.com
role: m.role.admin
- matrix_id: "@admin2:{{ matrix_domain }}"
email_address: admin2@example.com
role: m.role.admin
- email_address: security@example.com
role: m.role.security
# Your organization's support page on the base (or another) domain, if any
matrix_static_files_file_matrix_support_property_m_support_page: "https://example.com/support"
```
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
## Installing well-known files on the base domain's server
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
To implement the service discovery mechanisms, your base domain's server (e.g. `example.com`) needs to run an HTTPS-capable webserver.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
### Serving the base domain from the Matrix server via the playbook
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
If you don't have a server for your base domain at all, you can use the Matrix server for this. If you don't need the base domain (e.g. `example.com`) for anything else (hosting a website, etc.), you can point it to the Matrix server's IP address and tell the playbook to configure it.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
**This is the easiest way to set up well-known serving** -- letting the playbook handle the whole base domain for you (including SSL certificates, etc.) and take care to serve the appropriate well-known files automatically.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
If you decide to go this route, you don't need to read ahead in this document. Instead, go to [Serving the base domain](configuring-playbook-base-domain-serving.md) to learn how the playbook can help you set it up.
However, if you need to use the base domain for other things, this method is less suitable than the one explained below.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
### Manually installing well-known files on the base domain's server
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
If you're managing the base domain by yourself somehow, you'll need to set up serving of some `/.well-known/matrix/*` files from it via HTTPS.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
To make things easy for you to set up, this playbook generates and hosts a few well-known files on the Matrix domain's server. The files are generated at the `/matrix/static-files/public/.well-known/matrix/` path on the server and hosted at URLs like `https://matrix.example.com/.well-known/matrix/server` and `https://matrix.example.com/.well-known/matrix/client`, even though this is the wrong place to host them.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
You have two options when it comes to installing the files on the base domain's server:
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
#### (Option 1): **Copying the files manually** to your base domain's server
**Hint**: Option 2 is generally a better way to do this. Make sure to go with it, if possible.
All you need to do is:
- copy `/.well-known/matrix/server` and `/.well-known/matrix/client` from the Matrix server (e.g. `matrix.example.com`) to your base domain's server (`example.com`). You can find these files in the `/matrix/static-files/.well-known/matrix` directory on the Matrix server. They are also accessible on URLs like this: `https://matrix.example.com/.well-known/matrix/server` (same for `client`).
Add "Web" to Element and SchildiChat web application (#3755) * Replace "Element" with "Element Web" - If Element indicates the web application, then it is changed to Element Web. - If it indicates clients branded with Element such as Element desktop, web, mobile clients, then it is changed to Element clients. - If it is combined with location sharing functionality, it is not changed. with other some changes, including: - Change "app.element.io" anchor link to "https://github.com/element-hq/element-web" on README.md, following other documentation files Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Replace "SchildiChat" with "SchildiChat Web" - If SchildiChat indicates the web application, then it is changed to SchildiChat Web. - If it indicates clients branded with SchildiChat such as SchildiChat desktop, web, mobile clients, then it is changed to SchildiChat clients. - If it is combined with location sharing functionality, it is not changed. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Rename configuring-playbook-client-schildichat.md to configuring-playbook-client-schildichat-web.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Rename configuring-playbook-client-element.md to configuring-playbook-client-element-web.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-11-07 14:31:26 +00:00
- set up the server at your base domain (e.g. `example.com`) so that it adds an extra HTTP header when serving the `/.well-known/matrix/client` file. [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the `Access-Control-Allow-Origin` header should be set with a value of `*`. If you don't do this step, web-based Matrix clients (like Element Web) may fail to work. Setting up headers for the `/.well-known/matrix/server` file is not necessary, as this file is only consumed by non-browsers, which don't care about CORS.
This is relatively easy to do and possibly your only choice if you can only host static files from the base domain's server. It is, however, **a little fragile**, as future updates performed by this playbook may regenerate the well-known files and you may need to notice that and copy them over again.
Update docs/configuring-well-known.md and docs/installing.md (#3767) * Update docs/configuring-well-known.md: remove redundant information For example, anchor links to the headers are distractive as these headers are displayed by scrolling a bit. Also: edit section headers Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add "Support service discovery" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: recategorize the sections about installing well-known files on the base domain's server The commit merges the content of the option 2 with the section above, as both explain how to serve the base domain via the playbook and claim it is the easy way of installing well-known files, and therefore the content is repetitive. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: create a section for types of well-known service discovery mechanism Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: add a link to the Matrix Specification, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: iterate Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-base-domain-serving.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/configuring-well-known.md Co-authored-by: Slavi Pantaleev <slavi@devture.com> * Update docs/installing.md: iterate Summary: - Try to reflect review comments - Declare that the shorter user identifier is recommended - Add a note about installing the server matrix.example.com directly, with the link to the FAQ entry Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/installing.md: replace the anchor link to docs/configuring-well-known.md with one to docs/howto-server-delegation.md Service Discovery via .well-known files is one of the two ways for server delegation, and it is possible to set up server delegation via a DNS SRV record instead (though it is more advanced and complicated), so it should be more proper to use the words "delegation/redirection" than "service discovery". Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-well-known.md: fix a typo Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- 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>
2024-11-15 06:34:21 +00:00
#### (Option 2): **Setting up reverse-proxying** of the well-known files from the base domain's server to the Matrix server
This option is less fragile and generally better.
On the base domain's server (e.g. `example.com`), you can set up reverse-proxying, so that any access for the `/.well-known/matrix` location prefix is forwarded to the Matrix domain's server (e.g. `matrix.example.com`).
With this method, you **don't need** to add special HTTP headers for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) reasons (like `Access-Control-Allow-Origin`), because your Matrix server (where requests ultimately go) will be configured by this playbook correctly.
**For nginx**, it would be something like this:
```nginx
# This is your HTTPS-enabled server for example.com.
server {
server_name example.com;
location /.well-known/matrix {
proxy_pass https://matrix.example.com/.well-known/matrix;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_ssl_server_name on;
}
# other configuration
}
```
2022-05-13 10:44:16 +00:00
**For Apache2**, it would be something like this:
```apache
<VirtualHost *:443>
ServerName example.com
SSLProxyEngine on
ProxyPass /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon
ProxyPassReverse /.well-known/matrix https://matrix.example.com/.well-known/matrix nocanon
# other configuration
</VirtualHost>
```
**For Caddy 2**, it would be something like this:
2018-10-19 14:22:27 +00:00
```caddy
example.com {
reverse_proxy /.well-known/matrix/* https://matrix.example.com {
header_up Host {upstream_hostport}
}
}
```
2019-09-23 15:44:13 +00:00
**For HAProxy**, it would be something like this:
```haproxy
frontend www-https
# Select a Challenge for Matrix federation redirect
acl matrix-acl path_beg /.well-known/matrix/
# Use the challenge backend if the challenge is set
use_backend matrix-backend if matrix-acl
backend matrix-backend
# Redirects the .well-known Matrix to the Matrix server for federation.
2019-09-23 15:44:13 +00:00
http-request set-header Host matrix.example.com
server matrix matrix.example.com:80
# Map url path as ProxyPass does
reqirep ^(GET|POST|HEAD)\ /.well-known/matrix/(.*) \1\ /\2
# Rewrite redirects as ProxyPassReverse does
acl response-is-redirect res.hdr(Location) -m found
2020-06-07 17:56:12 +00:00
rsprep ^Location:\ (http|https)://matrix.example.com\/(.*) Location:\ \1://matrix.example.com/.well-known/matrix/\2 if response-is-redirect
2019-09-23 15:44:13 +00:00
```
2024-01-09 13:34:00 +00:00
**For Netlify**, configure a [redirect](https://docs.netlify.com/routing/redirects/) using a `_redirects` file in the [publish directory](https://docs.netlify.com/configure-builds/overview/#definitions) with contents like this:
2021-02-19 01:37:01 +00:00
```
/.well-known/matrix/* https://matrix.example.com/.well-known/matrix/:splat 200!
2021-02-19 01:37:01 +00:00
```
**For AWS CloudFront**
1. Add a custom origin with matrix.example.com to your distribution
2. Add two behaviors, one for `.well-known/matrix/client` and one for `.well-known/matrix/server` and point them to your new origin.
Make sure to:
- **replace `example.com`** in the server configuration with your actual domain name
- and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be
## Confirming it works
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at these URLs:
- `https://example.com/.well-known/matrix/server`
- `https://example.com/.well-known/matrix/client`
- `https://example.com/.well-known/matrix/support`
2018-10-21 09:58:25 +00:00
2018-10-29 20:38:58 +00:00
You can also check if everything is configured correctly, by [checking if services work](maintenance-checking-services.md).