Developer Setup
Last Verified: February 2026
This guide walks you through setting up the complete Equa development environment from scratch. By the end, you will have the database, backend API, frontend app, AI gateway, and component library all running locally.
Prerequisites
Install these tools before proceeding:
| Tool | Minimum Version | Install |
|---|
| Node.js | 22+ (24 recommended) | nvm — nvm install 24 |
| Yarn | 1.x (Classic) | npm install -g yarn |
| pnpm | 10+ | npm install -g pnpm |
| Docker Desktop | Latest | docker.com/products/docker-desktop |
| Git | 2.x | Bundled with macOS Xcode CLI tools |
node --version # v24.x.x
yarn --version # 1.22.x
pnpm --version # 10.x.x
docker --version # Docker version 2x.x.x
git --version # git version 2.x.x
Clone Repositories
Clone all active repositories into a common directory:
mkdir -p ~/Documents/repos && cd ~/Documents/repos
git clone https://github.com/EQUAStart/equa-web.git
git clone https://github.com/EQUAStart/equa-server.git
git clone https://github.com/EQUAStart/equabot.git # equabot-gateway
git clone https://github.com/EQUAStart/equa-patternlib-nextjs.git
git clone https://github.com/Balancing-Rock/command-center-so.git
equa-desktop-app-mac-ios repository exists as a placeholder but is not yet initialized. Skip it for now.
Install Dependencies
Each repo uses a different package manager:
# equa-server (Yarn workspaces)
cd ~/Documents/repos/equa-server && yarn install
# equa-web (Yarn)
cd ~/Documents/repos/equa-web && yarn install
# equabot-gateway (pnpm -- requires Node 22+)
cd ~/Documents/repos/equabot && pnpm install
# equa-patternlib (npm)
cd ~/Documents/repos/equa-patternlib-nextjs && npm install
# command-center-so (npm)
cd ~/Documents/repos/command-center-so && npm install
Environment Configuration
equa-server
Create ~/Documents/repos/equa-server/.env:
DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your-secure-password-here
DATABASE_NAME=equa
DATABASE_PORT=5432
NODE_ENV=development
PORT=3000
SESSION_SECRET=generate-a-random-string-here
AES_KEY=generate-a-32-byte-hex-key-here
EMAIL_TRANSPORTER=dev
equa-server/README.md and equa-server/.env.production.template
equa-web
Create ~/Documents/repos/equa-web/.env:
NODE_ENV=development
DISABLE_DRIFT=true
DISABLE_FULLSTORY=true
/api requests to http://localhost:3000 by default.
Source: equa-web/README.md (lines 12-19)
equabot-gateway
No .env file required for basic local development. The gateway uses its own config system via equabot config set.
command-center-so
Create ~/Documents/repos/command-center-so/.env.local with your auth provider credentials (see repo README for details).
Docs search prerequisite: The Command Center’s docs search feature (/docs, Cmd+K) requires a pre-built search index from the equa-docs repo:
cd ~/Documents/repos/equa-docs
npm install
npm run build:search # generates search-index.json
~/Documents/repos/equa-docs/search-index.json by default. To override the path, set EQUA_DOCS_PATH in .env.local:
EQUA_DOCS_PATH=/path/to/equa-docs
Search index not found at <path>/search-index.json. Run 'npm run build:search' in equa-docs.
Source: command-center-so/src/lib/docsIndex.ts, equa-docs/SEARCH-ARCHITECTURE.md
Start Services
Start services in this order. Each service depends on the previous one.
Step 1: PostgreSQL Database
cd ~/Documents/repos/equa-server
docker-compose up -d
until docker exec equa-postgres pg_isready -U postgres -d equa 2>/dev/null; do
sleep 1
done
echo "Database ready"
equa-start-dev skill, verified startup sequence
Step 2: Initialize Database (first time only)
cd ~/Documents/repos/equa-server
yarn init:db
equa-server/package.json script init:db
Step 3: Backend API Server
Port 3000 is reserved for equa-server. The command-center-so npm run dev script binds to port 3001, so there is no conflict when both run simultaneously. If you manually run npx next dev without -p 3001, Next.js will default to 3000 and collide with equa-server. Always use npm run dev (which includes -p 3001) rather than bare next dev.
cd ~/Documents/repos/equa-server
yarn start:dev
equa-server/package.json script start:dev runs ts-node scripts/api.ts
Step 4: Frontend Development Server
cd ~/Documents/repos/equa-web
yarn start
equa-web/package.json script start — includes NODE_OPTIONS='--openssl-legacy-provider' automatically
Step 5: Equabot Gateway (optional)
The gateway requires Node 22+. If you use nvm, switch to Node 24 first:
nvm use 24
cd ~/Documents/repos/equabot
EQUABOT_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway --port 18789 --allow-unconfigured
- WebSocket:
ws://127.0.0.1:18789
- Browser Control UI:
http://localhost:18791
Source: equa-start-dev skill Step 5; equabot-gateway/package.json engine requirement >=22.12.0
Step 6: Storybook (optional)
cd ~/Documents/repos/equa-patternlib-nextjs
npm run storybook
equa-patternlib-nextjs/package.json script storybook
Step 7: Command Center (optional)
cd ~/Documents/repos/command-center-so
npm run dev
dev script includes -p 3001 so it does not conflict with equa-server on port 3000.
Source: command-center-so/package.json script dev runs next dev -p 3001 (Next.js 16 with Turbopack)
Verify Everything Works
Check that all services are listening:
| Service | Port | Check Command | Expected |
|---|
| PostgreSQL | 5432 | docker ps | grep equa-postgres | Container running |
| equa-server | 3000 | ps aux | grep "ts-node.*api.ts" | grep -v grep | ts-node process |
| equa-web | 8080 | lsof -i :8080 | head -3 | node process |
| equabot Gateway | 18789 | lsof -i :18789 | head -3 | node process |
| Browser Control | 18791 | lsof -i :18791 | head -3 | node process |
| Storybook | 6006 | lsof -i :6006 | head -3 | node process |
| Command Center | 3001 | lsof -i :3001 | head -3 | next-server process |
Verify equa-server specifically (not just “something on port 3000”): Run ps -p $(lsof -ti :3000) -o command= — it should show ts-node or Express, not next-server. If it shows next-server, that’s command-center-so occupying equa-server’s port.
Stop Services
# Stop application processes
pkill -f "equa-server.*start:dev"
pkill -f "equa-web.*webpack"
pkill -f "equabot.*gateway"
pkill -f "storybook"
pkill -f "command-center-so.*next"
# Stop database
cd ~/Documents/repos/equa-server && docker-compose down
equa-start-dev skill “Stop Services” section
Troubleshooting
| Symptom | Cause | Fix |
|---|
Error: listen EADDRINUSE :3000 | Port 3000 occupied (another process or bare next dev without -p) | lsof -i :3000 to identify the process; kill it. Always use npm run dev for command-center-so (binds to 3001) |
403 Forbidden on /api/v1/organization/:id | Session expired or user lacks org permission | Re-authenticate at http://localhost:8080/login, then check http://localhost:3000/v1/auth/diagnostic to confirm session state and user binding |
401 on authenticated API calls | Missing/invalid session cookie | Sign in again at http://localhost:8080/login, then verify GET /v1/user/current returns a user and http://localhost:3000/v1/auth/diagnostic shows hasUser: true |
| Need deeper auth diagnostics for 401/403 errors | No auth debug logs enabled | Start equa-server with DEBUG=equa:auth yarn start:dev to log rejected sessions and permission denials |
Error: digital envelope routines::unsupported on equa-web | Missing OpenSSL legacy provider | Verify yarn start includes NODE_OPTIONS='--openssl-legacy-provider' (it should automatically) |
error engine required: node >=22.12.0 on equabot | Wrong Node version active | nvm use 24 before running equabot commands |
| Docker compose fails | Docker Desktop not running | Start Docker Desktop, wait for it to initialize |
ECONNREFUSED 127.0.0.1:5432 | PostgreSQL container not running | cd equa-server && docker-compose up -d |
yarn: command not found | Yarn not installed globally | npm install -g yarn |
pnpm: command not found | pnpm not installed globally | npm install -g pnpm |
| Hot reload not working | Stale cache or file watcher limit | Restart the dev server; on Linux increase fs.inotify.max_user_watches |
Next Steps
Once your environment is running, read the Repository Guide to understand how the codebase is organized.
