From 505b331534de36a8e5578e2a1b941aa5f5273102 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Lametti?= Date: Wed, 4 Mar 2026 13:33:08 -0500 Subject: [PATCH] Docs: add example for root domain delegation - Change link in README to internal documentation link; original more detailed link is preserved in documentation page as a reference. - Add Caddy example. TODO: - [x] Add example for Caddy - [ ] Add example for Traefik --- README.md | 2 +- docs/deploying/root-domain-delegation.md | 25 +++++++++++++++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d6139a5a..54dd31ac 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ This is just a summary for the impatient. See the full [documentation](https://matrix-construct.github.io/tuwunel/). > [!TIP] -> Avoid using a sub-domain for your `server_name`. You can always delegate later with a [`.well-known`](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-well-known.md) +> Avoid using a sub-domain for your `server_name`. You can always delegate later with a [`.well-known`](https://matrix-construct.github.io/tuwunel/deploying/root-domain-delegation.html) > file, but you can never change your `server_name`. **2.** Setup TLS certificates. Most users enjoy the [Caddy](https://caddyserver.com/) reverse-proxy diff --git a/docs/deploying/root-domain-delegation.md b/docs/deploying/root-domain-delegation.md index 3e2276a0..b2f60104 100644 --- a/docs/deploying/root-domain-delegation.md +++ b/docs/deploying/root-domain-delegation.md @@ -92,11 +92,28 @@ At a minimum, the following JSON files should be created: ### Option 2: Reverse proxy -This is an example configuration if `example.com` is reverse-proxied behing Nginx. +These are example configurations if `example.com` is reverse-proxied behing Nginx or Caddy. > [!NOTE] > Replace `tuwunel` with the URL where tuwunel is listening; this may look like `127.0.0.1:8008`, `matrix.example.com`, or `tuwunel` if you declared an `upstream tuwunel` block. +> [!IMPORTANT] +> These configurations need to be applied to the reverse proxy for `example.com`, **not** `matrix.example.com`. + +#### Caddy + + + +```caddy +example.com { + reverse_proxy /.well-known/matrix/* https://matrix.example.com { + header_up Host {upstream_hostport} + } +} +``` + +#### Nginx + ```nginx,hidelines=~ server { ~listen 443 ssl http2; @@ -116,3 +133,9 @@ server { ## Testing Navigate to `example.com/.well-known/matrix/client` and `example.com/.well-known/matrix/server`. These should display results similar to the [JSON snippets above](#option-1-static-json-files). + +Entering `example.com` in the [Matrix federation tester](https://federationtester.matrix.org/) should also work. + +## Additional resources + +For a more complete guide, see the Matrix setup with Ansible and Docker [documentation on setting up `.well-known`](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-well-known.md).