Developer Quickstart & Local Setup
Running the monorepo locally with Docker, PostgreSQL Vector Database, and Redis.
This guide will help you set up and run the complete KHOLO monorepo on your local development machine in under 5 minutes.
1. System Prerequisites
Ensure you have the following installed on your machine:
- Node.js: $\ge 22.0.0$ (
node -v) - npm: $\ge 10.0.0$ (
npm -v) - Docker & Docker Compose: For PostgreSQL (with
Vector Database) and Redis 7.
2. Monorepo Structure
3. Step-by-Step Installation
Step 1: Install Dependencies
From the repository root, install dependencies for all workspaces:
npm installStep 2: Start Infrastructure (PostgreSQL & Redis)
Start PostgreSQL on port 5433 (to prevent conflicts with any local Postgres) and Redis on port 6380:
npm run db:upVerify containers are running:
docker psStep 3: Configure Environment Variables
Copy the example environment files:
# In apps/api
cp apps/api/.env.example apps/api/.env
# In apps/web
cp apps/web/.env.example apps/web/.env.localEdit apps/api/.env if you wish to use live Google Gemini or OpenAI keys:
# AI Provider Setup (Optional: defaults to local heuristic parser if left empty)
PRIMARY_AI_PROVIDER="gemini"
GEMINI_API_KEY="your_gemini_api_key_here"
OPENAI_API_KEY="your_openai_api_key_here"Step 4: Run Migrations & Seed the Database
Initialize the Prisma client, apply schema migrations, and seed sample South African FMCG products and customer accounts:
# Generate Prisma Client and apply schema
cd apps/api
npx prisma generate
npx prisma db push
# Seed 15 core SA wholesale products and test accounts
cd ../..
npm run db:seed4. Starting Development Servers
Open two or three terminal tabs:
Terminal 1: Backend API (Port 3001)
npm run dev:apiHealth check: curl http://localhost:XXXX/api/health $\rightarrow$ {"status":"ok"}.
Terminal 2: Web Control Centre (Port 3000)
npm run dev:webAccess the Clerk Control Centre at http://localhost:XXXX.
Terminal 3 (Optional): Super Admin Portal (Port 3002)
npm run dev:adminAccess the Fleet & Platform Management portal at http://localhost:XXXX.
5. Helpful Workspace Scripts
| Command | Action |
|---|---|
npm run db:up | Starts local PostgreSQL and Redis containers in the background. |
npm run db:down | Stops and removes local database containers. |
npm run db:seed | Seeds 15 South African FMCG products, prices, and customer accounts. |
npm run test:sim | Executes customer trade jargon simulation test in terminal. |
npm test --workspace=apps/api | Runs automated security, route, and pilot feature unit tests. |