8.7 KiB
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:
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.
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:
- Provision a dedicated PostgreSQL 18 database and a non-superuser application role.
- 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. - Set the configuration documented in
.env.example.MCP_ORIGINandGITZA_URLare HTTPS origins, without paths. No URL or host is supplied by a tool caller. - 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.
- Build the image from the repository root with
docker build -f Dockerfile -t gitza-mcp:0.1.0 .. - Run the image with command
migrateas a separate release step. The web process checks the schema and never runs migrations automatically. - Start with command
http,HOST=0.0.0.0, and port 3400 behind TLS. SetMCP_TRUST_PROXYonly to the exact proxy addresses/CIDRs, not a blanket trust flag. - 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:
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.