156 lines
8.7 KiB
Markdown
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.
|