Run the Navin Platform for local development with make

This page runs the platform on a development machine without Docker: make install prepares the venv of the Control Plane, the portal dependencies and Keycloak; make start starts PostgreSQL, Redis and Keycloak when they do not answer yet, applies the migrations, then starts the API (python -m eai.main, port 8080), the worker (python -m eai.worker) and the portal (port 3300). It is meant for developers of the platform.

Before you begin

• Python 3.11 or newer, Node.js 20 or newer, redis-server on the PATH, the PostgreSQL binaries (or a PostgreSQL that already answers on EAI_DATABASE_URL), and Java 21 for Keycloak.
• The repository cloned, commands run from its root.
• make help lists the targets, in French with EAI_LOCALE=fr.

Steps

1. Create the settings. make docker-env writes services/control-plane/local.env (and deploy/compose/.env) with random local secrets and free ports. An existing file is kept.

   make docker-env

   Expected result: services/control-plane/local.env exists.

2. Install the components.

   make install

   It creates services/control-plane/.venv with the extras of EXTRAS (default dev), runs npm install in portal/ (INSTALL_PORTAL=0 skips it) and puts Keycloak 26.8.1 in ~/.local/toolchains (INSTALL_KEYCLOAK=0 skips it).

   Expected result: services/control-plane/.venv/bin/python -c "import eai" succeeds.

   If it fails: the Python or Node.js version is too old; check python3 --version and node --version.

3. Start the platform.

   make start
   make status

   Expected result: make status lists postgres, redis, keycloak, api, worker and portal as running.

   If it fails: make logs (or make logs COMPONENTS=api) shows the logs; MIGRATE=0 starts without the migrations, DB_WAIT (default 30 seconds) is the wait for a database that refuses connections.

4. Sign in. Open http://localhost:3300/login, tab Login: navin / navin (EAI_BOOTSTRAP_ADMIN_USERNAME and EAI_BOOTSTRAP_ADMIN_PASSWORD of local.env). The account has the roles platform_admin and tenant_admin on the tenant default; the portal asks for a new password at the first sign in. The Sign in with SSO button uses the Keycloak started by make start (console http://localhost:8081/admin, user admin, password KEYCLOAK_ADMIN_PASSWORD of deploy/compose/.env).

Variables of the make targets

Variable	Effect
COMPONENTS	Components to act on: postgres redis keycloak api worker media-worker portal
ENV_FILE	Settings file (default services/control-plane/local.env)
PORT, EAI_HOST	API port (default EAI_PORT, else 8080) and bind address (default 127.0.0.1)
PORTAL_PORT, PORTAL_HOST	Portal port (default 3300) and bind address (default 127.0.0.1)
PORTAL_BUILD	1 builds the portal again, 0 never builds
PG_DATA, PG_BIN	Data folder (default .run/postgres) and binaries of the local PostgreSQL
REDIS_SERVER	redis-server binary
KEYCLOAK_HOME	Keycloak release (default ~/.local/toolchains/keycloak-26.8.1)
VENV, PYTHON	Virtual environment and interpreter
EXTRAS	Extras of make install (dev; empty for the runtime only; litellm, otel, workers)
MIGRATE, DB_WAIT	Start without migrations; wait for the database
LOG_LINES, FOLLOW	Lines shown by make logs, without following them with FOLLOW=0
START_TIMEOUT, STOP_TIMEOUT, WORKER_ARGS, MEDIA_WORKER_ARGS, RUN_DIR	Timeouts, arguments, pid and log folder (default .run)

The portal can also run in development mode: cd portal && npm run dev (http://localhost:3300, folder .next-dev); stop the portal of make start first.

Stop

make stop

It stops what make start started; a PostgreSQL or Redis that was already running is left as it was.

Next steps

• Docker Compose for the other services (OpenFGA, OPA, Qdrant, NATS, Temporal, observability)
• Local start guide: sign in with Keycloak and LDAP, install a service from the portal with the Navin Manager sandbox

Troubleshooting

Symptom	Cause	Fix
make start waits then fails on the database	PostgreSQL refuses the connection	Check EAI_DATABASE_URL of local.env; raise DB_WAIT
Portal pages return 404 for scripts after a build	Old file names cached by the browser	Reload with Ctrl-F5
Keycloak does not start	No Java 21, or KEYCLOAK_HOME wrong	Install Java 21; run make install again