Installation ~15 min

Requirements

Tool	Version	Purpose
Bun	≥ 1.0	Runtime and package manager
Docker + Compose	≥ 20.10	PostgreSQL, Redis, Keycloak, MinIO

---

Infrastructure

Start all (recommended)

./scripts/start-infrastructure.sh

Docker Compose directly

cd shell
docker compose up -d

Default service ports:

Service	Port
PostgreSQL	5433
Redis	6380
Keycloak	8080
MinIO	9000 / 9001 (console)

---

Shell API

1. Install dependencies

cd shell/api
bun install

2. Create .env

# shell/api/.env  — minimum for local dev
APP_ENV_DATABASE_URL=postgresql://shell:shell@localhost:5433/shell_db
APP_ENV_JWT_SECRET=change-me-at-least-32-chars-for-local-dev

# Keycloak — set both to same value locally
APP_ENV_KEYCLOAK_URL=http://localhost:8080
APP_ENV_KEYCLOAK_INTERNAL_URL=http://localhost:8080
APP_ENV_KEYCLOAK_REALM=veni-ai
APP_ENV_KEYCLOAK_CLIENT_ID=veni-ai-platform
APP_ENV_KEYCLOAK_REDIRECT_URI=http://localhost:3000/api/auth/callback

# Redis (no password locally)
APP_ENV_REDIS_URL=redis://localhost:6380

Never commit .env to git

All .env files are in .gitignore. Use infrastructure/k8s/overlays/dev/secrets.env for K8s (also gitignored).

3. Run migrations

bun run db:migrate

Safe to re-run — Drizzle migrations are idempotent. Migration files live in shell/api/database/migrations/.

4. Start

Development (watch)

bun run dev

Production

bun run build   # tsc && tsc-alias → dist/index.js
bun run start   # bun dist/index.js

Verify: curl http://localhost:3000/api/health

---

Shell UI

1. Install

cd shell/ui
bun install

2. Create .env.local

# shell/ui/.env.local
VITE_API_URL=http://localhost:3000/api

3. Start

bun run dev    # → http://localhost:5173

---

Scripts reference

Shell API

Script	What it runs
bun run dev	tsc && bun src/index.ts
bun run build	tsc && tsc-alias → dist/index.js
bun run start	bun dist/index.js
bun run db:migrate	drizzle-kit migrate
bun run db:studio	drizzle-kit studio (local DB UI)

Shell UI

Script	What it runs
bun run dev	Vite dev server → :5173
bun run build	tsc && vite build
bun run test	vitest
bun run test:coverage	vitest --coverage