Run the Navin Platform with Docker Compose

This page starts the whole stack of deploy/compose/docker-compose.yml on one workstation: Control Plane API, worker, portal, PostgreSQL, Redis, LiteLLM, Keycloak, OpenFGA, OPA, OpenBao, Qdrant, NATS, Temporal, LiveKit, ClickHouse, OpenSearch, Jaeger, the OpenTelemetry Collector, Prometheus, Alertmanager and SeaweedFS. It is meant for developers and demonstrations. Count thirty minutes, most of it for pulling the images.

warning

This stack is not for production: OpenBao runs in development mode and Keycloak in start-dev.

Before you begin

• Docker Engine with the compose v2 plugin: docker compose version.
• Resources: see Sizing.
• Optional: an NVIDIA GPU and the NVIDIA container toolkit for the gpu profile (vLLM, media worker).
• The ports of Network ports free on the host.

Steps

1. Create the settings file. make docker-env copies deploy/compose/.env.example to deploy/compose/.env with random local secrets and free host ports, and writes services/control-plane/local.env for a Control Plane started on the host. An existing file is kept.

   make docker-env

   Without make: cp deploy/compose/.env.example deploy/compose/.env, then replace every CHANGE_ME_ value (openssl rand -hex 32).

   Expected result: deploy/compose/.env exists and holds no CHANGE_ME_.

2. Check Docker and the compose file.

   make docker-check
   docker compose -f deploy/compose/docker-compose.yml --env-file deploy/compose/.env config -q

   Expected result: no output from config -q.

   If it fails: the message names the missing variable of .env, or the Docker daemon that does not answer.

3. Build and pull the images, create the containers.

   make docker-install

   Expected result: the images control-plane and portal are built (worker too with the gpu profile), the others pulled.

4. Start the stack. The one-shot services run first: migrate (python -m eai.migrate), openfga-migrate, opensearch-init and seaweedfs-init (buckets eai-audit-worm with object lock in COMPLIANCE mode, eai-artifacts and opik). Keycloak imports the realm enterprise-ai from deploy/keycloak/realm-enterprise-ai.json; OPA loads the bundle deploy/policies/opa.

   make docker-start
   make docker-status

   Optional profiles: make docker-start PROFILES="gpu ollama" adds vLLM, the media worker and Ollama; PROFILES=opik adds Opik (it needs a MySQL 8.4 server installed separately, OPIK_STATE_DB_URL and OPIK_STATE_DB_PASSWORD in .env).

   Expected result: make docker-status shows the long running services running (healthy when they have a healthcheck) and the one-shot services exited (0).

   If it fails: make <service>-logs (for example make control-plane-logs). PostgreSQL keeps the password of its first start in its volume: after a new .env, run make docker-clean (removes the volumes) then start again.

5. Load the OpenFGA model.

   fga store create --name enterprise-ai --api-url http://localhost:8082
   fga model write --store-id <store-id> --file deploy/policies/openfga/model.fga
   python3 tools/policies/fga_build.py --check

   <store-id>: id printed by fga store create.

   Expected result: the model tests pass.

Verify

curl -fsS http://localhost:8080/readyz

Expected output: "status": "ready". Then open http://localhost:3300, tab Login, with EAI_BOOTSTRAP_ADMIN_USERNAME and EAI_BOOTSTRAP_ADMIN_PASSWORD of .env (navin / navin by default): the portal asks for a new password at the first sign in.

Service	URL
Control Plane API	http://localhost:8080/v1
Portal	http://localhost:3300
LiteLLM	http://localhost:4000
Keycloak (realm enterprise-ai)	http://localhost:8081
OpenFGA	http://localhost:8082
OpenBao (dev)	http://localhost:8200
Temporal UI	http://localhost:8088
Opik (profile opik)	http://localhost:3001
Jaeger	http://localhost:16686
Prometheus	http://localhost:9090
SeaweedFS S3 API	http://localhost:8333

With EAI_AUTH_DEV=1 the API accepts the headers X-Dev-Tenant, X-Dev-User and X-Dev-Roles; set it to 0 to require Keycloak tokens.

Stop and clean

Command	Effect
make docker-stop	Stops the containers
make docker-down	Removes the containers, keeps the volumes
make docker-clean	Removes the containers and the volumes: databases, queues and object storage start empty

Next steps

• Local development to run the API and the portal on the host next to these services
• First configuration

Troubleshooting

Symptom	Cause	Fix
password authentication failed in the migrate logs	.env changed after the first start	make docker-clean, then make docker-start
A port is already allocated	Another program uses it	make docker-env picks the next free port for the infrastructure ports; for the others stop the program
vLLM does not start	No GPU or no NVIDIA container toolkit	Start without the gpu profile, or use PROFILES=ollama
Opik does not start	No MySQL state database	Set OPIK_STATE_DB_URL and OPIK_STATE_DB_PASSWORD