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

# Docker Setup

> Complete Docker containerization: Docker Compose services, container management scripts, rebuilding, and troubleshooting.

## Quick Start

<Steps>
  <Step title="Prerequisites">
    * Docker Desktop installed and running
    * At least 8GB RAM available for Docker
    * 20GB free disk space
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    cp .env.docker .env
    # Edit .env and add your API keys
    # Required: OPENAI_API_KEY, OPENROUTER_API_KEY
    ```
  </Step>

  <Step title="Start All Services">
    ```bash theme={null}
    ./scripts/docker-start.sh
    # Or: docker-compose up --build -d
    ```
  </Step>

  <Step title="Access the Platform">
    Open [http://localhost:3000](http://localhost:3000)
  </Step>
</Steps>

## Services Architecture

| Service           | Port | Container                   | Description        |
| ----------------- | ---- | --------------------------- | ------------------ |
| Web App           | 3000 | brainstormer-web            | Next.js frontend   |
| API Gateway       | 4000 | brainstormer-gateway        | Request routing    |
| Auth Service      | 4001 | brainstormer-auth           | Authentication     |
| Bot Service       | 4002 | brainstormer-bot            | AI chat and agents |
| Realtime Audio    | 4003 | brainstormer-realtime-audio | Voice cloning      |
| Knowledge Service | 4005 | brainstormer-knowledge      | RAG system         |
| PostgreSQL        | 5432 | brainstormer-postgres       | Database           |
| Redis             | 6379 | brainstormer-redis          | Job queue          |
| ChromaDB          | 8000 | brainstormer-chroma         | Vector DB          |

## Management Scripts

### Start and Stop

```bash theme={null}
# Start all services
./scripts/docker-start.sh

# Stop all services
./scripts/docker-stop.sh

# Stop and remove all data (DESTRUCTIVE)
docker-compose down -v
```

### View Logs

```bash theme={null}
# All services
./scripts/docker-logs.sh

# Specific service
./scripts/docker-logs.sh gateway
./scripts/docker-logs.sh knowledge
```

### Rebuild Services

<Warning>
  Always use `--no-cache` for reliable rebuilds. `docker compose up -d --build` often uses cached layers and does NOT pick up source changes.
</Warning>

```bash theme={null}
# Rebuild all services
docker compose build --no-cache && docker compose up -d

# Rebuild specific service
docker compose build --no-cache gateway && docker compose up -d gateway

# Check what code is in a running container
docker exec brainstormer-gateway cat /app/services/gateway/dist/index.js
```

### Direct Docker Commands

```bash theme={null}
# View running containers
docker-compose ps

# Restart a service
docker-compose restart knowledge

# Execute command in container
docker-compose exec knowledge sh

# View logs (follow)
docker-compose logs -f knowledge

# Build without cache
docker-compose build --no-cache
```

## Database Migrations

Migrations run automatically on container startup. To run manually:

```bash theme={null}
# Access PostgreSQL
docker-compose exec postgres psql -U brainstormer -d brainstormer

# Run a specific migration
docker-compose exec postgres psql -U brainstormer -d brainstormer \
  -f /docker-entrypoint-initdb.d/001_initial_schema.sql
```

## Environment Variables

### Required

```bash theme={null}
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-v1-...
```

### Optional

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-...       # Claude models
ELEVENLABS_API_KEY=...             # Voice cloning
LLAMA_CLOUD_API_KEY=...            # LlamaParse
PINECONE_API_KEY=...               # Production vectors
CLOUD_STORAGE_ENABLED=true         # S3 storage
CLOUD_STORAGE_PROVIDER=aws-s3
CLOUD_STORAGE_BUCKET=your-bucket
```

## Security Notes

<Tabs>
  <Tab title="Development">
    * Default passwords used (suitable for development only)
    * PostgreSQL: `brainstormer` / `password`
    * JWT Secret: `development-secret-key-replace-in-production`
  </Tab>

  <Tab title="Production">
    Before deploying to production:

    1. Change all default passwords
    2. Use strong JWT secret (32+ characters)
    3. Enable HTTPS/TLS
    4. Configure firewall rules
    5. Use environment-specific secrets
    6. Enable Docker secrets management
  </Tab>
</Tabs>

## Health Checks

```bash theme={null}
# View health status
docker-compose ps

# Service health endpoints
curl http://localhost:4000/health  # Gateway
curl http://localhost:4005/health  # Knowledge

# Resource usage
docker stats
docker system df
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Services won't start">
    ```bash theme={null}
    docker ps                           # Check Docker is running
    docker-compose logs [service-name]  # Check service logs
    docker-compose down                 # Remove all containers
    docker-compose up --build -d        # Rebuild and start
    ```
  </Accordion>

  <Accordion title="Port conflicts">
    ```bash theme={null}
    lsof -i:3000
    lsof -i:4000
    lsof -i:5432
    # Stop conflicting services, then restart Docker
    ```
  </Accordion>

  <Accordion title="Database issues">
    ```bash theme={null}
    # Reset database (DELETES ALL DATA)
    docker-compose down -v
    docker-compose up -d postgres
    docker-compose up -d
    ```
  </Accordion>

  <Accordion title="Build failures">
    ```bash theme={null}
    docker system prune -a              # Clear Docker cache
    docker-compose build --no-cache     # Rebuild without cache
    docker system df                    # Check disk space
    ```
  </Accordion>

  <Accordion title="Out of memory">
    Increase Docker memory limit in Docker Desktop settings. Recommended: 8GB minimum.
  </Accordion>
</AccordionGroup>