Docker Setup

Quick Start

Prerequisites

Docker Desktop installed and running
At least 8GB RAM available for Docker
20GB free disk space

Configure Environment

cp .env.docker .env
# Edit .env and add your API keys
# Required: OPENAI_API_KEY, OPENROUTER_API_KEY

Start All Services

./scripts/docker-start.sh
# Or: docker-compose up --build -d

Access the Platform

Open http://localhost:3000

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

# 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

# All services
./scripts/docker-logs.sh

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

Rebuild Services

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

# 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

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

# 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

OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-v1-...

Optional

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

Development
Production

Default passwords used (suitable for development only)
PostgreSQL: brainstormer / password
JWT Secret: development-secret-key-replace-in-production

Health Checks

# 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

Services won't start

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

Port conflicts

lsof -i:3000
lsof -i:4000
lsof -i:5432
# Stop conflicting services, then restart Docker

Database issues

# Reset database (DELETES ALL DATA)
docker-compose down -v
docker-compose up -d postgres
docker-compose up -d

Build failures

docker system prune -a              # Clear Docker cache
docker-compose build --no-cache     # Rebuild without cache
docker system df                    # Check disk space

Out of memory

Increase Docker memory limit in Docker Desktop settings. Recommended: 8GB minimum.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Quick Start

Services Architecture

Management Scripts

Start and Stop

View Logs

Rebuild Services

Direct Docker Commands

Database Migrations

Environment Variables

Required

Optional

Security Notes

Health Checks

Troubleshooting

​Quick Start

​Services Architecture

​Management Scripts

​Start and Stop

​View Logs

​Rebuild Services

​Direct Docker Commands

​Database Migrations

​Environment Variables

​Required

​Optional

​Security Notes

​Health Checks

​Troubleshooting

Quick Start

Services Architecture

Management Scripts

Start and Stop

View Logs

Rebuild Services

Direct Docker Commands

Database Migrations

Environment Variables

Required

Optional

Security Notes

Health Checks

Troubleshooting