Skip to main content

Run with Docker Compose

Use Docker Compose for a local CAIPE stack with the UI, Dynamic Agents, MCP servers, a MongoDB-compatible database, RBAC services, and optional RAG/tracing components. MongoDB is the default; DocumentDB is opt-in.

Prerequisites​

  • Docker or Docker Desktop
  • Git
  • An LLM provider key

Configure​

git clone https://github.com/caipe-io/ai-platform-engineering.git
cd ai-platform-engineering
cp .env.example .env

Edit .env with your provider key:

LLM_PROVIDER=openai
OPENAI_API_KEY=<token>

The checked-in example starts the default OSS stack:

COMPOSE_PROFILES=mcp-servers,caipe-ui-prod,rbac,dynamic-agents,rag,caipe-mongodb,web_ingestor

mcp-servers starts the packaged MCP server containers. Add credentials only for the MCP servers you plan to use, for example:

GITHUB_PERSONAL_ACCESS_TOKEN=<token>
ARGOCD_TOKEN=<token>
ARGOCD_API_URL=https://argocd.example.com

For full provider details see Configure LLMs. For service credentials see Configure Agent Secrets.

Seed application resources​

Compose mounts config/app-config.yaml into the UI. To keep local settings out of Git:

cp config/app-config.yaml config/app-config.local.yaml

Set the override in .env:

CAIPE_APP_CONFIG_FILE=./config/app-config.local.yaml

The file can seed models, MCP servers, agents, workflows, and RAG datasources. For example:

rag_sources:
  - source_type: web_url
    url: https://docs.example.com
    name: example-docs
    search_with_teams: [primary]
    settings:
      crawl_mode: sitemap
      max_pages: 500

Seeded datasources are visible but read-only in the UI. search_with_teams controls who can query their content independently from source management. Change the YAML and restart the UI to update or remove them. Connector credentials remain in .env or the deployment secret store.

Start​

docker compose up

Open the UI at http://localhost:3000. The Dynamic Agents API is exposed at http://localhost:8100 and is also proxied through the UI API routes.

To update .env to the latest published CAIPE release before starting Compose:

./setup-caipe.sh update-compose-release

To let the setup helper update .env and start Compose:

./setup-caipe.sh --docker-compose

The setup script asks before using sudo. Use --no-sudo to forbid it or --allow-sudo to permit it without a consent prompt. See sudo consent for automation and fallback behavior.

Choose the MIT-licensed DocumentDB provider instead:

./setup-caipe.sh --docker-compose --database=documentdb

Profiles​

ProfileDescription
mcp-serversPackaged MCP server containers
caipe-ui-prodProduction CAIPE UI image
caipe-mongodbMongoDB for UI state, Dynamic Agents, RBAC metadata, and checkpoints
caipe-documentdbOpt-in DocumentDB provider for the same MongoDB-compatible state
rbacLocal Keycloak, OpenFGA, AgentGateway, and config bridge
dynamic-agentsDynamic Agents runtime used by chat, skills, and Agent Builder
ragVector RAG services
web_ingestor / web-ingestorWeb datasource ingestion worker
slack-botSlack bot integration service
webex-botWebex bot integration service
tracingLangfuse tracing stack

Examples:

# Default stack from .env
docker compose up

# Render selected services without starting them
docker compose config --services

# Add tracing
docker compose --profile tracing up

# Add graph RAG
docker compose --profile graph_rag up

# Add the web ingestion worker
docker compose --profile web_ingestor up

# Build local images from source
docker compose -f docker-compose.dev.yaml up --build

First-Install RBAC Defaults​

If the first launch reports Keycloak reconciliation errors, failed migrations with OPENFGA_HTTP is not set, or missing Keycloak admin credentials, make sure .env contains the local RBAC defaults:

KEYCLOAK_ADMIN_CLIENT_ID=caipe-platform
KEYCLOAK_ADMIN_CLIENT_SECRET=caipe-platform-dev-secret
OPENFGA_HTTP=http://openfga:8080
OPENFGA_STORE_NAME=caipe-openfga
AUTHZ_SERVICE_URL=http://caipe-ui:3000

Then recreate the services that consume those settings:

COMPOSE_PROFILES="mcp-servers,caipe-ui-prod,rbac,dynamic-agents,rag,caipe-mongodb,web_ingestor" \
docker compose --env-file .env -f docker-compose.yaml up -d --force-recreate caipe-ui dynamic-agents keycloak-init

If Keycloak or OpenFGA were initialized with bad settings, reset only the local auth/RBAC volumes. Keep MongoDB if you want to preserve CAIPE data:

docker compose --env-file .env -f docker-compose.yaml down
docker volume ls | grep -E 'keycloak_postgres_data|openfga_postgres_data'
docker volume rm <keycloak_postgres_data_volume> <openfga_postgres_data_volume>
docker compose --env-file .env -f docker-compose.yaml up -d

Tracing​

The tracing profile starts Langfuse v3.

docker compose --profile tracing up

Open Langfuse at http://localhost:3001, create an account, copy the keys, then add them to .env:

ENABLE_TRACING=true
LANGFUSE_PUBLIC_KEY=<public-key>
LANGFUSE_SECRET_KEY=<secret-key>
LANGFUSE_HOST=http://langfuse-web:3000

Restart the stack after changing tracing settings.

Next Steps​