olemd/forgejo-mcp-broker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(deploy): Caddy front-end example + walkthrough (forgejo-mcp-broker-r2c)

Browse source 
Adds deploy/caddy/Caddyfile and docs/deploy-caddy.md, the front-end
half of the production deployment that pairs with deploy-podman.md.

Caddyfile:
  - reverse_proxy with flush_interval -1 (mandatory for /mcp SSE)
  - structured JSON access log to a separate file
  - validated with `caddy validate` and formatted with `caddy fmt`
  - omits explicit X-Forwarded-{For,Proto,Host} since Caddy forwards
    them by default (caddy validate flags them as redundant)

deploy-caddy.md walks operators through:
  - why a reverse proxy at all (TLS, SSE, future rate limits)
  - the host-header trap and why FJMCP_BROKER_PUBLIC_URL is the
    trusted source of issuer URLs (cross-references the existing
    TestDiscovery_IssuerIgnoresHostHeader regression)
  - SSE buffering as the most common deployment foot-gun
  - optional rate-limit recipe via caddy-ratelimit (defers to backlog
    issue -ttl)
  - troubleshooting for the four failure modes the broker has actually
    seen during dev: wrong issuer, buffered SSE, unreachable upstream,
    TLS conflict

README updated to link both deploy guides and the deploy/ subtree.

Closes forgejo-mcp-broker-r2c.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ole-Morten Duesund 2026-04-27 17:49:25 +02:00
commit c18120c470
5 changed files with 184 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

36
deploy/caddy/Caddyfile Normal file
View file

@ -0,0 +1,36 @@
# Caddyfile for fjmcp-broker.
#
# Place at /etc/caddy/Caddyfile (or wherever your Caddy reads from) and
# replace `mcp.example.com` with your real hostname. Caddy fetches an
# automatic Let's Encrypt cert on first start.
#
# This config front-ends the broker container that listens on
# 127.0.0.1:8080 (matching deploy/podman/fjmcp-broker.container).
mcp.example.com {
encode zstd gzip
# Reverse-proxy everything to the broker. The broker mounts every
# endpoint at the root: /healthz, /oauth/*, /.well-known/*, /mcp.
#
# Caddy already forwards X-Forwarded-For / X-Forwarded-Proto / Host
# by default, so they're not listed below. The broker derives its
# own identity from FJMCP_BROKER_PUBLIC_URL anyway and ignores
# these headers (see TestDiscovery_IssuerIgnoresHostHeader).
reverse_proxy 127.0.0.1:8080 {
# SSE responses on /mcp need flushed-as-we-go forwarding;
# default buffering would defeat the streaming model. -1 means
# "flush every write".
flush_interval -1
}
# Optional: drop a structured access log under a separate file so
# broker stderr stays clean for application events.
log {
output file /var/log/caddy/fjmcp-broker.log {
roll_size 50mb
roll_keep 5
}
format json
}
}