> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # Developer Setup > Get the full Equa development environment running locally # 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](https://github.com/nvm-sh/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](https://www.docker.com/products/docker-desktop/) | | Git | 2.x | Bundled with macOS Xcode CLI tools | Verify your setup: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} # 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`: ```env theme={null} 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`: ```env theme={null} 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: ```bash theme={null} 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`: ```env theme={null} 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 /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 ```bash theme={null} cd ~/Documents/repos/equa-server docker-compose up -d ``` Wait for the database to be ready: ```bash theme={null} 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) ```bash theme={null} 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. ```bash theme={null} cd ~/Documents/repos/equa-server yarn start:dev ``` The API server starts on **[http://localhost:3000](http://localhost:3000)**. Source: `equa-server/package.json` script `start:dev` runs `ts-node scripts/api.ts` ### Step 4: Frontend Development Server ```bash theme={null} cd ~/Documents/repos/equa-web yarn start ``` The frontend starts on **[http://localhost:8080](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: ```bash theme={null} 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) ```bash theme={null} cd ~/Documents/repos/equa-patternlib-nextjs npm run storybook ``` Storybook starts on **[http://localhost:6006](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](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](/web/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](http://localhost:8080) * **API health:** [http://localhost:3000](http://localhost:3000) (should return JSON, not HTML) * **Storybook:** [http://localhost:6006](http://localhost:6006) * **Gateway UI:** [http://localhost:18791](http://localhost:18791) * **Command Center:** [http://localhost:8080/prime?openEquanaut=true](http://localhost:8080/prime?openEquanaut=true) ## Stop Services ```bash theme={null} # 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](/onboarding/repository-guide) to understand how the codebase is organized.