> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Setting up Brainstormer V2 for local development: prerequisites, Docker infrastructure, npm install, running services, and troubleshooting.

## Overview

Local development uses a hybrid approach:

* **Docker** for infrastructure (PostgreSQL, Redis, ChromaDB)
* **npm + Turbo** for application services (hot-reload development)

## Prerequisites

| Software       | Version               | Purpose                   |
| -------------- | --------------------- | ------------------------- |
| Docker Desktop | 20.x+                 | Infrastructure containers |
| Node.js        | 18+ (LTS recommended) | Runtime                   |
| npm            | 9+                    | Package management        |

<CodeGroup>
  ```bash Install Node.js via nvm theme={null}
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
  nvm install 20
  nvm use 20
  ```

  ```bash Verify installations theme={null}
  node --version    # Should be 18.x or 20.x
  npm --version     # Should be 9.x or 10.x
  docker --version  # Should be 20.x or higher
  ```
</CodeGroup>

## Infrastructure Setup (Docker)

### Start Containers

```bash theme={null}
# Start existing containers
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma

# Check status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

You should see three running containers:

| Container             | Port |
| --------------------- | ---- |
| brainstormer-postgres | 5432 |
| brainstormer-redis    | 6379 |
| brainstormer-chroma   | 8000 |

<Note>
  If containers don't exist yet, see the [Docker Setup](/developer/deployment/docker) guide for initial creation.
</Note>

### Database Migrations

Migrations run automatically on first container start. To run manually:

```bash theme={null}
# Run all migrations
for migration in infrastructure/postgres/migrations/*.sql; do
  echo "Running: $migration"
  docker exec -i brainstormer-postgres psql -U brainstormer -d brainstormer < "$migration"
done
```

### Verify Infrastructure

```bash theme={null}
# PostgreSQL
docker exec brainstormer-postgres pg_isready -U brainstormer

# Redis
docker exec brainstormer-redis redis-cli ping
# Should return: PONG

# ChromaDB
curl http://localhost:8000/api/v1/heartbeat
```

## Environment Configuration

<Steps>
  <Step title="Copy Template">
    ```bash theme={null}
    cp .env.docker .env
    ```
  </Step>

  <Step title="Set Required Keys">
    ```bash theme={null}
    # OpenRouter (REQUIRED for AI features)
    OPENROUTER_API_KEY=sk-or-v1-your-key-here

    # OpenAI (REQUIRED for Knowledge Base embeddings)
    OPENAI_API_KEY=sk-your-key-here

    # Database (Docker container)
    DATABASE_URL=postgresql://brainstormer:password@localhost:5432/brainstormer

    # Redis
    REDIS_HOST=localhost
    REDIS_PORT=6379

    # JWT Secret
    JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
    ```
  </Step>

  <Step title="Optional Keys">
    ```bash theme={null}
    ELEVENLABS_API_KEY=your-key          # Voice cloning
    LLAMA_CLOUD_API_KEY=llx-your-key     # Advanced document parsing
    PINECONE_API_KEY=your-key            # Production vector storage
    CLOUD_STORAGE_ENABLED=false          # S3 file storage
    ```
  </Step>
</Steps>

## Application Setup

### Install Dependencies

```bash theme={null}
npm install
```

This installs dependencies for all workspace packages: root, services/gateway, services/auth, services/bot, services/realtime-audio, services/knowledge, apps/web, and packages/shared.

### Start Development Servers

```bash theme={null}
npm run dev
```

This starts all services with hot-reload:

| Service           | URL                                            |
| ----------------- | ---------------------------------------------- |
| API Gateway       | [http://localhost:4000](http://localhost:4000) |
| Auth Service      | [http://localhost:4001](http://localhost:4001) |
| Bot Service       | [http://localhost:4002](http://localhost:4002) |
| Realtime Audio    | [http://localhost:4003](http://localhost:4003) |
| Knowledge Service | [http://localhost:4005](http://localhost:4005) |
| Web App           | [http://localhost:3000](http://localhost:3000) |

### Verify Services

```bash theme={null}
curl http://localhost:4000/health  # Gateway
curl http://localhost:4001/health  # Auth
curl http://localhost:4002/health  # Bot
curl http://localhost:4005/health  # Knowledge
```

## Development Workflow

### Making Changes

1. Edit code in your editor
2. Services auto-reload (tsx watch for backend, Turbopack for frontend)
3. Refresh browser to see frontend changes

### Running Individual Services

```bash theme={null}
cd services/auth && npm run dev       # Port 4001
cd services/bot && npm run dev        # Port 4002
cd services/gateway && npm run dev    # Port 4000
cd services/knowledge && npm run dev  # Port 4005
cd apps/web && npm run dev            # Port 3000
```

### Stopping Services

```bash theme={null}
# Stop npm dev: Ctrl+C in terminal

# Stop infrastructure (keeps data)
docker stop brainstormer-postgres brainstormer-redis brainstormer-chroma
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Containers not running">
    ```bash theme={null}
    docker ps -a | grep brainstormer
    docker start brainstormer-postgres brainstormer-redis brainstormer-chroma
    ```
  </Accordion>

  <Accordion title="Database connection errors">
    ```bash theme={null}
    docker exec brainstormer-postgres pg_isready -U brainstormer
    docker logs brainstormer-postgres
    ```
  </Accordion>

  <Accordion title="Port conflicts">
    ```bash theme={null}
    lsof -ti:3000,4000,4001,4002,4003,4005 | xargs kill -9
    ```
  </Accordion>

  <Accordion title="Build errors">
    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    rm -rf .turbo
    npm run build
    ```
  </Accordion>

  <Accordion title="TypeScript errors">
    ```bash theme={null}
    npm run typecheck
    npm run lint -- --fix
    ```
  </Accordion>

  <Accordion title="Missing environment variables">
    ```bash theme={null}
    ls -la .env
    cat .env | grep -E "OPENROUTER_API_KEY|OPENAI_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

## Quick Reference

```bash theme={null}
# Complete startup
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma
npm install
npm run dev
open http://localhost:3000

# Complete shutdown
# Ctrl+C (stop npm dev)
docker stop brainstormer-postgres brainstormer-redis brainstormer-chroma
```