From 6e913bfec40e941dc70bad1e4a75bcf77971eeb1 Mon Sep 17 00:00:00 2001 From: Matthias Ahouansou Date: Thu, 2 May 2024 09:27:14 +0100 Subject: [PATCH] docs: delegation --- book.toml | 4 +++ docs/SUMMARY.md | 1 + docs/configuration.md | 1 + docs/delegation.md | 69 +++++++++++++++++++++++++++++++++++++++++++ docs/faq.md | 12 +++++--- 5 files changed, 83 insertions(+), 4 deletions(-) create mode 100644 docs/delegation.md diff --git a/book.toml b/book.toml index e25746ca..700ecda5 100644 --- a/book.toml +++ b/book.toml @@ -16,3 +16,7 @@ git-repository-icon = "fa-git-square" [output.html.search] limit-results = 15 + +[output.html.code.hidelines] +json = "~" + diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f874bb21..afba3cca 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,6 +3,7 @@ - [Introduction](introduction.md) - [Configuration](configuration.md) +- [Delegation](delegation.md) - [Deploying](deploying.md) - [Generic](deploying/generic.md) - [Debian](deploying/debian.md) diff --git a/docs/configuration.md b/docs/configuration.md index efa080dc..d903a21e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -56,6 +56,7 @@ The `global` section contains the following fields: | `turn_secret` | `string` | The TURN secret | `""` | | `turn_ttl` | `integer` | The TURN TTL in seconds | `86400` | | `emergency_password` | `string` | Set a password to login as the `conduit` user in case of emergency | N/A | +| `well_known` | `table` | Used for [delegation](delegation.md) | See [delegation](delegation.md) | ### TLS diff --git a/docs/delegation.md b/docs/delegation.md new file mode 100644 index 00000000..c8e5391c --- /dev/null +++ b/docs/delegation.md @@ -0,0 +1,69 @@ +# Delegation + +You can run Conduit on a separate domain than the actual server name (what shows up in user ids, aliases, etc.). +For example you can have your users have IDs such as `@foo:example.org` and have aliases like `#bar:example.org`, +while actually having Conduit hosted on the `matrix.example.org` domain. This is called delegation. + +## Automatic (recommended) + +Conduit has support for hosting delegation files by itself, and by default uses it to serve federation traffic on port 443. + +With this method, you need to direct requests to `/.well-known/matrix/*` to Conduit in your reverse proxy. + +This is only recommended if Conduit is on the same physical server as the server which serves your server name (e.g. example.org) +as servers don't always seem to cache the response, leading to slower response times otherwise, but it should also work if you +are connected to the server running Conduit using something like a VPN. + +> **Note**: this will automatically allow you to use [sliding sync][0] without any extra configuration + +To configure it, use the following options in the `global.well_known` table: +| Field | Type | Description | Default | +| --- | --- | --- | --- | +| `client` | `String` | The URL that clients should use to connect to Conduit | `https://` | +| `server` | `String` | The hostname and port servers should use to connect to Conduit | `:443` | + +### Example + +```toml +[global.well_known] +client = "https://matrix.example.org" +server = "matrix.example.org:443" +``` + +## Manual + +Alternatively you can serve static JSON files to inform clients and servers how to connect to Conduit. + +### Servers + +For servers to discover how to access your domain, serve a response in the following format for `/.well-known/matrix/server`: + +```json +{ + "m.server": "matrix.example.org:443" +} +``` +Where `matrix.example.org` is the domain and `443` is the port Conduit is accessible at. + +### Clients + +For clients to discover how to access your domain, serve a response in the following format for `/.well-known/matrix/client`: +```json +{ + "m.homeserver": { + "base_url": "https://matrix.example.org" + } +} +``` +Where `matrix.example.org` is the URL Conduit is accessible at. + +To ensure that all clients can access this endpoint, it is recommended you set the following headers for this endpoint: +``` +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS +Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization +``` + +If you also want to be able to use [sliding sync][0], look [here](faq.md#how-do-i-setup-sliding-sync). + +[0]: https://matrix.org/blog/2023/09/matrix-2-0/#sliding-sync diff --git a/docs/faq.md b/docs/faq.md index ce84f818..4c23a25c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,12 +15,16 @@ You can simply stop Conduit, make a copy or file system snapshot of the database ## How do I setup sliding sync? -You need to add a `org.matrix.msc3575.proxy` field to your `.well-known/matrix/client` response which points to Conduit. Here is an example: +If you use the [automatic method for delegation](delegation.md#automatic-recommended) or just proxy `.well-known/matrix/client` to Conduit, sliding sync should work with no extra configuration. +If you don't, continue below. + +You need to add a `org.matrix.msc3575.proxy` field to your `.well-known/matrix/client` response which contains a url which Conduit is accessible behind. +Here is an example: ```json { - "m.homeserver": { - "base_url": "https://matrix.example.org" - }, +~ "m.homeserver": { +~ "base_url": "https://matrix.example.org" +~ }, "org.matrix.msc3575.proxy": { "url": "https://matrix.example.org" }