Local Setup

Prerequisites

• Node.js 24.x (see .node-version; engines enforces it)
• npm (repo uses package-lock.json — do not use pnpm/yarn)
• PostgreSQL 15+ with pgvector (local Postgres or a managed fork)
• Redis (optional for dev; required for queues/rate limits)

Install and run

git clone <repo-url> && cd casesolo
npm install
cp .env.example .env   # then fill in values below
npx prisma generate
npx prisma migrate dev # or prisma migrate deploy against an existing DB
npm run dev

Seed demo data only when needed: npm run db:seed.

Required env vars (dev minimum)

Full list with explanations: .env.example.

| Var | Purpose | |---|---| | DATABASE_URL | Pooled Postgres connection (Prisma via adapter-pg) | | DIRECT_URL | Non-pooled connection for prisma migrate deploy | | JWT_SECRET | ≥ 32 chars; signs access/refresh tokens | | USERMAILS_API_KEY, MAIL_FROM_EMAIL | Email sending identity | | REDIS_URL | Queues, cache, rate limits (else degraded) | | NEXT_PUBLIC_APP_URL | Emails, redirects, OAuth callbacks |

Storage (S3_* or R2_*), Stripe, Twilio, Sentry, and AI provider keys are only needed for the features that use them — the app boots without them.

Verify the setup

npm run typecheck             # next typegen + tsc
npm run lint
npm run test:run              # Vitest unit + route tests
npm run self-hosted:standalone-check  # after npm run build

npm run doctor diagnoses common environment problems. npm run verify:launch is for controlled launch-verification environments only — it can create records against the configured database (dry-run with -- --dry-run --json).

Common problems

| Symptom | Fix | |---|---| | prisma migrate dev fails on pgvector | Enable the vector extension on your Postgres | | Workers/queues silent | Set REDIS_URL; BullMQ workers boot from instrumentation-node.ts only when CASESOLO_ENABLE_BULLMQ_WORKERS=true | | Node version errors in verify:launch | It auto-re-execs under Node 24 (nvm/Homebrew/Volta); override only via documented env vars in testing |