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]>
71 lines
3.1 KiB
Markdown
71 lines
3.1 KiB
Markdown
# 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`](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:
|
|
|
|
1. Prefer **Cloudflare Access**, **Cloudflare WARP**, or an org **VPN** so only
|
|
authenticated staff reach the service.
|
|
2. Bind to a specific interface only when necessary — never `0.0.0.0` / `::`
|
|
without understanding the exposure.
|
|
3. 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`](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 |