Docker

The well-known saga

Posted on by Kenneth Ballard / 0 Comment

With Discord’s recent announcement that they’re going to declare everyone as teenagers unless they go through age verification, my wife and I are looking at alternatives. That way she has something onto which she can move her friends for their weekly D&D games.

Enter Element.

But I’m not going to be talking about trying to get an Element setup off the ground. Yet. Instead I’m focusing on just one part of that: the .well-known files that Matrix clients use for auto-discovery. And files that have the potential to be make-or-break for your setup.

So up-front question: did you know you actually do not have to manually create that?

This is a small detail all of the setup guides I’ve seen so far have overlooked. And it was something I only saw when looking through the Synapse documentation. The setting you’re looking for is public_baseurl. Set this to your homeserver’s hostname and Synapse will expose the .well-known/matrix/client endpoint and generate the JSON for you based on your configuration.

And if you’re setting up to use the Matrix Authentication Service (which you should), it will automatically include the necessary details based on your configuration.

So if your homeserver.yaml includes public_baseurl: "https://[homeserver-hostname]" – and, yes, it must be in quotes – and you’re using the MAS, the JSON output will be this:

{
  "m.homeserver": {
    "base_url": "https://[homeserver-hostname]/"
  },
  "org.matrix.msc2965.authentication": {
    "issuer": "https://[auth-hostname]/",
    "account": "https://[auth-hostname]/account/"
  }
}

In setting up the authentication service, you already know the front-facing hostname is handled by that service’s configuration, not Synapse’s configuration. And Synapse queries the MAS for those values for the output. It’s a quick check on your configuration, since not seeing that output or not seeing the correct values means something is misconfigured. And it preserves the SSoT principle – single source of truth – for your settings.

Mostly.

Unfortunately Synapse does not generate the needed output from the matrix_rtc settings (I’ve filed a bug about that), but there’s an easy way to add that using the extra_well_known_client_content setting:

matrix_rtc:
  transports:
  - type: livekit
    livekit_service_url: https://[rtc-hostname]/

# You also need to set serve_server_wellknown as true to also generate and
# serve .well-known/matrix/server for MatrixRTC

serve_server_wellknown: true
extra_well_known_client_content:
  org.matrix.msc4143.rtc_foci:
  - type: livekit
    livekit_service_url: https://[rtc-hostname]/

Yes it does mean you’re duplicating settings in your homeserver.yaml, but this does give you an avenue to avoid needing to create the JSON files manually. This is what the final JSON will look like:

{
  "m.homeserver": {
    "base_url": "https://[homeserver-hostname]/"
  },
  "org.matrix.msc2965.authentication": {
    "issuer": "https://[auth-hostname]/",
    "account": "https://[auth-hostname]/account/"
  },
  "org.matrix.msc4143.rtc_foci": [
    {
      "type": "livekit",
      "livekit_service_url": "https://[rtc-hostname]/"
    }
  ]
}

Kenneth Ballard