Skip to main content

Local Development Setup

This guide will help you set up CivStart for local development.

Prerequisites​

  • Node.js: 20.x or higher
  • pnpm: 9.12.0 or higher
  • Docker: For local PostgreSQL and Redis
  • Git: For version control

Initial Setup​

1. Clone the Repository​

git clone https://github.com/SuperAppsLLC/CivStart.git
cd CivStart

2. Install Dependencies​

pnpm install

3. Environment Configuration​

Create .env.local files for each application:

Backend (apps/backend/.env.local)​

# Database
DATABASE_URL="postgresql://civstart:password@localhost:5432/civstart_dev"

# Redis
REDIS_URL="redis://localhost:6379"

# Clerk
CLERK_SECRET_KEY="your_clerk_secret_key"
CLERK_PUBLISHABLE_KEY="your_clerk_publishable_key"

# AI/ML
GOOGLE_GEMINI_API_KEY="your_gemini_api_key"
PINECONE_API_KEY="your_pinecone_api_key"

# URLs
FRONTEND_URL="http://localhost:3000"
BACKEND_URL="http://localhost:3001"

Frontend (apps/frontend/.env.local)​

NEXT_PUBLIC_API_URL="http://localhost:3001"
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your_clerk_publishable_key"
CLERK_SECRET_KEY="your_clerk_secret_key"

Admin (apps/admin/.env.local)​

NEXT_PUBLIC_API_URL="http://localhost:3001"
NEXT_PUBLIC_ADMIN_CLERK_PUBLISHABLE_KEY="your_admin_clerk_publishable_key"
ADMIN_CLERK_SECRET_KEY="your_admin_clerk_secret_key"

4. Start Docker Services​

pnpm docker:up

This starts:

  • PostgreSQL on port 5432
  • Redis on port 6379

5. Run Database Migrations​

pnpm --filter=@repo/database db:migrate:dev

6. Seed the Database (Optional)​

pnpm reset:local

This will:

  • Clear all data
  • Sync from Airtable
  • Create 50 test accounts
  • Generate AI matches

Running the Applications​

Start All Applications​

pnpm dev

This starts:

Start Individual Applications​

# Backend only
pnpm --filter=@civstart/backend dev

# Frontend only
pnpm --filter=@civstart/frontend dev

# Admin only
pnpm --filter=@civstart/admin dev

Available Scripts​

Development​

  • pnpm dev - Start all apps in dev mode
  • pnpm build - Build all apps
  • pnpm lint - Lint all packages
  • pnpm format - Format code with Prettier

Database​

  • pnpm db:generate - Generate Prisma client
  • pnpm db:migrate:dev - Run migrations
  • pnpm db:studio - Open Prisma Studio
  • pnpm reset:local - Reset and seed database

Docker​

  • pnpm docker:up - Start Docker services
  • pnpm docker:down - Stop Docker services
  • pnpm docker:logs - View Docker logs
  • pnpm docker:reset - Reset Docker volumes

Testing​

Run Tests​

# All tests
pnpm test:all

# Backend tests only
pnpm --filter=@civstart/backend test

# Frontend tests only
pnpm --filter=@civstart/frontend test

Test Coverage​

pnpm test:check-coverage

Troubleshooting​

Port Already in Use​

If ports 3000, 3001, or 3002 are in use:

# Find and kill processes on ports
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9
lsof -ti:3002 | xargs kill -9

Database Connection Issues​

  1. Ensure Docker is running: docker ps
  2. Check database logs: pnpm docker:logs:db
  3. Reset database: pnpm docker:reset

Prisma Client Issues​

If you encounter Prisma client errors:

pnpm --filter=@repo/database db:generate

Next Steps​