Docs/Deployment/Local Development Setup

Local Development Setup

How to run the platform on a developer machine: a small infrastructure subset (Postgres, Valkey, Keycloak) in Docker, plus core, web and web-admin as hot-reloading processes. This is the one place in the docs where localhost URLs are correct — they are local-development values only and must never be reused for a deployment.

Prerequisites
Docker with Compose v2; JDK 21 and Maven 3.9+ (core); Node.js 22 (web, web-admin; CI uses Node 22); Python 3.12 for the Python services
Maven rule
Run one Maven build at a time (concurrent builds share ~/.m2 and target/)
npm rule
Do not run npm install while other processes run npx in the same project (the two race)
Env file
deploy/compose/.env (gitignored), generated by scripts/vegaduta secrets
Local ports
core 8080 · web 3000 · web-admin 3001 · Keycloak 8180 · Postgres 5432 · Valkey 6379 · sidecar 8001 · code-intel 8090

Three ways in

PathWhat you get
Devcontainer / Codespaces.devcontainer/ runs post-create.sh: git hooks, bash scripts/dev-up.sh (infra subset), npm ci in web and web-admin, and mvn -DskipTests compile in core. Forwarded ports: 3000, 3001, 8080, 8001, 8090, 8180, 8088, 8333.
bash scripts/dev-up.shContributor spin-up (Linux, macOS, WSL, Git Bash), a thin wrapper over scripts/vegaduta. Default: writes deploy/compose/.env, builds and starts postgres, valkey, keycloak from lite.yml (loopback only) and runs the realm reconcile. --app: the Lite stack built from source. --all: Full stack with the main profiles, from source (heavy). --env-only: just the .env.
scripts/vegaduta up --lite --buildEverything in containers, built from source; no hot reload.

The normal loop

  1. Start infra. bash scripts/dev-up.sh.
  2. Run core as a process. Spring Boot does not read .env files. Export the same APP_ENCRYPTION_KEY, KEYCLOAK_CLIENT_SECRET, POSTGRES_PASSWORD and VALKEY_PASSWORD (as REDIS_PASSWORD) that deploy/compose/.env holds, with SPRING_PROFILES_ACTIVE=security,knowledge,graph-memory,lite, then cd core && mvn -pl app -am spring-boot:run (header of scripts/dev-up.sh). scripts/run-core-local.sh automates the export but reads deploy/.env; point it at your env file or copy the values.
  3. Run the frontends. cd web && npm ci && npm run dev serves on 3000; cd web-admin && npm ci && npm run dev on 3001.
  4. Optional services. sidecar: uvicorn app.main:app --reload --port 8001 in services/sidecar/; code-intel: see services/code-intel/README.md.
  5. Stop. scripts/vegaduta down (keeps data).

Testing before you push

make test          # core, web, web-admin, Python services
make lint
make gates         # the static gates CI runs
cd core && mvn clean verify
cd web && npm run lint && npm run typecheck && npm test

Traps that recur locally

TrapDetail
APP_ENCRYPTION_KEY mismatchMust be identical everywhere core boots. If a process-run core and the container stack share one database with different keys, existing encrypted rows become undecryptable.
Issuer mismatchLocally the issuer is http://localhost:8180/realms/agentic-ai; core must accept the issuer Keycloak stamps (ADR-0005).
Baked NEXT_PUBLIC_*A value set at next build time is used whenever the runtime environment does not set one; never build an image you will deploy with localhost values (ADR-0007). npm run dev is unaffected.
Keycloak realm import runs once--import-realm only imports a realm that does not exist; later edits to deploy/keycloak/agentic-ai-realm.json need a live update or a fresh volume — see Keycloak Provisioning.
Dirty working treeUse a clean worktree (git worktree add --detach) for images you will deploy; uncommitted edits and stray .env*.local files otherwise get baked in.

Related: Getting Started · Build, Test & Verify · Environment Variable Reference · Deployment Guide

Evidence & references