feat(deploy): rootless podman + Quadlet deployment (forgejo-mcp-broker-8yd)

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>

deploy/podman/fjmcp-broker.container

@@ -0,0 +1,46 @@
+# Podman Quadlet unit for fjmcp-broker.
+#
+# Drop this file at ~/.config/containers/systemd/fjmcp-broker.container,
+# then run:
+#   systemctl --user daemon-reload
+#   systemctl --user start fjmcp-broker
+#
+# Quadlet generates a transient systemd service from this file. State
+# lives in the named volume "fjmcp-state"; recreating the container
+# preserves SQLite data and registered OAuth clients.
+
+[Unit]
+Description=fjmcp-broker — OAuth 2.1 broker for forgejo-mcp
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+Image=ghcr.io/olemd/fjmcp-broker:latest
+ContainerName=fjmcp-broker
+
+# Named volume for persistent SQLite state. Quadlet creates the volume
+# on first start if it doesn't exist.
+Volume=fjmcp-state:/data:Z
+
+# Required configuration. Set FJMCP_BROKER_PUBLIC_URL to the
+# Caddy-fronted hostname clients will see. Forgejo OAuth credentials
+# come from a separate file outside this unit so the unit itself is
+# safe to commit.
+EnvironmentFile=%h/.config/fjmcp-broker.env
+Environment=FJMCP_BROKER_LISTEN=:8080
+Environment=FJMCP_BROKER_STORE=/data/broker.db
+
+# Caddy reverse-proxies to localhost:8080.
+PublishPort=127.0.0.1:8080:8080
+
+# Healthcheck via /healthz. Three failures (90s) trigger restart.
+HealthCmd=/usr/local/bin/fjmcp-broker --version
+HealthInterval=30s
+HealthRetries=3
+
+[Service]
+Restart=on-failure
+RestartSec=10s
+
+[Install]
+WantedBy=default.target

deploy/podman/fjmcp-broker.env.example

@@ -0,0 +1,25 @@
+# Example environment file for fjmcp-broker.
+#
+# Copy this to ~/.config/fjmcp-broker.env (chmod 0600) and fill in the
+# real values. The Quadlet unit reads this via EnvironmentFile=.
+
+# Public-facing URL — what clients (Claude.ai) will see. MUST match
+# what Caddy serves; the broker uses this verbatim in OAuth metadata.
+FJMCP_BROKER_PUBLIC_URL=https://mcp.example.com
+
+# Upstream Forgejo instance. The broker delegates user authentication
+# here via OAuth2.
+FORGEJO_URL=https://forgejo.example.com
+
+# OAuth2 application credentials. Create the application at
+# Forgejo → Settings → Applications → OAuth2 Applications,
+# with the redirect URI set to ${FJMCP_BROKER_PUBLIC_URL}/oauth/callback.
+FORGEJO_OAUTH_CLIENT_ID=replace-with-your-forgejo-app-id
+FORGEJO_OAUTH_CLIENT_SECRET=replace-with-your-forgejo-app-secret
+
+# Scopes requested from Forgejo. The default covers the full forgejo-mcp
+# tool surface. Trim if your users don't need write access.
+FORGEJO_OAUTH_SCOPES=read:user write:repository write:issue write:notification read:organization
+
+# Optional: verbose logging.
+# FJMCP_BROKER_DEBUG=true