From 27fcd7fe3a0699fe86f687449f8d00855c0cebbc Mon Sep 17 00:00:00 2001 From: stratself Date: Sat, 4 Apr 2026 10:46:28 +0000 Subject: [PATCH] docs(docker,delegation): Fix .well-known docs - check below for details .well-known env var in example composes now point to `example.com:443`, and are turned on by default for Caddy labels and the Traefik configs. For the Caddyfile example, they're left uncommented. Added small bulletpoint on how to use this env var. Consistencize all the .well-known comments inside these composes. I don't want to overly fix the example composes and get it wrong, so this small change should be enough. Split-domain deployments are fully outsourced to the Delegation page now, and some changes are also made there to be more comprehensive. --- docs/advanced/delegation.mdx | 5 +++++ docs/deploying/docker.mdx | 13 +++++++++---- .../public/deploying/docker-compose.for-traefik.yml | 8 +++----- .../deploying/docker-compose.with-caddy-labels.yml | 12 ++++++++---- docs/public/deploying/docker-compose.with-caddy.yml | 10 ++++++++++ .../deploying/docker-compose.with-traefik.yml | 8 +++----- docs/public/deploying/docker-compose.yml | 9 +++++++++ 7 files changed, 47 insertions(+), 18 deletions(-) diff --git a/docs/advanced/delegation.mdx b/docs/advanced/delegation.mdx index 3c718dc23..290a621b8 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 #admin room if unset #support_page = #support_role = "m.role.admin" #support_email = @@ -42,6 +43,10 @@ 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 diff --git a/docs/deploying/docker.mdx b/docs/deploying/docker.mdx index 887f06444..f6dd016a1 100644 --- a/docs/deploying/docker.mdx +++ b/docs/deploying/docker.mdx @@ -41,8 +41,10 @@ Continuwuity requires HTTPS for Matrix federation. You'll need: - A reverse proxy with SSL/TLS certificates (Traefik, Caddy, nginx, etc.) - see [Docker Compose](#docker-compose) for complete examples. - Port `:443` (for Client-Server traffic) and `:8448` (for federation traffic) opened on your server's firewall. + - Alternatively, if you want both client and federation traffic on `:443`, you can configure `CONTINUWUITY_WELL_KNOWN` following some of the examples below. + :::tip Alternative setups -For setups with `.well-known` delegation, different ports, and/or split-domain deployments, consult the [Delegation/Split-domain](../advanced/delegation) page. +For more setups with `.well-known` delegation and split-domain deployments, consult the [Delegation/Split-domain](../advanced/delegation) page. ::: @@ -128,7 +130,7 @@ nameserver 1.0.0.1 nameserver 1.1.1.1 ``` -Consult the [**DNS tuning guide (recommended)**](../advanced/dns) for full solutions to this issue. +Consult the [**DNS tuning guide (recommended)**](../advanced/dns.mdx) for full solutions to this issue. ::: #### Caddy (using Caddyfile) @@ -197,7 +199,7 @@ Consult the [**DNS tuning guide (recommended)**](../advanced/dns) for full solut -You will then need to point your reverse proxy towards Continuwuity at `127.0.0.1:8008` +You will then need to point your reverse proxy towards Continuwuity at `127.0.0.1:8008`. See the [Other reverse proxies](generic.mdx#setting-up-the-reverse-proxy) section of the Generic page for further routing details. ### Starting Your Server @@ -238,5 +240,8 @@ section in the development documentation. ## Next steps -- For smooth federation, set up a caching resolver according to the [DNS tuning guide](../advanced/dns) +- Test that your setup works by following these [instructions](./generic.mdx#how-do-i-know-it-works) +- For smooth federation, set up a caching resolver according to the [DNS tuning guide](../advanced/dns.mdx) - To set up Audio/Video communication, see the [Calls](../calls.mdx) page. +If you want to set up an appservice, take a look at the [Appservice +Guide](../appservices.mdx). diff --git a/docs/public/deploying/docker-compose.for-traefik.yml b/docs/public/deploying/docker-compose.for-traefik.yml index e7b1a46ff..583fb3975 100644 --- a/docs/public/deploying/docker-compose.for-traefik.yml +++ b/docs/public/deploying/docker-compose.for-traefik.yml @@ -27,13 +27,11 @@ services: CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above - # We need some way to serve the client and server .well-known json. The simplest way is via the CONTINUWUITY_WELL_KNOWN - # variable / config option, there are multiple ways to do this, e.g. in the continuwuity.toml file, and in a separate - # see the override file for more information about delegation + # Serve .well-known files to tell others to reach Continuwuity on port :443 CONTINUWUITY_WELL_KNOWN: | { - client=https://matrix.example.com, - server=matrix.example.com:443 + client=https://example.com, + server=example.com:443 } volumes: diff --git a/docs/public/deploying/docker-compose.with-caddy-labels.yml b/docs/public/deploying/docker-compose.with-caddy-labels.yml index 8e42a41bf..a5e381b79 100644 --- a/docs/public/deploying/docker-compose.with-caddy-labels.yml +++ b/docs/public/deploying/docker-compose.with-caddy-labels.yml @@ -33,13 +33,17 @@ services: CONTINUWUITY_PORT: 8008 #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above - # Required for .well-known delegation - edit these according to your chosen domain - CONTINUWUITY_WELL_KNOWN__CLIENT: https://matrix.example.com - CONTINUWUITY_WELL_KNOWN__SERVER: matrix.example.com:443 + # Serve .well-known files to tell others to reach Continuwuity on port :443 + CONTINUWUITY_WELL_KNOWN: | + { + client=https://example.com, + server=example.com:443 + } + networks: - caddy labels: - caddy: matrix.example.com + caddy: example.com caddy.reverse_proxy: "{{upstreams 8008}}" volumes: db: diff --git a/docs/public/deploying/docker-compose.with-caddy.yml b/docs/public/deploying/docker-compose.with-caddy.yml index b5f65ef3e..fcf2dfdbd 100644 --- a/docs/public/deploying/docker-compose.with-caddy.yml +++ b/docs/public/deploying/docker-compose.with-caddy.yml @@ -28,6 +28,16 @@ services: CONTINUWUITY_ADDRESS: 0.0.0.0 CONTINUWUITY_PORT: 8008 #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + + ## (Optional) Serve .well-known files to tell others to reach Continuwuity on port :443 + ## If you do this, remove all routes to port :8448 from the compose and Caddyfile + # CONTINUWUITY_WELL_KNOWN: | + # { + # client=https://example.com, + # server=example.com:443 + # } + + networks: - caddy diff --git a/docs/public/deploying/docker-compose.with-traefik.yml b/docs/public/deploying/docker-compose.with-traefik.yml index e971aaa0d..afa6df3b2 100644 --- a/docs/public/deploying/docker-compose.with-traefik.yml +++ b/docs/public/deploying/docker-compose.with-traefik.yml @@ -24,13 +24,11 @@ services: CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above - # We need some way to serve the client and server .well-known json. The simplest way is via the CONTINUWUITY_WELL_KNOWN - # variable / config option, there are multiple ways to do this, e.g. in the continuwuity.toml file, and in a separate - # reverse proxy, but since you do not have a reverse proxy and following this guide, this example is included + # Serve .well-known files to tell others to reach Continuwuity on port :443 CONTINUWUITY_WELL_KNOWN: | { - client=https://matrix.example.com, - server=matrix.example.com:443 + client=https://example.com, + server=example.com:443 } traefik: diff --git a/docs/public/deploying/docker-compose.yml b/docs/public/deploying/docker-compose.yml index 86a3f2edd..4dc5ec4f1 100644 --- a/docs/public/deploying/docker-compose.yml +++ b/docs/public/deploying/docker-compose.yml @@ -18,5 +18,14 @@ services: CONTINUWUITY_PORT: 8008 #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + ## (Optional) Serve .well-known files to tell others to reach Continuwuity on port :443 + ## If you do this, remove all routes to port :8448 on your reverse proxy + # CONTINUWUITY_WELL_KNOWN: | + # { + # client=https://example.com, + # server=example.com:443 + # } + + volumes: db: