Deployment

Docker Stack

The repository root provides a docker-compose.yml that starts all services:

# Recommended ordered startup
./kavach.sh

# Direct Compose operation
docker compose up --build

# Stop while preserving volumes
./scripts/docker/docker-down.sh

# Reset containers and local data
./scripts/docker/docker-reset.sh

Repository layout

Root entrypoints remain short and operational helpers are grouped under scripts/:

kavach.sh                         Docker startup orchestrator
kavach-local.sh                   Local API + MCPO orchestrator
scripts/build/                    Build metadata generation
scripts/docker/                   Compose up, down, and reset
scripts/keycloak/                 Keycloak readiness and MCP actor discovery
scripts/mcp/                      MCPO startup
keycloak-postgres/                Keycloak and PostgreSQL configuration
console/                           Kavach Studio

Deployment Steps

1. Install Docker, Docker Compose, uv, Node.js, and pnpm.
2. Review the environment files and keep secrets out of source control.
3. Ensure Keycloak credentials and the kavach-mcp client secret match the imported realm.
4. Run ./kavach.sh; it starts Keycloak, discovers the MCP actor, generates build metadata, validates Compose, and starts the stack.
5. Open Studio at http://localhost:3000, sign in, and assign tenant roles under Organization → Access.
6. Verify REST at http://localhost:8000/ready and MCPO at http://localhost:8001/docs.

Services

The Compose stack starts the following services:

• keycloak and keycloak-postgres — local OIDC identity provider and its database.
• kavach-platform — REST API on port 8000. Built from Dockerfile.platform using the Astral UV image for Python 3.12. Runs Uvicorn with uvicorn kavach.api.app:app.
• kavach-replay-worker — dedicated durable-job worker. It consumes replay execution and replay evaluation jobs, along with asynchronous evaluation and experiment jobs, and shares the SQLite volume with the API.
• kavach-studio — Next.js governance console on port 3000. Built from console/Dockerfile.studio using a multi-stage Alpine build.
• neo4j — Graph database on bolt://7687 and HTTP port 7474. Uses Neo4j 5.26.27-community with default credentials neo4j/kavach-local-password.
• kavach-mcp — MCPO OpenAPI proxy on port 8001, backed by the stdio MCP server.

Local Developer Mode

Local mode runs the Python API and Studio outside Docker while retaining Keycloak and Neo4j as infrastructure services. From the Kavach repository root, use the managed startup command rather than invoking Uvicorn alone:

./kavach-local.sh

# Start Studio separately when needed
cd console && pnpm dev

This loads .env.local, starts Keycloak, discovers the MCP service-account actor, starts MCPO, and launches the API. Running Uvicorn directly requires exporting the same environment first; files such as.env.platform are not loaded automatically by Uvicorn. The local orchestrator writes the discovered actor to .env.mcp.generated and starts the API with Uvicorn.

Environment Configuration

The platform service reads from two env files: .env.platform (runtime configuration) and .env.build (auto-generated build metadata). Key settings:

# .env.platform (runtime config)
KAVACH_ENV=local
KAVACH_AUTO_SEED_DEMO_DATA=true
KAVACH_GRAPH_URI=bolt://neo4j:7687
KAVACH_GRAPH_USER=neo4j
KAVACH_GRAPH_PASSWORD=kavach-local-password

# Multi-tenant / RBAC
KAVACH_TENANCY_ENABLED=true
KAVACH_AUTH_MODE=keycloak
KAVACH_KEYCLOAK_URL=http://keycloak.localhost:8080
KAVACH_KEYCLOAK_REALM=kavach

# Studio and MCP
NEXT_PUBLIC_KEYCLOAK_URL=http://keycloak.localhost:8080
KAVACH_MCP_CLIENT_ID=kavach-mcp
KAVACH_MCP_CLIENT_SECRET=...
KAVACH_MCP_API_URL=http://kavach-platform:8000

# Repository backends (all sqlite for local)
KAVACH_EVALUATION_REPOSITORY=sqlite
KAVACH_JOB_REPOSITORY=sqlite
KAVACH_POLICY_REPOSITORY=sqlite

# Replay API and worker must share these durable stores
KAVACH_REPLAY_REPOSITORY=sqlite
KAVACH_REPLAY_SQLITE_PATH=/var/lib/kavach/kavach.db
KAVACH_REPLAY_EXECUTION_CATALOG_BACKEND=sqlite
KAVACH_REPLAY_EXECUTION_CATALOG_SQLITE_PATH=/var/lib/kavach/kavach.db
KAVACH_REPLAY_EVALUATION_PROVIDER=mock

Local mode uses .env.local. Docker uses .env.platform plus generated files such as .env.build and .env.mcp.generated. Keep secrets out of source control and regenerate derived files when the Keycloak realm or service client changes.

Keycloak & MCP startup

Keycloak is startup infrastructure, not the source of runtime actor identity. The bootstrap administrator provisions the initial organization and project once. The MCP startup flow then resolves the kavach-mcp client service-account ID and writes it to .env.mcp.generated. The MCP server obtains and refreshes a short-lived client-credentials token at runtime.

Studio Image

Studio uses a multi-stage build: dependencies installation, Next.js standalone build, and a minimal Alpine runner. The API base URL is passed as a build argument:

docker build \
  --build-arg NEXT_PUBLIC_KAVACH_API_BASE_URL=http://localhost:8000 \
  -f console/Dockerfile.studio \
  -t kavach-studio ./console

Build Metadata

The repository includes a build metadata script that generates .env.build with commit SHA, build date, and dirty status:

./scripts/build/generate-build-metadata.sh
# Generates .env.build with:
# KAVACH_COMMIT_SHA, KAVACH_COMMIT_SHA_FULL
# KAVACH_BUILD_DATE, KAVACH_BUILD_DIRTY

These values are exposed through the Settings Control Plane as system.version, system.commit_sha, and system.build_date.

Scaling

The API and worker services are stateless and can each be scaled independently. All durable state lives in PostgreSQL, Neo4j and the audit store. Workers pull from the job queue, so throughput grows linearly with the worker count until a datastore becomes the bottleneck.

Upgrades

Schema migrations are forward-compatible and run before new service versions roll out. Combined with stateless services, this enables rolling upgrades with no downtime.