Update docs/configuring-well-known.md and docs/installing.md #3767
Conversation
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 <[email protected]>
…" as a type of well-known service discovery Signed-off-by: Suguru Hirahara <[email protected]>
…t 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 <[email protected]>
…well-known service discovery mechanism Signed-off-by: Suguru Hirahara <[email protected]>
…fication, to which MSC 1929 was implemented MSC 1929 has no longer been for an early adopter. Signed-off-by: Suguru Hirahara <[email protected]>
Signed-off-by: Suguru Hirahara <[email protected]>
docs/configuring-well-known.md
Outdated
|
|
||
| - (not that 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. Learn more in [Introduction to Client Server Discovery](#introduction-to-client-server-discovery) | ||
| - (important) **Federation Server discovery** (`/.well-known/matrix/server`) -- assists other servers in the Matrix network with finding your server. **This is necessary for federation to work.** Without a proper configuration, your server will effectively not be part of the Matrix network. |
There was a problem hiding this comment.
**This is necessary for federation to work.** was based on this line on docs/installing.md, but I started doubting it is correct, as serving the base domain is in fact optional and therefore it should be fine to run matrix.example.com without delegation/redirection if you will.
There is a FAQ entry about it ("How do I install on matrix.example.com without involving the base domain?"), but it seems to me a little bit ambiguous.
I would like to be corrected if I take it incorrectly (I think it is pretty likely…), but as far as I could understand, setting up DNS SRV record or a /.well-known/matrix/server file for Federation Server discovery is required for federation to work, only if base domain is served in order to set up an ID like @user:example.com.
So, if matrix.example.com is used by default AND it is indeed fine for user ID to be @user:matrix.example.com, then setting up Server Delegation is not required, and therefore nothing needs to be done for Federation Server discovery, right?
There was a problem hiding this comment.
The default and reasonable setup is to have short identifiers (e.g. @user:example.com). This is achieved by using matrix_domain: example.com in the vars.yml file.
By following the sample vars.yml (examples/vars.yml), you'll get a setup like this.
Most people do not actually target the example.com server though. They usually run a website there, etc., and wish to install Matrix on matrix.example.com.
The playbook defaults ask you for the base domain (in the matrix_domain variable), but assume that installation is done against the matrix.{{ matrix_domain }} server.
If you're following these defaults, you will end up with a Matrix homeserver which:
- has a
server_nameSynapse configuration setting that matchesmatrix_domain(that isexample.com) - is exposing its APIs at
matrix.example.com
This is OK and usable at least locally, but for federation to work, you need to do the delegation step (/.well-known/matrix/server).
/.well-known/matrix/client is not so important. Your server is correctly configured and will federate even if you only have the /.well-known/matrix/server file in place. The client file is just (a highly recommended) assistance file that helps clients find your homeserver. It lets:
- users type
@user:example.comin the "Username" field - .. which will make the client application hit
https://example.com/.well-known/matrix/clientand see that this server's full homeserver URL is actuallyhttps://matrix.example.com - .. so the client will configure the homeserver URL correctly
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).
If you use Element Web as configured by the playbook, the homeserver URLs are set/hardcoded correctly, so you won't be inconvenienced by this, but with any other client you will need to do manual work adjusting the homeserver URL value.
So while the lack of /.well-known/matrix/client file can potentially be a serious inconvenience, it's not a critical blocker to having your server work (it will federate) and to having clients connect to it (they can, but manual work may be involved).
This is the reason that the /.well-known/matrix/client file was originally labelled with (not that important). Perhaps this label makes it sound too unimportant though. Perhaps your new label ((less important)) is somewhat better in making the client file sound "a bit more important" than before.
To get back to the topic of federation delegation (the /.well-known/matrix/server file)..
People can also host their server directly on matrix.example.com and have uglier (long) identifiers like @user:matrix.example.com. They can then skip the whole "federation delegation thing" and the base domain will be optional.
However, this kind of set up is non-default. It's covered by these FAQ questions:
- Why install my server at matrix.example.com and not at the base domain?
- How do I install on matrix.example.com without involving the base domain?
For this kind of setup, various variables need to be introduced to vars.yml (compared to the sample configuration we recommend to people).
So.. in the general case (following the sample vars.yml config and getting a nicely configured server with short identifiers), setting up delegation on the base domain is required.
There was a problem hiding this comment.
Below, I'll try to answer your questions more directly/succinctly.
I would like to be corrected if I take it incorrectly (I think it is pretty likely…), but as far as I could understand, setting up DNS SRV record or a
/.well-known/matrix/serverfile for Federation Server discovery is required for federation to work, only if base domain is served in order to set up an ID like@user:example.com.
True. Delegation is only required for getting short identifiers (@user:example.com), while you're setting up a server not on example.com, but on another hostname (like matrix.example.com).
That said, the default playbook setup (as recommended by the sample vars.yml file in examples/vars.yml) is exactly like that:
- you only configure the base domain in
matrix_domain - all other domains (e.g.
matrix.example.com) are calculated from that base domain value inmatrix_domain - the playbook installs against the server and assumes its hostname is indeed
matrix.example.com - the playbook configures the (Synapse) homeserver installed to presents itself as
example.com(server_name: example.comin the Synapse configuration) - due to this mismatch between what Synapse presents itself as (
example.com) and what the actual hostname is (matrix.example.com), server delegation (/.well-known/matrix/serversetup on the base domain) is necessary for this default configuration
So, if matrix.example.com is used by default AND it is indeed fine for user ID to be @user:matrix.example.com, then setting up Server Delegation is not required, and therefore nothing needs to be done for Federation Server discovery, right?
For "nothing needs to be done for Federation Server discovery", one needs a more complicated (non-default) setup as described in the FAQ entries:
- Why install my server at matrix.example.com and not at the base domain?
- How do I install on matrix.example.com without involving the base domain?
By following the standard guide (as recommended by the sample vars.yml file in examples/vars.yml), federation setup work (/.well-known/matrix/server setup on the base domain) is necessary. Your server will work locally even without this setup, but federation requires it.
There was a problem hiding this comment.
Thanks for the detailed replies! I will reflect those points to the PR 😄
Co-authored-by: Slavi Pantaleev <[email protected]>
Co-authored-by: Slavi Pantaleev <[email protected]>
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 <[email protected]>
…g-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 <[email protected]>
|
This should be fine… |
Signed-off-by: Suguru Hirahara <[email protected]>
luixxiul
changed the title
No description provided.