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
This commit is contained in:
André Lametti
2026-03-04 13:33:08 -05:00
parent b81ef81a70
commit 505b331534
2 changed files with 25 additions and 2 deletions

View File

@@ -51,7 +51,7 @@ This is just a summary for the impatient. See the full
[documentation](https://matrix-construct.github.io/tuwunel/). [documentation](https://matrix-construct.github.io/tuwunel/).
> [!TIP] > [!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`. > file, but you can never change your `server_name`.
**2.** Setup TLS certificates. Most users enjoy the [Caddy](https://caddyserver.com/) reverse-proxy **2.** Setup TLS certificates. Most users enjoy the [Caddy](https://caddyserver.com/) reverse-proxy

View File

@@ -92,11 +92,28 @@ At a minimum, the following JSON files should be created:
### Option 2: Reverse proxy ### 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] > [!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. > 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
<!-- from https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/c9bb48ff110dfca73946c69780ef8633e87b22f9/docs/configuring-well-known.md?plain=1#L150,L156 -->
```caddy
example.com {
reverse_proxy /.well-known/matrix/* https://matrix.example.com {
header_up Host {upstream_hostport}
}
}
```
#### Nginx
```nginx,hidelines=~ ```nginx,hidelines=~
server { server {
~listen 443 ssl http2; ~listen 443 ssl http2;
@@ -116,3 +133,9 @@ server {
## Testing ## 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). 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).