gitza-mcp/OPERATIONS.md

156 lines
8.7 KiB
Markdown

# Gitza MCP operations
## Deployment boundary
Deploy to an approved South African application host. Keep the service,
PostgreSQL, secrets, logs and backups inside that approved boundary. Consult your
operator's infrastructure inventory for current topology and addresses. This
guide does not require access to Gitza's internal infrastructure documentation or
claim that a public endpoint is already deployed.
Use one application replica in v1. Concurrency is bounded per process; multi-replica
deployment requires a shared concurrency lease implementation before rollout.
## Configuration and first deployment
The repository includes `compose.yml`, which starts PostgreSQL 18, runs the
one-shot migrator successfully, and only then starts the MCP process. The
application connects as a separate `mcp` database owner without superuser,
database-creation or role-management privileges. PostgreSQL is on an internal
Docker network with no host port. Only the MCP joins the proxy-facing network.
Generate persistent keys once, after building or installing the package:
```sh
gitza-mcp generate-secrets .env.secrets
```
This writes database passwords, cookie/encryption keys and a private signing JWK
to a new file with owner-only permissions. It refuses existing files and
symlinks. It never prints the secrets. Keep a separate secure backup; do not
regenerate keys during deployments. On Windows, also restrict the file's ACL.
Create a private `.env.hosted` from the hosted fields in `.env.example`, including
the real origins and confidential OAuth application credentials. Do not copy
empty secret fields over generated values. Use the generated base64url database
passwords unchanged; URL-special characters need encoding in `DATABASE_URL`.
```sh
docker compose --env-file .env.hosted --env-file .env.secrets up --build -d --wait
```
Put the MCP service behind your HTTPS proxy on its internal port 3400. When using
Coolify, create a public Git application with Docker Compose build pack,
`/compose.yml`, and route the `mcp` service to the chosen HTTPS origin on port 3400.
Supply configuration through its secret environment settings. Keep the database
volume across deployments and pin the source commit or release tag. Do not expose
the `postgres` or `migrate` services to the proxy. The image runs read-only as a
non-root user, drops capabilities and waits up to 25 seconds for shutdown.
The generated secrets are for a fresh database. Changing the password variables
does not update a role in an existing PostgreSQL volume; rotate credentials with
an explicit database change and update the application together.
For a separately managed database or container platform, use these equivalent steps:
1. Provision a dedicated PostgreSQL 18 database and a non-superuser application role.
2. Register a confidential OAuth application in the operator's ordinary Gitza account
settings, with callback `https://YOUR_MCP_ORIGIN/auth/callback`. Do not use the
instance-wide administrative application registration facility.
3. Set the configuration documented in `.env.example`. `MCP_ORIGIN` and `GITZA_URL`
are HTTPS origins, without paths. No URL or host is supplied by a tool caller.
4. Generate a private RSA signing JWK Set, a cookie key and an encryption key offline.
Each cookie/encryption key must have at least 32 random bytes (exactly 32 for
encryption), encoded as base64url. Persist all keys across restarts.
5. Build the image from the repository root with `docker build -f Dockerfile -t gitza-mcp:0.1.0 .`.
6. Run the image with command `migrate` as a separate release step. The web process
checks the schema and never runs migrations automatically.
7. Start with command `http`, `HOST=0.0.0.0`, and port 3400 behind TLS. Set
`MCP_TRUST_PROXY` only to the exact proxy addresses/CIDRs, not a blanket trust flag.
8. Check `/healthz`, `/readyz`, OAuth discovery and an actual sign-in with two test
accounts. The proxy must preserve Host and stream POST responses correctly.
Do not place tokens, database passwords or private JWKs in CLI arguments or image
build arguments. Inject them through the platform's secret environment mechanism.
The container runs as a non-root user. The database must not be publicly exposed.
### OAuth configuration
Discovery is served at `/.well-known/oauth-protected-resource/mcp`,
`/.well-known/openid-configuration`, and `/.well-known/oauth-authorization-server`.
Public clients register at `/oauth/register`; only code/refresh grants and HTTPS
or HTTP loopback callbacks (`localhost`, `127.0.0.1`, `[::1]`) are accepted. PKCE S256 is mandatory. Remote client
metadata, remote JWKS and request URI fetching are disabled.
Access tokens last ten minutes. Refresh tokens rotate and have a thirty-day absolute
ceiling. Reusing a refresh token revokes its grant. Revoked grants are checked on
each tool request, including requests using otherwise unexpired tokens. Browser
sessions last one day; login/consent interactions expire after ten minutes.
Cross-origin browser requests are rejected. CLI clients connect directly; browser
inspection clients need a local backend/proxy. CORS is not a substitute for client
registration or access tokens.
### Limits and audit
Default limits are five in-flight MCP requests per account, 120 requests per minute,
and twenty write calls per minute. Dynamic registration is ten requests per IP per
minute; browser sign-in is sixty per minute. These are fixed v1 limits in the
service, covered by tests. Change them through a reviewed release.
Audit rows record time, account ID, grant ID, tool, repository identifier and outcome.
No token, source content, comment body or issue body belongs in logs. Hourly cleanup
removes expired transient state and audit events older than thirty days. Monitoring
can query counts and latency at the reverse proxy; keep request bodies and query
strings out of proxy access logs, especially OAuth callbacks. Alert on readiness
failures, elevated 5xx/401/429 rates and repeated upstream failures. The service emits
generic startup, OAuth failure and cleanup failure diagnostics on stderr.
## Key rotation
Encryption uses AES-256-GCM with a fresh nonce and row-specific authenticated context.
`MCP_ENCRYPTION_KEYS` is an ordered JSON object such as `{"v2":"NEW_KEY","v1":"OLD_KEY"}`.
The first key encrypts new state; retained keys decrypt old state.
For v1, stop the app, back up PostgreSQL and the current keyring separately, add the
new key first, run `rotate-keys`, and restart with that keyring. Verify connection and
refresh tests before removing the old key. Never remove a key still needed to restore
a retained backup. The rotation command re-encrypts state transactionally.
For cookie keys, add the new key first and retain the previous key for at least a
browser-session lifetime. For signing keys, add the new key to the JWK Set, roll it
out, then move it first. Keep previous public validation keys available for the
relevant token lifetime. Do not generate replacement keys automatically at boot.
## Backup, restore and rollback
Back up PostgreSQL using the fleet's approved encrypted backup process. Store
encryption/signing/cookie keys through separate secret backup procedures. A database
without its encryption keys cannot restore usable credentials.
Before each schema-changing release, take a backup and restore it into a disposable
PostgreSQL 18 database. Run migrations and credential-decryption smoke tests there.
Switch traffic only after readiness and OAuth checks pass. Keep the previous image
and pre-migration backup as the rollback pair; do not run destructive down migrations
against a live database. Version 001 is an additive initial schema.
SIGTERM stops accepting new connections and allows up to twenty seconds for shutdown.
Use a container stop timeout of at least twenty-five seconds. Do not log the
contents of the generated test fixture or production environment when troubleshooting.
## Coolify Compose builds
Keep credentials runtime-only. Coolify also interpolates Compose while building;
for the custom build command, supply harmless placeholders without exposing real
keys as build arguments:
```sh
MCP_DB_PASSWORD=build-only MCP_ENCRYPTION_KEYS=build-only POSTGRES_PASSWORD=build-only MCP_ORIGIN=build-only GITZA_CLIENT_ID=build-only GITZA_CLIENT_SECRET=build-only MCP_COOKIE_KEYS=build-only MCP_SIGNING_JWKS=build-only docker compose build --pull
```
Disable Dockerfile ARG injection, configure the actual values as literal runtime
variables, and pin the full Git commit SHA. Verify the generated Compose networks
and use the actual reverse-proxy address for `MCP_TRUST_PROXY`; recheck it if the
network is recreated. Coolify may attach database services to its dedicated
application network as well as the internal database network. Never publish a
database host port.