conduit/docs/delegation.md
Matthias Ahouansou 6e913bfec4
docs: delegation
2024-05-02 09:41:27 +01:00

2.6 KiB

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.

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 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_name>
server String The hostname and port servers should use to connect to Conduit <server_name>:443

Example

[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:

{
  "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:

{
  "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, look here.