> ## 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.

# New Machine Setup

> Complete setup guide for a fresh machine: prerequisites, cloning, infrastructure, migrations, and verification.

## Prerequisites

### Required Software

<Steps>
  <Step title="Docker Desktop">
    ```bash theme={null}
    # Download and install Docker Desktop
    # Visit: https://www.docker.com/products/docker-desktop
    docker --version  # Should be >= 20.x
    ```
  </Step>

  <Step title="Node.js 18+">
    ```bash theme={null}
    # macOS (Homebrew)
    brew install node@20

    # Or via nvm
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    nvm install 20
    nvm use 20

    node --version  # Should be >= v18.0.0
    npm --version   # Should be >= v9.0.0
    ```
  </Step>

  <Step title="Git">
    ```bash theme={null}
    git --version  # Should already be installed
    ```
  </Step>
</Steps>

<Note>
  PostgreSQL, Redis, and ChromaDB run in Docker containers. No manual installation needed.
</Note>

## Project Setup

### 1. Clone Repository

```bash theme={null}
git clone https://github.com/brainstormerio/brainstormerv2.git
cd brainstormerv2
```

### 2. Infrastructure Setup (Docker)

```bash theme={null}
# Start infrastructure containers
# If containers don't exist, see Docker Setup guide for initial creation
docker start brainstormer-postgres brainstormer-redis brainstormer-chroma

# Verify containers are running
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Test PostgreSQL connection
docker exec brainstormer-postgres pg_isready -U brainstormer
```

### 3. Run Database Migrations

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

# Verify tables
docker exec brainstormer-postgres psql -U brainstormer -d brainstormer -c "\dt"
```

**Expected tables include:**

* `users`, `organizations`, `organization_members`
* `bots`, `bot_prompt_versions`, `conversations`, `messages`, `token_usage`
* `ai_models`, `message_attachments`, `custom_voices`
* `knowledge_bases`, `kb_sources`, `kb_documents`, `kb_document_chunks`, `kb_agent_links`, `kb_analytics`

### 4. Install Dependencies

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

### 5. Environment Configuration

```bash theme={null}
cp .env.example .env
```

Edit `.env` with your API keys:

<Tabs>
  <Tab title="Required">
    ```bash theme={null}
    DATABASE_URL=postgresql://brainstormer:password@localhost:5432/brainstormer
    OPENROUTER_API_KEY=your-openrouter-api-key
    REDIS_HOST=localhost
    REDIS_PORT=6379
    JWT_SECRET=your-super-secret-jwt-key
    NODE_ENV=development
    ```
  </Tab>

  <Tab title="Optional">
    ```bash theme={null}
    ELEVENLABS_API_KEY=your-elevenlabs-key
    LLAMA_CLOUD_API_KEY=your-llama-cloud-key
    PINECONE_API_KEY=your-pinecone-key
    PINECONE_ENVIRONMENT=us-east-1
    PINECONE_INDEX_NAME=brainstormer-kb
    CLOUD_STORAGE_ENABLED=false
    ```
  </Tab>
</Tabs>

### 6. Start Services

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

## Verification Checklist

### Database

```bash theme={null}
# Check tables exist
docker exec brainstormer-postgres psql -U brainstormer -d brainstormer -c "\dt"

# Check views
docker exec brainstormer-postgres psql -U brainstormer -d brainstormer -c "\dv"
# Should show: kb_summary, document_usage_stats
```

### 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:4003/health  # Realtime Audio
curl http://localhost:4005/health  # Knowledge
```

### Redis

```bash theme={null}
docker exec brainstormer-redis redis-cli ping
# Should return: PONG
```

### Frontend

1. Open [http://localhost:3000](http://localhost:3000)
2. Register a new account
3. Create a test agent
4. Send a test message
5. Verify chat works with OpenRouter

## API Keys to Obtain

### Required

| Key        | URL                                                      | Purpose               |
| ---------- | -------------------------------------------------------- | --------------------- |
| OpenRouter | [https://openrouter.ai/keys](https://openrouter.ai/keys) | AI chat (300+ models) |

### Optional

| Key        | URL                                                                                        | Purpose            |
| ---------- | ------------------------------------------------------------------------------------------ | ------------------ |
| ElevenLabs | [https://elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys) | Voice cloning      |
| LlamaParse | [https://cloud.llamaindex.ai/api-key](https://cloud.llamaindex.ai/api-key)                 | Document parsing   |
| Pinecone   | [https://app.pinecone.io/](https://app.pinecone.io/)                                       | Production vectors |

## Quick Reference

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

# Type check
npm run typecheck

# Build
npm run build

# Run migrations
for f in infrastructure/postgres/migrations/*.sql; do
  docker exec -i brainstormer-postgres psql -U brainstormer -d brainstormer < "$f"
done
```