Matthias/conduit

Fork 0

Docs: Delegation #956

Open

purplemeteorite wants to merge 3 commits from docs-delegation into next

purplemeteorite commented

2023-08-05 15:16:43 +00:00

(Migrated from gitlab.com)

Changes:

Explained the goal of delegation
Explained how to set it up
Added Nginx and Caddy example configurations
Removed an old and incomplete section about delegation

I agree to release my code and all other changes of this MR under the Apache-2.0 license

Changes: - Explained the goal of delegation - Explained how to set it up - Added Nginx and Caddy example configurations - Removed an old and incomplete section about delegation ----------------------------------------------------------------------------- - [x] I agree to release my code and all other changes of this MR under the Apache-2.0 license

paulvt commented

2023-08-05 15:22:37 +00:00

(Migrated from gitlab.com)

I would not use the wording "server name" in this paragraph, because that is what Conduit uses to refer to the name of the server it considers its own (see the config example).

So, in away it is actually the other way around: To use the domain as the server name instead of the hostname Conduit is reachable with (for example conduit.example.com), do delegation as described below etc. etc.

I would not use the wording "server name" in this paragraph, because that is what Conduit uses to refer to the name of the server it considers its own (see the [config](https://gitlab.com/famedly/conduit/-/blob/next/conduit-example.toml?ref_type=heads#L23) example). So, in away it is actually the other way around: To use the domain as the server name instead of the hostname Conduit is reachable with (for example `conduit.example.com`), do delegation as described below etc. etc.

purplemeteorite commented

2023-08-05 15:41:15 +00:00

(Migrated from gitlab.com)

As per your config example, "server name" would equal example.com in this context. We would use delegation to have Conduit listen on somethingotherthanexample.com. Therefore, the sentence seems right to me.

Could you please read it one more time and confirm that you still see a problem?

As per your config example, "server name" would equal `example.com` in this context. We would use delegation to have Conduit listen on `somethingotherthanexample.com`. Therefore, the sentence seems right to me. Could you please read it one more time and confirm that you still see a problem?

paulvt commented

2023-08-05 15:52:23 +00:00

(Migrated from gitlab.com)

I think it's good to reiterate/reinforce that what's behind the colon is what we call the server name which is what you have written in the configuration. I have found this to be a common source of confusion.

Note that this some something you mention later with "By using delegation, you can host Conduit [...]" and this would bring this a bit to the front?

(Feel free to ignore this comment though, if you do not agree.)

I completely understand what you are trying to say. Maybe the source of the confusion is that Conduit doesn't really "listen" on a domain but only allows for (the hosting of) s single server name. IMO it might be better to say: Delegation can also be used to have Conduit be reachable on a hostname or even domain different from your (configured) server name. I think it's good to reiterate/reinforce that what's behind the colon is what we call the server name which is what you have written in the configuration. I have found this to be a common source of confusion. Note that this some something you mention later with "By using delegation, you can host Conduit \[...\]" and this would bring this a bit to the front? (Feel free to ignore this comment though, if you do not agree.)

purplemeteorite commented

2023-08-05 16:20:35 +00:00

(Migrated from gitlab.com)

Suggestion: Delegation can also be used to host Conduit on a domain different from your server name...
or: A further use of delegation is to host Conduit on a domain different from your server name...
This also means removing or at least changing the last sentence to avoid repetition.

Suggestion: Delegation can also be used to host Conduit on a domain different from your server name... or: A further use of delegation is to host Conduit on a domain different from your server name... This also means removing or at least changing the last sentence to avoid repetition.

girlbossceo commented

2023-08-05 17:17:20 +00:00

(Migrated from gitlab.com)

Any idea where you got this from?

                add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
                add_header 'Access-Control-Allow-Headers' 'X-Requested-With, Content-Type, Authorization';

This is simply serving a JSON file. Why do we need to allow POST, PUT, DELETE, and OPTIONS HTTP methods? I don't see this anywhere in Synapse delegation documentation. I am only aware of Access-Control-Allow-Origin * and Cross-Origin-Resource-Policy cross-origin (which is missing here by the way) being required for the /client file at minimum.

Any idea where you got this from? ``` add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'X-Requested-With, Content-Type, Authorization'; ``` This is simply serving a JSON file. Why do we need to allow POST, PUT, DELETE, and OPTIONS HTTP methods? I don't see this anywhere in Synapse delegation documentation. I am only aware of `Access-Control-Allow-Origin *` and `Cross-Origin-Resource-Policy cross-origin` (which is missing here by the way) being required for the `/client` file at minimum.

girlbossceo commented

2023-08-05 17:18:01 +00:00

(Migrated from gitlab.com)

Same thing as my review above^
Missing Cross-Origin-Resource-Policy cross-origin and unsure what the purpose of Access-Control-Allow-Headers and Access-Control-Allow-Methods are for.

Same thing as my review above^ Missing `Cross-Origin-Resource-Policy cross-origin` and unsure what the purpose of `Access-Control-Allow-Headers` and `Access-Control-Allow-Methods` are for.

purplemeteorite commented

2023-08-05 17:46:54 +00:00

(Migrated from gitlab.com)

I am unsure as to why, but it is recommended by the specification:
"Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the CORS section in this specification."

I am unsure as to why, but it is recommended by the specification: "Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the [CORS section](https://spec.matrix.org/v1.7/client-server-api/#web-browser-clients) in this specification."

purplemeteorite commented

2023-08-05 17:49:48 +00:00

(Migrated from gitlab.com)

Closing as duplicate. A possible discussion should only happen in one place at the same time.

girlbossceo commented

2023-08-05 18:01:08 +00:00

(Migrated from gitlab.com)

Talked about it in the Conduit chat and I'm going to assume this is really just a misleading or confusing spec issue that Synapse docs deviate from to make it even more confusing.

I've used plenty of mobile and desktop clients (FluffyChat, Nheko, Element, ElementX, Cinny, etc) with just ACAO * and CORP cross-origin with zero issues, but supposedly OPTIONS method is necessary for JavaScript-based clients (?). I definitely know for a fact most of this is really not necessary, but I'm fine with leaving it as is either way.

Talked about it in the Conduit chat and I'm going to assume this is really just a misleading or confusing spec issue that Synapse docs deviate from to make it even more confusing. I've used plenty of mobile and desktop clients (FluffyChat, Nheko, Element, ElementX, Cinny, etc) with just ACAO * and CORP cross-origin with zero issues, but supposedly `OPTIONS` method is necessary for JavaScript-based clients (?). I definitely know for a fact most of this is really not necessary, but I'm fine with leaving it as is either way.

x4u commented

2023-08-07 00:28:31 +00:00

(Migrated from gitlab.com)

This sort of sidesteps the awkward fact that one can’t easily return .json with 200 on httpd as one can with nginx and Caddy.

I don’t believe the current example really works. The only way to bring this in line with your other examples I can think of is to set the headers here, but add instructions for creating the .json file manually.

What would you expect it to be done here?

This sort of sidesteps the awkward fact that one can’t easily return `.json` with `200` on httpd as one can with nginx and Caddy. I don’t believe the current example really works. The only way to bring this in line with your other examples I can think of is to set the headers here, but add instructions for creating the `.json` file manually. What would you expect it to be done here?

purplemeteorite commented

2023-08-07 15:26:14 +00:00

(Migrated from gitlab.com)

This example was not working, therefore, I removed it.

I tried adding a new working one, but given my lack of experience with Apache webservers, I eventually decided to leave this task to someone with more knowledge of httpd.

This example was not working, therefore, I removed it. I tried adding a new working one, but given my lack of experience with Apache webservers, I eventually decided to leave this task to someone with more knowledge of httpd.

x4u commented

2023-08-09 22:41:06 +00:00

(Migrated from gitlab.com)

mod_lua seems to fit the bill. You might have a go at it, or we can leave this for another PR. If someone has a better solution, I’d love to hear it too.

https://gist.github.com/james2doyle/f09b0e159bb30836e593

`mod_lua` seems to fit the bill. You might have a go at it, or we can leave this for another PR. If someone has a better solution, I’d love to hear it too. https://gist.github.com/james2doyle/f09b0e159bb30836e593

x4u commented

2023-08-09 23:14:08 +00:00

(Migrated from gitlab.com)

mentioned in merge request !500

purplemeteorite commented

2023-08-10 14:30:10 +00:00

(Migrated from gitlab.com)

changed this line in version 2 of the diff

changed this line in [version 2 of the diff](/famedly/conduit/-/merge_requests/531/diffs?diff_id=758038405&start_sha=0174085c1d8d337fe722f9a3bde21a49bd87da73#137b89a8b5bee51ad944756e4cafa20086cd75bd_189_189)

purplemeteorite commented

2023-08-10 14:30:11 +00:00

(Migrated from gitlab.com)

added 3 commits

a059c5bc - Added section about delegation
90f54994 - Documentation on how to set up delegation with .well-known
8db0df09 - Remove superseded sections

Compare with previous version

added 3 commits <ul><li>a059c5bc - Added section about delegation</li><li>90f54994 - Documentation on how to set up delegation with .well-known</li><li>8db0df09 - Remove superseded sections</li></ul> [Compare with previous version](/famedly/conduit/-/merge_requests/531/diffs?diff_id=758038405&start_sha=0174085c1d8d337fe722f9a3bde21a49bd87da73)

purplemeteorite commented

2023-08-10 14:36:46 +00:00

(Migrated from gitlab.com)

resolved all threads

x4u commented

2023-08-13 23:24:40 +00:00

(Migrated from gitlab.com)

After this gets merged, I’m happy to redo the httpd snippet in a follow-up PR as discussed above.

After this gets merged, I’m happy to redo the `httpd` snippet in a follow-up PR as discussed above.

Samonitari commented

2023-08-14 07:42:39 +00:00

(Migrated from gitlab.com)

Sorry for chiming in. I use caddy, and I noticed you added an example.

While certainly working, I think it could be better:

example.com {
  # Your main domain's (other) config goes here

  handle_path /.well-known/matrix/* {
    header application/json
    header Access-Control-Allow-Origin *
    header Access-Control-Allow-Methods "GET" # Are you sure we want anything other than GET? Does Allow-Headers provide anything meaningful?
    
    respond /server `{"m.server": "conduit.example.com:443"}`
    respond /client `{"m.homeserver": {"base_url": "https://conduit.example.com"}}`
  }
}

As a side note, I prefer redirecting example.com's .well-known/matrix/* like this:

example.com {

  # Your main domain's (other) config goes here...

  # Well known of delegated matrix server is redirected to matching subdomain, to only include info about it here minimally: separataion of concerns...
  redir /.well-known/matrix/* https://conduit.example.com{uri} 308
}

And the actual JSON response and header controls go to the subdomain's file

Sorry for chiming in. I use caddy, and I noticed you added an example. While certainly working, I think it could be better: ``` example.com { # Your main domain's (other) config goes here handle_path /.well-known/matrix/* { header application/json header Access-Control-Allow-Origin * header Access-Control-Allow-Methods "GET" # Are you sure we want anything other than GET? Does Allow-Headers provide anything meaningful? respond /server `{"m.server": "conduit.example.com:443"}` respond /client `{"m.homeserver": {"base_url": "https://conduit.example.com"}}` } } ``` As a side note, I prefer redirecting `example.com`'s `.well-known/matrix/*` like this: ``` example.com { # Your main domain's (other) config goes here... # Well known of delegated matrix server is redirected to matching subdomain, to only include info about it here minimally: separataion of concerns... redir /.well-known/matrix/* https://conduit.example.com{uri} 308 } ``` And the actual JSON response and header controls go to the subdomain's file

x4u commented

2023-08-14 13:03:14 +00:00

(Migrated from gitlab.com)

mentioned in issue #378

purplemeteorite commented

2023-08-16 15:18:57 +00:00

(Migrated from gitlab.com)

changed this line in version 3 of the diff

changed this line in [version 3 of the diff](/famedly/conduit/-/merge_requests/531/diffs?diff_id=762577007&start_sha=8db0df09aacdc0068daa4fec340770195ed2b364#137b89a8b5bee51ad944756e4cafa20086cd75bd_230_227)

purplemeteorite commented

2023-08-16 15:18:58 +00:00

(Migrated from gitlab.com)

added 2 commits

1d89b211 - Documentation on how to set up delegation with .well-known
b29dc440 - Remove superseded sections

Compare with previous version

added 2 commits <ul><li>1d89b211 - Documentation on how to set up delegation with .well-known</li><li>b29dc440 - Remove superseded sections</li></ul> [Compare with previous version](/famedly/conduit/-/merge_requests/531/diffs?diff_id=762577007&start_sha=8db0df09aacdc0068daa4fec340770195ed2b364)

purplemeteorite commented

2023-08-16 15:23:21 +00:00

(Migrated from gitlab.com)

Thank you for your suggestions. The example now uses handle_path.

Your question about Access-Control-Allow-Methods has been answered earlier already.

Thank you for your suggestions. The example now uses `handle_path`. Your question about `Access-Control-Allow-Methods` has been [answered earlier](https://gitlab.com/famedly/conduit/-/merge_requests/531#note_1501792515) already.

purplemeteorite commented

2023-08-16 15:23:22 +00:00

(Migrated from gitlab.com)

resolved all threads

jfowl commented

2023-09-01 14:39:39 +00:00

(Migrated from gitlab.com)

### Delegation

because otherwise "Setting up the Reverse Proxy" would be on the same level and thus an empty section

```suggestion:-0+0 ### Delegation ``` because otherwise "Setting up the Reverse Proxy" would be on the same level and thus an empty section

jfowl commented

2023-09-01 14:39:40 +00:00

(Migrated from gitlab.com)

thus, this should probably become

#### Setting up delegation

thus, this should probably become ```suggestion:-0+0 #### Setting up delegation ```

jfowl commented

2023-09-01 14:39:40 +00:00

(Migrated from gitlab.com)

A matrix username has the format `@username:example.com`, where `example.com` corresponds to the server name. Other homeservers and clients will try to use this address to reach your server. By default, clients use port 443 and federation traffic (= other Matrix servers) uses port 8448. If you want to host Conduit under a different domain than in your usernames (e.g. `conduit.example.com`) or use a different port, delegation makes it possible to reroute incoming requests to an address and port of your choice. Both of these are optional, and they are not exclusive.

```suggestion:-0+0 A matrix username has the format `@username:example.com`, where `example.com` corresponds to the server name. Other homeservers and clients will try to use this address to reach your server. By default, clients use port 443 and federation traffic (= other Matrix servers) uses port 8448. If you want to host Conduit under a different domain than in your usernames (e.g. `conduit.example.com`) or use a different port, delegation makes it possible to reroute incoming requests to an address and port of your choice. Both of these are optional, and they are not exclusive. ```

jfowl commented

2023-09-01 14:39:41 +00:00

(Migrated from gitlab.com)

Delegation can be set up with an [SRV DNS record](https://matrix-org.github.io/synapse/latest/delegate.html#srv-dns-record-delegation) or by serving a JSON response, usually referred to as [`.well-known` delegation](https://matrix-org.github.io/synapse/latest/delegate.html#well-known-delegation).

Below are some example configs for some popular reverse proxies to set up `.well-known` delegation.

Replace `example.com` with the server name you want in your usernames (`@user:example.com`), and `conduit.example.com` with the domain of the server where Conduit is running.

I would suggest to just referring to the synapse docs for an explanation of the delegation methods, as they are somewhat the canonical source for info on this.

```suggestion:-0+0 Delegation can be set up with an [SRV DNS record](https://matrix-org.github.io/synapse/latest/delegate.html#srv-dns-record-delegation) or by serving a JSON response, usually referred to as [`.well-known` delegation](https://matrix-org.github.io/synapse/latest/delegate.html#well-known-delegation). Below are some example configs for some popular reverse proxies to set up `.well-known` delegation. Replace `example.com` with the server name you want in your usernames (`@user:example.com`), and `conduit.example.com` with the domain of the server where Conduit is running. ``` I would suggest to just referring to the synapse docs for an explanation of the delegation methods, as they are somewhat the canonical source for info on this.

jfowl commented

2023-09-01 14:39:41 +00:00

(Migrated from gitlab.com)

Since Conduit listens on port 6167 by default, you need to set up a reverse proxy to forward incoming requests to it. By default, ports 8448 and 443 need to be forwarded. If you have set up delegation, you probably only need to forward 443 to conduit. Example configurations for various reverse proxies can be found below.

```suggestion:-0+0 Since Conduit listens on port 6167 by default, you need to set up a reverse proxy to forward incoming requests to it. By default, ports 8448 and 443 need to be forwarded. If you have set up delegation, you probably only need to forward 443 to conduit. Example configurations for various reverse proxies can be found below. ```

jfowl commented

2023-09-01 14:39:41 +00:00

(Migrated from gitlab.com)

Thanks for filling this documentation gap <3

I have left a few small suggestions, but other than that I'm happy.

Thanks for filling this documentation gap <3 I have left a few small suggestions, but other than that I'm happy.

purplemeteorite commented

2023-09-02 18:09:01 +00:00

(Migrated from gitlab.com)

I strongly disagree, but I am curious to hear the reason for your suggestion. IMHO, it is simply counterproductive to increase the number of clicks a user has to make to understand what is happening.
Furthermore, we should orient after the specs, not the synapse documentation. Using the latter as a basis for this documentation is a great way to copy mistakes or some custom synapse setting.

I strongly disagree, but I am curious to hear the reason for your suggestion. IMHO, it is simply counterproductive to increase the number of clicks a user has to make to understand what is happening. Furthermore, we should orient after the specs, not the synapse documentation. Using the latter as a basis for this documentation is a great way to copy mistakes or some custom synapse setting.

purplemeteorite commented

2023-09-02 18:25:56 +00:00

(Migrated from gitlab.com)

This is a bit wordy and introduces repetitions.

Because they have read the section about delegation, they know how it works. Blankly stating that they (probably) only need 443 is unnecessary and could lead to confusion as to why they need this port and not some other. We should aim to inform about possible configurations, not decide for one and ignore others.

I will not apply this suggestion.

This is a bit wordy and introduces repetitions. Because they have read the section about delegation, they know how it works. Blankly stating that they (probably) only need 443 is unnecessary and could lead to confusion as to why they need this port and not some other. We should aim to inform about possible configurations, not decide for one and ignore others. I will not apply this suggestion.

purplemeteorite commented

2023-09-02 18:29:16 +00:00

(Migrated from gitlab.com)

Could it be more useful to set "Setting up the Reverse Proxy" as a top level header?

x4u commented

2023-10-25 00:03:03 +00:00

(Migrated from gitlab.com)

mentioned in merge request !556

This pull request is broken due to missing fork information.

View command line instructions