From 2fe710bdb47e36640a81efaa799e308152f1d594 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Mon, 13 Jul 2026 15:02:20 +0300 Subject: [PATCH] Document Caddy directive-order pitfall for well-known reverse-proxying Caddy evaluates directives according to its own fixed directive order, not their order in the Caddyfile. redir runs before reverse_proxy, so a redirect elsewhere in the same site block silently shadows the /.well-known/matrix reverse-proxying. Add a note and a handle-block example that enforces the intended priority. Fixes #1080 Co-Authored-By: Claude Fable 5 --- docs/configuring-well-known.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md index ec5ad90ce..a2561f90e 100644 --- a/docs/configuring-well-known.md +++ b/docs/configuring-well-known.md @@ -155,6 +155,23 @@ example.com { } ``` +**Note**: Caddy does not process directives in the order they appear in the Caddyfile, but according to its own [directive order](https://caddyserver.com/docs/caddyfile/directives#directive-order). Notably, `redir` is evaluated before `reverse_proxy`, so a `redir` elsewhere in the same site block (a common way to send the base domain to `www.example.com` or to another site) takes precedence and breaks the well-known reverse-proxying. In such cases, wrap the directives in [`handle`](https://caddyserver.com/docs/caddyfile/directives/handle) blocks to enforce the intended priority: + +```caddy +example.com { + handle /.well-known/matrix/* { + reverse_proxy https://matrix.example.com { + header_up Host {upstream_hostport} + } + } + + handle { + # Everything else, e.g. a redirect to some other site + redir https://www.example.com{uri} + } +} +``` + **For HAProxy**, it would be something like this: ```haproxy