diff --git a/docs/advanced/delegation.mdx b/docs/advanced/delegation.mdx index 085448534..e2cb3f0fa 100644 --- a/docs/advanced/delegation.mdx +++ b/docs/advanced/delegation.mdx @@ -50,8 +50,6 @@ # Defaults to members of the admin room if unset # CONTINUWUITY_WELL_KNOWN__SERVER: matrix.example.com:443 ``` -## Reverse proxying well-known files to Continuwuity - After doing the steps above, Continuwuity will serve these 3 JSON files: - `/.well-known/matrix/client`: for Client-Server discovery @@ -60,9 +58,11 @@ ## Reverse proxying well-known files to Continuwuity To enable full discovery, you will need to reverse proxy these paths from the base domain back to Continuwuity. +## Reverse proxying well-known files to Continuwuity +
-For Caddy +For **Caddy** ``` matrix.example.com:443 { @@ -78,7 +78,7 @@ ## Reverse proxying well-known files to Continuwuity
-For Traefik (via Docker labels) +For **Traefik** (via Docker labels) ``` services: @@ -93,7 +93,10 @@ ## Reverse proxying well-known files to Continuwuity
-Restart Continuwuity and your reverse proxy. Once that's done, visit these routes and check that the responses match the examples below: + +For **Docker** users, consult the compose files in the [Appendix section](#docker-compose-examples). + +After applying these changes, restart Continuwuity and your reverse proxy.Visit these routes and check that the responses match the examples below:
@@ -253,3 +256,45 @@ ## Related Documentation - [Server-to-Server resolution](https://spec.matrix.org/v1.17/server-server-api/#resolving-server-names) (see this for more information on SRV records) - [Client-to-Server resolution](https://spec.matrix.org/v1.17/client-server-api/#server-discovery) - [MSC1929: Homeserver Admin Contact and Support page](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) + +## Appendix + +### Docker Compose examples + +The following Compose files are taken from [Docker instructions](../deploying/docker.mdx) and reconfigured to support split-domain delegation. Note the updated `CONTINUWUITY_WELL_KNOWN` variable and relevant changes in reverse proxy rules. + +
+Caddy (using Caddyfile) - delegated.docker-compose.with-caddy.yml ([view raw](/advanced/delegated.docker-compose.with-caddy.yml)) + +```yaml file="../public/advanced/delegated.docker-compose.with-caddy.yml" + +``` + +
+ +
+Caddy (using labels) - delegated.docker-compose.with-caddy-labels.yml ([view raw](/advanced/delegated.docker-compose.with-caddy-labels.yml)) + +```yaml file="../public/advanced/delegated.docker-compose.with-caddy-labels.yml" + +``` + +
+ +
+Traefik (for existing setup) - delegated.docker-compose.for-traefik.yml ([view raw](/advanced/delegated.docker-compose.for-traefik.yml)) + +```yaml file="../public/advanced/delegated.docker-compose.for-traefik.yml" + +``` + +
+ +
+Traefik included - delegated.docker-compose.with-traefik.yml ([view raw](/advanced/delegated.docker-compose.with-traefik.yml)) + +```yaml file="../public/advanced/delegated.docker-compose.with-traefik.yml" + +``` + +
diff --git a/docs/public/advanced/delegated.docker-compose.for-traefik.yml b/docs/public/advanced/delegated.docker-compose.for-traefik.yml new file mode 100644 index 000000000..2c170a984 --- /dev/null +++ b/docs/public/advanced/delegated.docker-compose.for-traefik.yml @@ -0,0 +1,44 @@ +# Continuwuity - Behind Traefik Reverse Proxy + +services: + homeserver: + image: forgejo.ellis.link/continuwuation/continuwuity:latest + restart: unless-stopped + command: /sbin/conduwuit + volumes: + - db:/var/lib/continuwuity + - ./continuwuity-resolv.conf:/etc/resolv.conf # use custom resolvers rather than Docker's + #- ./continuwuity.toml:/etc/continuwuity.toml + networks: + - proxy + labels: + - "traefik.enable=true" + - "traefik.http.routers.continuwuity.rule=(Host(`matrix.example.com`) || (Host(`example.com`) && PathPrefix(`/.well-known/matrix`)))" + - "traefik.http.routers.continuwuity.entrypoints=websecure" # your HTTPS entry point + - "traefik.http.routers.continuwuity.tls=true" + - "traefik.http.routers.continuwuity.service=continuwuity" + - "traefik.http.services.continuwuity.loadbalancer.server.port=8008" + # possibly, depending on your config: + # - "traefik.http.routers.continuwuity.tls.certresolver=letsencrypt" + environment: + CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS + CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity + CONTINUWUITY_ADDRESS: 0.0.0.0 + CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label + #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + + # 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 + } + +volumes: + db: + +networks: + # This is the network Traefik listens to, if your network has a different + # name, don't forget to change it here and in the docker-compose.override.yml + proxy: + external: true diff --git a/docs/public/advanced/delegated.docker-compose.with-caddy-labels.yml b/docs/public/advanced/delegated.docker-compose.with-caddy-labels.yml new file mode 100644 index 000000000..3fac2e410 --- /dev/null +++ b/docs/public/advanced/delegated.docker-compose.with-caddy-labels.yml @@ -0,0 +1,54 @@ +# Continuwuity - With Caddy Labels + +services: + caddy: + # This compose file uses caddy-docker-proxy as the reverse proxy for Continuwuity! + # For more info, visit https://github.com/lucaslorentz/caddy-docker-proxy + image: lucaslorentz/caddy-docker-proxy:ci-alpine + ports: + - 80:80 + - 443:443 + environment: + - CADDY_INGRESS_NETWORKS=caddy + networks: + - caddy + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./data:/data + restart: unless-stopped + labels: + caddy: example.com + caddy.reverse_proxy: /.well-known/matrix/* homeserver:8008 + + homeserver: + image: forgejo.ellis.link/continuwuation/continuwuity:latest + restart: unless-stopped + command: /sbin/conduwuit + volumes: + - db:/var/lib/continuwuity + - ./continuwuity-resolv.conf:/etc/resolv.conf # use custom resolvers rather than Docker's + #- ./continuwuity.toml:/etc/continuwuity.toml + environment: + CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS + CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity + CONTINUWUITY_ADDRESS: 0.0.0.0 + CONTINUWUITY_PORT: 8008 + #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + + # 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 + } + + networks: + - caddy + labels: + caddy: matrix.example.com + caddy.reverse_proxy: "{{upstreams 8008}}" +volumes: + db: + +networks: + caddy: diff --git a/docs/public/advanced/delegated.docker-compose.with-caddy.yml b/docs/public/advanced/delegated.docker-compose.with-caddy.yml new file mode 100644 index 000000000..c6e7d2dcb --- /dev/null +++ b/docs/public/advanced/delegated.docker-compose.with-caddy.yml @@ -0,0 +1,57 @@ +# Continuwuity - Using Caddy Docker Image + +services: + caddy: + image: docker.io/caddy:latest + ports: + - 80:80 + - 443:443 + networks: + - caddy + volumes: + - ./data:/data + restart: unless-stopped + configs: + - source: Caddyfile + target: /etc/caddy/Caddyfile + + homeserver: + image: forgejo.ellis.link/continuwuation/continuwuity:latest + restart: unless-stopped + command: /sbin/conduwuit + volumes: + - db:/var/lib/continuwuity + - ./continuwuity-resolv.conf:/etc/resolv.conf # use custom resolvers rather than Docker's + #- ./continuwuity.toml:/etc/continuwuity.toml + environment: + CONTINUWUITY_SERVER_NAME: example.com + CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity + CONTINUWUITY_ADDRESS: 0.0.0.0 + CONTINUWUITY_PORT: 8008 + #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + + ## 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 + } + + networks: + - caddy + +networks: + caddy: + +volumes: + db: + +configs: + Caddyfile: + content: | + https://matrix.example.com:443 { + reverse_proxy http://homeserver:8008 + } + https://example.com { + reverse_proxy /.well-known/matrix* http://homeserver:8008 + } diff --git a/docs/public/advanced/delegated.docker-compose.with-traefik.yml b/docs/public/advanced/delegated.docker-compose.with-traefik.yml new file mode 100644 index 000000000..2dbaaa531 --- /dev/null +++ b/docs/public/advanced/delegated.docker-compose.with-traefik.yml @@ -0,0 +1,84 @@ +# Continuwuity - With Traefik Reverse Proxy + +services: + homeserver: + image: forgejo.ellis.link/continuwuation/continuwuity:latest + restart: unless-stopped + command: /sbin/conduwuit + volumes: + - db:/var/lib/continuwuity + - ./continuwuity-resolv.conf:/etc/resolv.conf # use custom resolvers rather than Docker's + #- ./continuwuity.toml:/etc/continuwuity.toml + networks: + - proxy + labels: + - "traefik.enable=true" + - "traefik.http.routers.continuwuity.rule=(Host(`matrix.example.com`) || (Host(`example.com`) && PathPrefix(`/.well-known/matrix`)))" + - "traefik.http.routers.continuwuity.entrypoints=websecure" + - "traefik.http.routers.continuwuity.tls.certresolver=letsencrypt" + - "traefik.http.services.continuwuity.loadbalancer.server.port=8008" + environment: + CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS + CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity + CONTINUWUITY_ADDRESS: 0.0.0.0 + CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label + #CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above + + # 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 + } + + traefik: + image: "traefik:latest" + container_name: "traefik" + restart: "unless-stopped" + ports: + - "80:80" + - "443:443" + volumes: + - "/var/run/docker.sock:/var/run/docker.sock:z" + - "acme:/etc/traefik/acme" + labels: + - "traefik.enable=true" + + # middleware redirect + - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https" + # global redirect to https + - "traefik.http.routers.redirs.rule=hostregexp(`{host:.+}`)" + - "traefik.http.routers.redirs.entrypoints=web" + - "traefik.http.routers.redirs.middlewares=redirect-to-https" + + environment: + TRAEFIK_LOG_LEVEL: DEBUG + TRAEFIK_ENTRYPOINTS_WEB: true + TRAEFIK_ENTRYPOINTS_WEB_ADDRESS: ":80" + TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_TO: websecure + + TRAEFIK_ENTRYPOINTS_WEBSECURE: true + TRAEFIK_ENTRYPOINTS_WEBSECURE_ADDRESS: ":443" + TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS_CERTRESOLVER: letsencrypt + + TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT: true + # CHANGE THIS to desired email for ACME + TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_EMAIL: user@example.com + TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE: true + TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE_ENTRYPOINT: web + TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_STORAGE: "/etc/traefik/acme/acme.json" + + # Since Traefik 3.6.3, paths with certain "encoded characters" are now blocked by default; we need a couple, or else things *will* break + TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDSLASH: true + TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDHASH: true + + TRAEFIK_PROVIDERS_DOCKER: true + TRAEFIK_PROVIDERS_DOCKER_ENDPOINT: "unix:///var/run/docker.sock" + TRAEFIK_PROVIDERS_DOCKER_EXPOSEDBYDEFAULT: false + +volumes: + db: + acme: + +networks: + proxy: diff --git a/rspress.config.ts b/rspress.config.ts index f3bbf97dd..ad183a101 100644 --- a/rspress.config.ts +++ b/rspress.config.ts @@ -20,7 +20,11 @@ export default defineConfig({ '/deploying/docker-compose.for-traefik.yml', '/deploying/docker-compose.with-traefik.yml', `/deploying/docker-compose.override.yml`, - `/deploying/docker-compose.yml` + `/deploying/docker-compose.yml`, + '/advanced/delegated.docker-compose.with-caddy.yml', + '/advanced/delegated.docker-compose.with-caddy-labels.yml', + '/advanced/delegated.docker-compose.for-traefik.yml', + '/advanced/delegated.docker-compose.with-traefik.yml', ] }, },