From 72eabc9796700ce55b84882b966a0bf425e0d1fe Mon Sep 17 00:00:00 2001
From: stratself <stratself@noreply.forgejo.ellis.link>
Date: Wed, 8 Apr 2026 10:45:23 +0000
Subject: [PATCH] docs(delegation): Add section for manually serving
 .well-knowns files

* Also add note on default support contacts
* Also add individual env vars for .well-knowns
---
 docs/advanced/delegation.mdx | 47 +++++++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/docs/advanced/delegation.mdx b/docs/advanced/delegation.mdx
index 3c718dc23..e2e4d7b92 100644
--- a/docs/advanced/delegation.mdx
+++ b/docs/advanced/delegation.mdx
@@ -24,6 +24,7 @@ client = "https://matrix.example.com"
 server = "matrix.example.com:443"
 
 # (optional) customize your support contacts
+# Defaults to members of the admin room if unset
 #support_page =
 #support_role = "m.role.admin"
 #support_email =
@@ -42,9 +43,13 @@ services:
         client=https://matrix.example.com,
         server=matrix.example.com:443
         }
+
+      # You can also configure individual .well-knowns as below
+      # CONTINUWUITY_WELL_KNOWN__CLIENT: https://matrix.example.com
+      # CONTINUWUITY_WELL_KNOWN__SERVER: matrix.example.com:443
 ```
 
-## Serving with a reverse proxy
+## Reverse proxying .well-knowns to Continuwuity
 
 After doing the steps above, Continuwuity will serve these 3 JSON files:
 
@@ -94,9 +99,7 @@ Restart Continuwuity and your reverse proxy. Once that's done, visit these route
 <summary>`https://example.com/.well-known/matrix/server`</summary>
 
 ```json
-{
-  "m.server": "matrix.example.com:443"
-}
+{ "m.server": "matrix.example.com:443" }
 ```
 
 </details>
@@ -115,8 +118,44 @@ Restart Continuwuity and your reverse proxy. Once that's done, visit these route
 
 </details>
 
+### Serving .well-knowns manually
+
+Instead of reverse proxying .well-knowns, you can serve them directly as static JSON files that matches the ones above. This is useful if your base domain points to a different physical server, and reverse proxying isn't available.
+
+<details>
+
+<summary>Example Caddyfile **for the base domain**</summary>
+
+```
+https://example.com {
+
+    respond /.well-known/matrix/server 200 {
+        body `{"m.server":"matrix.example.com:443"}`
+    }
+
+    handle /.well-known/matrix/client {
+    header Access-Control-Allow-Origin *
+    respond <<JSON
+    {
+        "m.homeserver": {
+            "base_url": "https://matrix.example.com/"
+        }
+    }
+    JSON
+    }
+}
+```
+
+</details>
+
+When doing this, the `[global.well_known]` configurations can be safely removed. Remember to set the `Access-Control-Allow-Origin: *` header in your `/.well-known/matrix/client` path for web clients to work.
+
 ## Troubleshooting
 
+Check with the [Matrix Connectivity Tester][federation-tester] to see that it's working.
+
+[federation-tester]: https://federationtester.mtrnord.blog/
+
 ### Cannot log in with web clients
 
 Make sure there is an `Access-Control-Allow-Origin: *` header in your `/.well-known/matrix/client` path. While Continuwuity serves this header by default, it may be dropped by reverse proxies or other middlewares.