From cef83bf03c4bda77295062e85485ea5d57114c20 Mon Sep 17 00:00:00 2001
From: Hans van Zijst <hans@procolix.com>
Date: Wed, 13 Nov 2024 17:00:39 +0100
Subject: [PATCH] Added a bit about delegation and DNS.

---
 matrix/synapse/README.md | 41 ++++++++++++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/matrix/synapse/README.md b/matrix/synapse/README.md
index 5ba9220..8d1e5a7 100644
--- a/matrix/synapse/README.md
+++ b/matrix/synapse/README.md
@@ -61,10 +61,7 @@ listeners:
         compress: false
 ```
 
-
-
-
-# Database
+## Database
 
 The default installation leaves you with an sqlite3 database. Nice for experimenting, but
 unsuitable for a production environment.
@@ -112,7 +109,7 @@ After changing the database, restart Synapse and check whether it can connect
 and create the tables it needs.
 
 
-# Create admin
+## Create admin
 
 Synapse doesn't create an admin account at install time, so you'll have to do
 that yourself.
@@ -136,9 +133,41 @@ register_new_matrix_user -u admin -a -c /etc/matrix-synapse/conf.d/keys.yaml
 This will ask for a password, choose a safe one.
 
 
-# Logging
+## Logging
 
 Logging is configured in `log.yaml`. Some logging should go to systemd, the
 more specific logging to Synapse's own logfile(s).
 
 
+# Delegation and DNS
+
+If you run your server under a different FQDN than just the domain name you
+want to use, you need to delegate: point from your domain to the server.
+
+Example. You want to use example.com for your domain, but your server is
+called matrix.example.com. To make that work, you need to serve 2 bits of
+JSON-code on https://example.com/ to point clients and servers to the correct
+machine: matrix.example.com.
+
+Pointing servers to the correct server is done by publishing this bit of
+JSON-code under `https://example.com/.well-known/matrix/server`:
+
+```
+{
+  "m.homeserver": {"base_url": "https://matrix.example.com"},
+  "org.matrix.msc3575.proxy": {"url": "https://matrix.example.com"}
+}
+```
+
+Pointing clients to the correct server needs this at
+`https://example.com/.well-known/matrix/client`:
+
+```
+{
+  "m.server": "matrix.example.com"
+}
+```
+
+Very important: both names (example.com and matrix.example.com) must be A
+and/or AAAA records in DNS, not CNAME.
+