Arrakis Spice — Dev Quickstart

A simple guide to clone, set up, and run the app locally.

Prerequisites

• Node.js 18+ and pnpm 8+ (npm i -g pnpm)
• Docker and Docker Compose (Ensure that it's installed and running)

1) Clone

• GitHub or your fork:
  • git clone https://github.com/Kashyab19/arrakis-spice
  • cd arrakis-spice

2) Create .env (repo root)

Copy and paste this minimal config into a new file named .env in the repo root:

# API
API_PORT=3001
API_HOST=0.0.0.0
CORS_ORIGIN=http://localhost:5173

# Database & Cache (match docker-compose)
DATABASE_URL=postgresql://postgres:spice123@localhost:5432/arrakis_spice?schema=public
REDIS_URL=redis://localhost:6379

# external services (safe to leave empty for local dev)
OPENAI_API_KEY=
SERPER_API_KEY=
LLM_MODEL=gpt-4o-mini
WORKER_CONCURRENCY=2

3) Install dependencies

# Navigate to scripts folder. You will run into permission issues, so don't forget to
chmod +x ./setup.sh
./setup.sh

4) Start the app (API, Worker, Web)

# start everything including infra in one command
pnpm run dev:all

# To start individual services, navigate to each folder and:
pnpm run dev

5) Open the app

• Web: http://localhost:5173
• API: http://localhost:3001/api
• Health check: http://localhost:3001/api/health/detailed

6) Common scripts

• Start infra: pnpm run dev:services
• Start dev (API+WORKER+WEB): pnpm run dev
• Start all (infra + dev): pnpm run dev:all
• Build all: pnpm run build
• Stop infra: pnpm run stop
• Docker logs: pnpm run logs
• Docker status: pnpm run status
• Prisma Studio: pnpm run prisma:studio

7) Notes

• The web app calls the API at /api. In development, access the web app at http://localhost:5173 and the API at http://localhost:3001.
• If you change ports/origins, update CORS_ORIGIN in .env to match the web origin.
• If you run into DB issues, try:
  • pnpm run stop (stop containers)
  • pnpm run clean (stop and remove volumes) — this will wipe local DB data
  • pnpm run dev:services then re-run migrations

8) Project structure

packages/
├─ api/      # Fastify REST API
├─ worker/   # Background job processors
├─ web/      # React + Vite frontend
└─ shared/   # Prisma, types, utilities shared across packages

Architecture