sysadminandClaude Opus 4.8
1301a57de4
Adds docs/architecture/mcp-restart-governance.md, the restart-governance/v1 ADR defining who may restart the MCP control plane and under what conditions. - Recovery ladder (reconnect -> rebind -> scoped restart -> full restart -> host) with restart stated as the last resort. - Authorization matrix across author/reviewer/merger/reconciler/controller/ operator/admin; no LLM worker role may perform or authorize a full or host restart. - v1 authority decision recorded: controller approval + automated safety gates; quorum deferred to a superseding ADR. - Break-glass path with pre-declared incident and mandatory post-hoc audit. - Ambiguous policy state denies restart. - Stable policy IDs RG-01..RG-08 for later enforcement code to bind to. Cross-links the ADR from docs/safety-model.md and docs/webui-deployment.md, and adds tests/test_mcp_restart_governance_docs.py asserting acceptance criteria 1-5. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
3.1 KiB
Web UI deployment boundary (#435)
The MCP Control Plane web UI is an internal operator console, not a customer-facing application. The MVP assumes local or trusted-network access only.
MVP deployment model
- Default bind:
127.0.0.1:8765(WEBUI_HOST/WEBUI_PORT) - Authentication: none in MVP — protection comes from network placement.
The authorization, RBAC, redaction, and audit model that future gated writes
must pass through is defined in
webui-authz-audit.md(#633). - Mutations: read-only routes; gated write actions remain disabled (#434)
- Secrets: resolved server-side via
gitea_auth/GITEA_MCP_CONFIG; never embedded in HTML, JavaScript, or browser storage
Do not expose the UI on the public internet without an access layer.
Beyond localhost
If the UI must be reachable outside the operator laptop:
- Prefer Cloudflare Access, Cloudflare WARP, or an org VPN so only authenticated staff reach the service.
- Bind to a specific interface only when necessary — never
0.0.0.0/::without understanding the exposure. - Set explicit override env vars only after access controls are in place:
WEBUI_ALLOW_PUBLIC_BIND=1— acknowledges all-interface bind (0.0.0.0,::)WEBUI_ALLOW_REMOTE_BIND=1— acknowledges a non-loopback host
Startup refuses all-interface binds unless WEBUI_ALLOW_PUBLIC_BIND=1.
Non-loopback binds log a warning unless WEBUI_ALLOW_REMOTE_BIND=1.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
WEBUI_HOST |
127.0.0.1 |
Bind address |
WEBUI_PORT |
8765 |
Listen port |
WEBUI_REPO_ROOT |
repository root | Workflow/schema hash root for prompt library |
WEBUI_PROJECT_REGISTRY |
packaged JSON | Project registry file path |
GITEA_MCP_CONFIG |
unset | Server-side MCP profile config path (optional) |
GITEA_MCP_PROFILE |
unset | Active MCP profile name (optional) |
WEBUI_ALLOW_PUBLIC_BIND |
unset | Acknowledge 0.0.0.0 / :: bind |
WEBUI_ALLOW_REMOTE_BIND |
unset | Acknowledge non-loopback bind |
Gitea credentials (GITEA_TOKEN_*, .env.*, keychain refs) are read only on
the server when a page needs live Gitea data (e.g. /queue). They are not
shipped to the browser.
Health / deployment metadata
GET /health includes a deployment object with bind disposition, runtime
assumption paths, and the client-secret policy. Use it to verify an instance is
configured for internal-only operation.
Process restart / reload disposition
The console never exposes a restart or reload control; process restart of the
MCP control-plane runtime is governed separately. Restart is a last resort behind
reconnect/rebind, full restart is operator/admin-only under controller approval
plus safety gates, and break-glass is an incident-backed path. See
architecture/mcp-restart-governance.md
(#656).
Non-goals (MVP)
- Full SSO or session login in the UI
- Hosting on the public internet without Access/VPN/WARP
- Embedding Gitea tokens in the frontend bundle