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	18+ for equa-web/equa-server; 22+ for equabot-gateway	nvm — `nvm install 18` (or `nvm install 24` for gateway)
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

Verify your setup:

node --version   # v18.x.x (equa-web/equa-server) or v24.x.x (equabot-gateway)
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

The equa-desktop-app-mac-ios repository exists as a placeholder but is not yet initialized. Skip it for now. The old command-center-so repository is frozen source material and is not required for current local Command Center setup.

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

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

Source: 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

The webpack dev server proxies /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 (frozen source material only)

Do not configure or start command-center-so for current local Command Center work. The supported Command Center opens inside equa-web. Only clone or configure command-center-so when doing an explicit source-material parity audit. 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

The frozen source app reads the index from ~/Documents/repos/equa-docs/search-index.json by default. To override the path for a parity audit, set EQUA_DOCS_PATH in its .env.local:

EQUA_DOCS_PATH=/path/to/equa-docs

If the index file is missing, the search API returns a 500 error with: 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

Wait for the database to be ready:

until docker exec equa-postgres pg_isready -U postgres -d equa 2>/dev/null; do
  sleep 1
done
echo "Database ready"

Source: equa-start-dev skill, verified startup sequence

Step 2: Initialize Database (first time only)

cd ~/Documents/repos/equa-server
yarn init:db

This creates all tables via TypeORM schema synchronization. Source: equa-server/package.json script init:db

Step 3: Backend API Server

Port 3000 is reserved for equa-server. If a Next.js dev server or any other process binds to 3000, stop that process and restart equa-server. The current Command Center does not require a Next.js process on port 3001.

cd ~/Documents/repos/equa-server
yarn start:dev

The API server starts on http://localhost:3000. Source: 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

The frontend starts on http://localhost:8080 and proxies API calls to the backend at port 3000. Source: 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

The gateway runs on:

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

Storybook starts on http://localhost:6006. Source: equa-patternlib-nextjs/package.json script storybook

Step 7: Command Center

With the Step 4 equa-web dev server still running, open http://localhost:8080/prime?openEquanaut=true or use the Equanaut rail on supported equa-web routes. command-center-so remains frozen source material and should not be started for current local Command Center work. Source: equa-web/specs/060-command-center-fleet-management-shell/spec.md and Command Center.

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	8080	`curl -fsS http://localhost:8080/prime?openEquanaut=true \| head -3`	equa-web app HTML

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.

Open these URLs in your browser:

Frontend: http://localhost:8080
API health: http://localhost:3000 (should return JSON, not HTML)
Storybook: http://localhost:6006
Gateway UI: http://localhost:18791
Command Center: http://localhost:8080/prime?openEquanaut=true

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

Source: equa-start-dev skill “Stop Services” section

Troubleshooting

Symptom	Cause	Fix
`Error: listen EADDRINUSE :3000`	Port 3000 occupied by another process	`lsof -i :3000` to identify the process, stop/kill it, then restart equa-server; a `next-server` process usually means an accidental Next.js dev server bound to 3000
`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.

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Developer Setup

Developer Setup

Prerequisites

Clone Repositories

Install Dependencies

Environment Configuration

equa-server

equa-web

equabot-gateway

command-center-so (frozen source material only)

Start Services

Step 1: PostgreSQL Database

Step 2: Initialize Database (first time only)

Step 3: Backend API Server

Step 4: Frontend Development Server

Step 5: Equabot Gateway (optional)

Step 6: Storybook (optional)

Step 7: Command Center

Verify Everything Works

Stop Services

Troubleshooting

Next Steps

​Developer Setup

​Prerequisites

​Clone Repositories

​Install Dependencies

​Environment Configuration

​equa-server

​equa-web

​equabot-gateway

​command-center-so (frozen source material only)

​Start Services

​Step 1: PostgreSQL Database

​Step 2: Initialize Database (first time only)

​Step 3: Backend API Server

​Step 4: Frontend Development Server

​Step 5: Equabot Gateway (optional)

​Step 6: Storybook (optional)

​Step 7: Command Center

​Verify Everything Works

​Stop Services

​Troubleshooting

​Next Steps

Developer Setup

Prerequisites

Clone Repositories

Install Dependencies

Environment Configuration

equa-server

equa-web

equabot-gateway

command-center-so (frozen source material only)

Start Services

Step 1: PostgreSQL Database

Step 2: Initialize Database (first time only)

Step 3: Backend API Server

Step 4: Frontend Development Server

Step 5: Equabot Gateway (optional)

Step 6: Storybook (optional)

Step 7: Command Center

Verify Everything Works

Stop Services

Troubleshooting

Next Steps