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>
Adds a multi-stage Containerfile, Quadlet unit, and operator
walkthrough for a production deploy. The broker spawns forgejo-mcp
per session, so the image bundles both binaries — broker built from
this repo, forgejo-mcp pinned via FORGEJO_MCP_VERSION build-arg
(default 2.18.0).
Image stages:
1. golang:alpine compiles the broker with ldflags-stamped buildinfo
2. golang:alpine clones forgejo-mcp at the pinned tag and compiles it
3. distroless static-nonroot copies both binaries; uid 65532
Persistent state via the named volume `fjmcp-state` mounted at /data.
SQLite WAL + SHM sidecars live alongside broker.db on the same volume,
so a container swap or image upgrade preserves all OAuth clients,
issued tokens, and refresh-token history. Verified end-to-end:
podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test
curl /healthz # store: ok, broker.db created
podman stop fjmcp-test
podman run --rm -d -v fjmcp-test-state:/data ... fjmcp-broker:test
curl /healthz # store: ok, same broker.db
ls volume → broker.db, broker.db-shm, broker.db-wal all present
Quadlet unit (deploy/podman/fjmcp-broker.container) drops into
~/.config/containers/systemd/, reads secrets from a 0600 env file
outside the unit, publishes :8080 on loopback for Caddy to front.
Makefile gains `image` and `image-run` targets. README links to the
new docs/deploy-podman.md walkthrough.
Closes forgejo-mcp-broker-8yd.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
