Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1# Local Development Guide
2
3This guide covers configuration details and troubleshooting for local development. For the quickstart, see the [root README](../README.md).
4
5## Prerequisites
6
7- **Operating System**: macOS, Linux, or Windows with WSL2
8- **Node.js 24** (use `nvm install && nvm use` so local matches `.nvmrc`)
9- **npm** (included with Node.js)
10- **Docker and Docker Compose**
11- **16 GB RAM** or more recommended
12
13## Environment Setup
14
15### Server Configuration
16
17Copy `server/.env.example` to `server/.env`. The example file contains all available options with documentation. Key sections:
18
19- **Database connections**: PostgreSQL, ClickHouse, ScyllaDB, Redis
20- **Kafka**: Broker and schema registry settings
21- **External APIs**: OpenAI, SendGrid, Google APIs (optional)
22- **Security**: Session secrets, JWT signing keys
23
24The default values work with Docker Compose services out of the box.
25
26### Client Configuration
27
28Copy `client/.env.example` to `client/.env`. Defaults work for local development.
29
30## Docker Services
31
32Start all backing services:
33
34```bash
35npm run up
36```
37
38This starts:
39
40Service | Port | Notes
41----------------|------------|---------------------------------
42PostgreSQL | 5432 | Primary DB (with pgvector)
43ClickHouse | 8123, 9000 | Analytics warehouse
44ScyllaDB | 9042 | Item submission history
45Redis | 6379 | Caching and job queues
46Kafka | 29092 | Event streaming
47Schema Registry | 8081 | Kafka schemas
48Zookeeper | 22181 | Kafka coordination
49HMA | 5000 | Hash Matching Algorithm service
50Jaeger | 16686 | Tracing UI (opens automatically)
51OTEL Collector | 4317 | Telemetry collection
52
53Check service health:
54
55```bash
56docker ps
57docker logs <container-name>
58```
59
60Stop services:
61
62```bash
63npm run down
64```
65
66## Database Operations
67
68### Running Migrations
69
70```bash
71npm run db:update -- --env staging --db api-server-pg
72npm run db:update -- --env staging --db clickhouse
73#Creating keyspace
74npm run db:create -- --env staging --db scylla
75#Running migrations
76npm run db:update -- --env staging --db scylla
77```
78
79### Other Commands
80
81```bash
82npm run db:add -- --name <migration-name> --db api-server-pg
83npm run db:clean # Drop and recreate (destructive)
84npm run db:create # Create database
85npm run db:drop # Drop database
86```
87
88### Migration Locations
89
90```
91.devops/migrator/src/scripts/
92├── api-server-pg/ # PostgreSQL
93├── clickhouse/ # ClickHouse
94├── scylla/ # ScyllaDB
95└── snowflake/ # Snowflake (optional)
96```
97
98## Running the Application
99
100### All Services Together
101
102```bash
103npm run start # Client + server + GraphQL codegen (opens browser)
104npm run compile # Same, without opening browser
105```
106
107### Individual Services (Recommended for Debugging)
108
109```bash
110# Terminal 1
111npm run client:start
112
113# Terminal 2
114npm run server:start
115
116# Terminal 3 (optional, for GraphQL schema changes)
117npm run generate:watch
118```
119
120### With Distributed Tracing
121
122```bash
123cd server && npm run start:trace
124```
125
126View traces at http://localhost:16686
127
128### Access Points
129
130Service | URL
131-----------|------------------------------
132Client | http://localhost:3000
133API Server | http://localhost:8080
134GraphQL | http://localhost:8080/graphql
135Jaeger UI | http://localhost:16686
136
137## Testing
138
139```bash
140# Server
141cd server
142npm run test # Watch mode
143npm run test:prepush # Single run
144npm run test:integ # Integration tests
145
146# Client
147cd client
148npm run test # Watch mode
149npm run test:prepush # Single run
150
151# Full validation (run before pushing)
152npm run check:prepush
153```
154
155## GraphQL Development
156
157Coop uses schema-first GraphQL with bidirectional code generation.
158
159```bash
160npm run generate # One-time
161npm run generate:watch # Watch mode
162```
163
164Generated files:
165- `client/src/graphql/generated.ts`
166- `server/graphql/generated.ts`
167
168Schema changes trigger recompilation of both client and server. If you experience regeneration loops, stop watch mode and run manually.
169
170## Troubleshooting
171
172### ScyllaDB Not Ready
173
174ScyllaDB takes 30-60 seconds to initialize. If migrations fail immediately after `npm run up`, wait and retry.
175
176### ClickHouse Migration Fails
177
178Ensure `CLICKHOUSE_USERNAME` and `CLICKHOUSE_PASSWORD` are set in your `.env`.
179
180### Port Conflicts
181
182```bash
183lsof -i :3000 # Client
184lsof -i :8080 # Server
185lsof -i :5432 # PostgreSQL
186```
187
188### Reset Everything
189
190```bash
191npm run down
192docker volume prune # Warning: removes all Docker volumes
193npm run up
194npm run db:update -- --env staging --db api-server-pg
195npm run db:update -- --env staging --db clickhouse
196npm run create-org
197```
198
199### Connecting to Databases Directly
200
201```bash
202# PostgreSQL
203psql -h localhost -U postgres -d postgres
204# Password: postgres123
205
206# ClickHouse
207clickhouse-client --host localhost --user default --password clickhouse
208
209# Redis
210redis-cli
211```
212
213## Code Quality
214
215```bash
216npm run lint # ESLint
217npm run format # Prettier
218npm run check:prepush # Run before pushing
219```