Local Development Guide

This guide covers configuration details and troubleshooting for local development. For the quickstart, see the root README.

Prerequisites

• Operating System: macOS, Linux, or Windows with WSL2
• Node.js 24 (use nvm install && nvm use so local matches .nvmrc)
• npm (included with Node.js)
• Docker and Docker Compose
• 16 GB RAM or more recommended

Environment Setup

Server Configuration

Copy server/.env.example to server/.env. The example file contains all available options with documentation. Key sections:

• Database connections: PostgreSQL, ClickHouse, ScyllaDB, Redis
• Kafka: Broker and schema registry settings
• External APIs: OpenAI, SendGrid, Google APIs (optional)
• Security: Session secrets, JWT signing keys

The default values work with Docker Compose services out of the box.

Client Configuration

Copy client/.env.example to client/.env. Defaults work for local development.

Docker Services

Start all backing services:

npm run up

This starts:

Check service health:

docker ps
docker logs <container-name>

Stop services:

npm run down

Database Operations

Running Migrations

npm run db:update -- --env staging --db api-server-pg
npm run db:update -- --env staging --db clickhouse
#Creating keyspace
npm run db:create -- --env staging --db scylla
#Running migrations
npm run db:update -- --env staging --db scylla

Other Commands

npm run db:add -- --name <migration-name> --db api-server-pg
npm run db:clean    # Drop and recreate (destructive)
npm run db:create   # Create database
npm run db:drop     # Drop database

Migration Locations

.devops/migrator/src/scripts/
├── api-server-pg/    # PostgreSQL
├── clickhouse/       # ClickHouse
├── scylla/           # ScyllaDB
└── snowflake/        # Snowflake (optional)

Running the Application

All Services Together

npm run start       # Client + server + GraphQL codegen (opens browser)
npm run compile     # Same, without opening browser

Individual Services (Recommended for Debugging)

# Terminal 1
npm run client:start

# Terminal 2
npm run server:start

# Terminal 3 (optional, for GraphQL schema changes)
npm run generate:watch

With Distributed Tracing

cd server && npm run start:trace

View traces at http://localhost:16686

Access Points

Testing

# Server
cd server
npm run test              # Watch mode
npm run test:prepush      # Single run
npm run test:integ        # Integration tests

# Client
cd client
npm run test              # Watch mode
npm run test:prepush      # Single run

# Full validation (run before pushing)
npm run check:prepush

GraphQL Development

Coop uses schema-first GraphQL with bidirectional code generation.

npm run generate          # One-time
npm run generate:watch    # Watch mode

Generated files:

• client/src/graphql/generated.ts
• server/graphql/generated.ts

Schema changes trigger recompilation of both client and server. If you experience regeneration loops, stop watch mode and run manually.

Troubleshooting

ScyllaDB Not Ready

ScyllaDB takes 30-60 seconds to initialize. If migrations fail immediately after npm run up, wait and retry.

ClickHouse Migration Fails

Ensure CLICKHOUSE_USERNAME and CLICKHOUSE_PASSWORD are set in your .env.

Port Conflicts

lsof -i :3000    # Client
lsof -i :8080    # Server
lsof -i :5432    # PostgreSQL

Reset Everything

npm run down
docker volume prune    # Warning: removes all Docker volumes
npm run up
npm run db:update -- --env staging --db api-server-pg
npm run db:update -- --env staging --db clickhouse
npm run create-org

Connecting to Databases Directly

# PostgreSQL
psql -h localhost -U postgres -d postgres
# Password: postgres123

# ClickHouse
clickhouse-client --host localhost --user default --password clickhouse

# Redis
redis-cli

Code Quality

npm run lint       # ESLint
npm run format     # Prettier
npm run check:prepush    # Run before pushing