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,autonomous-agents
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.
External Apps are enabled by default with an empty deployment-owned catalog.
Add packages and installations to config/agentic-apps.yaml, or point
AGENTIC_APPS_CONFIG_FILE at another catalog file, then restart the UI.
Schedules run in Docker Compose through the local scheduler backend
(SCHEDULER_BACKEND=local, part of the dynamic-agents profile). Kubernetes
installs use the chart's CronJob backend. The installer enables the scheduler
and External Apps by default; use ENABLE_SCHEDULER=false or --no-apps to opt out.
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.
First-time setup wizard
On a new deployment, the setup wizard checks the runtime and walks an admin through a first working agent:
- Select or add an LLM model and verify provider access.
- Choose a starter recipe.
- Connect optional user credentials such as GitHub or Notion. OAuth connectors must be configured by the operator before they appear.
- Add a remote MCP server from the catalog, or configure a custom endpoint, then select the server for the starter agent.
- Optionally enable a knowledge base and platform capabilities.
- Create the agent and run the end-to-end smoke test.
The wizard never stores OAuth tokens in its setup state. Connections remain in the credential service and can be relinked from Credentials → Connected Apps. The current catalog uses operator-configured OAuth connectors; arbitrary custom endpoints still require their authentication to be configured in the MCP editor. Generic dynamic client registration (DCR) is not yet assumed for custom endpoints.
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
| Profile | Description |
|---|---|
mcp-servers | Packaged MCP server containers |
caipe-ui-prod | Production CAIPE UI image |
caipe-mongodb | MongoDB for UI state, Dynamic Agents, RBAC metadata, and checkpoints |
caipe-documentdb | Opt-in DocumentDB provider for the same MongoDB-compatible state |
rbac | Local Keycloak, OpenFGA, AgentGateway, and config bridge |
dynamic-agents | Dynamic Agents runtime used by chat, skills, and Agent Builder |
rag | Vector RAG services |
web_ingestor / web-ingestor | Web datasource ingestion worker |
slack-bot | Slack bot integration service |
webex-bot | Webex bot integration service |
tracing | Langfuse 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 (set LANGFUSE_PORT in .env to change
the host port), 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.