Getting Started

Audience: A new contributor setting up a clone
Basis: Read from README.md, CONTRIBUTING.md, scripts/dev-up.sh, scripts/run-core-local.sh, .devcontainer/. Commands are quoted from those files.
Next: Build, Test & Verify · Repository Map · Local Development Setup

Local URLs are labelled local

The localhost addresses on this page are the local-development exception. Never use localhost/127.0.0.1 in any browser-facing or token-issuer URL of a deployed environment, and never reuse a local deploy/compose/.env for a deployment.

1. Prerequisites

Tool	Version	Used by
JDK	21 is the compile target (`java.version` in `core/pom.xml`); `CONTRIBUTING.md` says maintainers build with 24.	`core/`
Maven	3.9+	`core/` (Spring Boot parent 3.4.4)
Node.js	20 or 22 (`CONTRIBUTING.md`; README says 20+)	`web/`, `web-admin/`
Python	3.11+ in `CONTRIBUTING.md`; README says 3.12+	`services/sidecar/`, `services/code-intel/`
Docker + Compose	recent	full stack in `deploy/`
gitleaks	8.18+	secret scan in the pre-push hook

2. Fastest paths

Devcontainer / Codespaces — .devcontainer/ (devcontainer.json, post-create.sh): installs git hooks, runs scripts/dev-up.sh (generates deploy/compose/.env, starts Postgres, Valkey and Keycloak) and warms npm ci + mvn compile.
Just run it — scripts/vegaduta up --lite (add --build to build from source), or install.sh, which downloads the latest release tarball and runs the same command (docs/getting-started.md).
scripts/dev-up.sh (Linux/macOS/WSL/Git Bash; scripts/vegaduta.ps1 is the Windows-native helper).

bash scripts/dev-up.sh            # infra only: postgres, valkey, keycloak (lite compose)
bash scripts/dev-up.sh --app      # the Lite stack built from source
bash scripts/dev-up.sh --all      # Full stack + main profiles, from source (heavy)
bash scripts/dev-up.sh --env-only # just write deploy/compose/.env

3. Manual bring-up

scripts/vegaduta secrets      # writes deploy/compose/.env with random secrets (never overwrites)
docker compose -f deploy/compose/lite.yml -f deploy/compose/lite.build.yml --env-file deploy/compose/.env up -d --build --wait

The compose files refuse to start without the required secrets (${...:?}), including APP_ENCRYPTION_KEY and KEYCLOAK_CLIENT_SECRET; scripts/vegaduta secrets generates them. Run the realm reconcile afterwards (deploy/keycloak/reconcile-keycloak.sh; scripts/vegaduta up does it for you).

APP_ENCRYPTION_KEY

Must be identical everywhere core boots (deploy/compose/.env, a locally run core, your Kubernetes Secret). A different key makes every stored provider key and channel secret undecryptable. This page deliberately lists names only, never values.

4. One service at a time

bash scripts/dev-up.sh                          # postgres, valkey, keycloak

cd core && mvn -pl app -am spring-boot:run     # or: ./scripts/run-core-local.sh
cd web && npm ci && npm run dev               # web (port 3000)
cd web-admin && npm ci && npm run dev         # web-admin (port 3001)
cd services/sidecar && uvicorn app.main:app --reload --port 8001
cd services/code-intel && pip install -r requirements.txt && CODE_INTEL_AUTH_MODE=none uvicorn app.main:app --port 8090

Spring Boot does not read .env files; a bare mvn spring-boot:run dies on a missing APP_ENCRYPTION_KEY. Export the values listed in the header of scripts/dev-up.sh first. scripts/run-core-local.sh does the export for you but reads deploy/.env, not deploy/compose/.env, and runs Maven offline (-o), so it needs a populated local cache.

5. Local ports (local only)

core 8080, web 3000, web-admin 3001, sidecar 8001, code-intel 8090, Keycloak 8180, Postgres 5432, Valkey 6379, SeaweedFS S3 8333, Temporal UI 8088, Langfuse 3002, Grafana 3003. The full matrix is on Ports & Service Matrix.

6. First-day checklist

Read CONTRIBUTING.md (short) — licensing and DCO sign-off, how changes get in, the checks. See Conventions & Standards.
Install the git hooks once: bash scripts/dev/install-git-hooks.sh (see Git & Contribution Workflow).
Find the folder you will work in on the Repository Map.
Run the merge gate locally before pushing — Build, Test & Verify.

7. Known traps at setup time

Never bake localhost into a deployed web image. The consoles read NEXT_PUBLIC_* at runtime; a value passed at build time becomes a baked fallback. Leave the build args empty for images you deploy (ADR-0007).
Do not run npm install while other processes run npx in the same project — the two race and roll back.
One Maven build at a time; parallel builds in one checkout fight over target/ (CONTRIBUTING.md).
If a build hits a real dependency or compile error, fix the cause rather than routing around it with --force or --legacy-peer-deps (README §2).
The Next.js version in web/ has breaking changes relative to older releases; read the guide bundled in node_modules/next/dist/docs/ before writing code.

Evidence & references

README.md §2 Running it locally, §3 Testing.
CONTRIBUTING.md — Local setup table and steps.
scripts/dev-up.sh, scripts/run-core-local.sh (headers), .devcontainer/.
core/pom.xml — java.version 21, Spring Boot parent 3.4.4.
services/code-intel/README.md (uvicorn line).