DOCKER_GUIDE.md

# Docker Setup Guide for IntegraChat

## Quick Start

### Option 1: Use PowerShell Script (Easiest for Windows)

```powershell
# Run the helper script
.\run-docker.ps1
```

### Option 2: Build and Run with Docker Compose (Recommended)

```powershell
# PowerShell
docker-compose up -d

# Or with rebuild
docker-compose up -d --build
```

### Build and Run Manually

**PowerShell (Windows):**
```powershell
# Build the image
docker build -t integrachat:latest .

# Run the container (PowerShell uses backticks for line continuation)
docker run -d --name integrachat `
  -p 7860:7860 -p 8000:8000 -p 8900:8900 `
  -e DOCKER_CONTAINER=1 `
  integrachat:latest

# Or use a single line:
docker run -d --name integrachat -p 7860:7860 -p 8000:8000 -p 8900:8900 -e DOCKER_CONTAINER=1 integrachat:latest
```

**Bash/Linux/Mac:**
```bash
# Build the image
docker build -t integrachat:latest .

# Run the container
docker run -d --name integrachat \
  -p 7860:7860 -p 8000:8000 -p 8900:8900 \
  -e DOCKER_CONTAINER=1 \
  integrachat:latest
```

## Container Management

### View Logs
```bash
# All logs (streaming)
docker logs -f integrachat

# Specific service logs
docker exec integrachat tail -f /app/logs/fastapi.log
docker exec integrachat tail -f /app/logs/gradio.log
docker exec integrachat tail -f /app/logs/mcp.log
```

### Stop Container
```bash
docker stop integrachat
```

### Start Container
```bash
docker start integrachat
```

### Remove Container
```bash
docker stop integrachat
docker rm integrachat
```

### Rebuild After Changes

**PowerShell:**
```powershell
docker stop integrachat
docker rm integrachat
docker build -t integrachat:latest .
docker run -d --name integrachat -p 7860:7860 -p 8000:8000 -p 8900:8900 -e DOCKER_CONTAINER=1 integrachat:latest
```

**Bash:**
```bash
docker stop integrachat
docker rm integrachat
docker build -t integrachat:latest .
docker run -d --name integrachat \
  -p 7860:7860 -p 8000:8000 -p 8900:8900 \
  -e DOCKER_CONTAINER=1 \
  integrachat:latest
```

## Access Services

- **Gradio UI**: http://localhost:7860
- **FastAPI API**: http://localhost:8000
- **MCP Server**: http://localhost:8900
- **API Docs**: http://localhost:8000/docs
- **MCP Docs**: http://localhost:8900/docs

## Environment Variables

Create a `.env` file (or use docker-compose.yml) to configure:

```env
# LLM Configuration
LLM_BACKEND=groq  # or "ollama"
GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.1-8b-instant

# Supabase (optional - for analytics)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_key

# Ports (defaults shown)
API_PORT=8000
MCP_PORT=8900
GRADIO_PORT=7860
```

## Docker Compose

The `docker-compose.yml` file provides:
- Easy service management
- Environment variable support
- Volume mounting for logs
- Health checks
- Auto-restart on failure

### Using Docker Compose

```bash
# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up -d --build
```

## PowerShell-Specific Notes

### Line Continuation
PowerShell uses backticks (`` ` ``) for line continuation, not backslashes (`\`):

```powershell
# ✅ Correct (PowerShell)
docker run -d --name integrachat `
  -p 7860:7860 `
  -p 8000:8000 `
  integrachat:latest

# ✅ Also correct (single line)
docker run -d --name integrachat -p 7860:7860 -p 8000:8000 -p 8900:8900 -e DOCKER_CONTAINER=1 integrachat:latest

# ❌ Wrong (bash syntax - doesn't work in PowerShell)
docker run -d --name integrachat \
  -p 7860:7860 \
  integrachat:latest
```

### Quick Commands Script
Use `run-docker.ps1` for easy container management:
```powershell
.\run-docker.ps1
```

## Troubleshooting

### Check Container Status
```bash
docker ps -a | grep integrachat
```

### Check Service Health
```bash
# FastAPI health
curl http://localhost:8000/health

# MCP health
curl http://localhost:8900/health
```

### View All Logs
```bash
docker exec integrachat tail -n 100 /app/logs/*.log
```

### Restart Services Inside Container
```bash
# Container will auto-restart services, but you can manually restart:
docker restart integrachat
```

### Clean Up
```bash
# Remove container and image
docker stop integrachat
docker rm integrachat
docker rmi integrachat:latest

# Remove all unused Docker resources
docker system prune -a
```

## Notes

- The container runs all three services (MCP, FastAPI, Gradio) automatically
- Logs are written to `/app/logs/` inside the container
- The entrypoint script handles service startup and health checks
- Supabase warnings are expected if credentials are not configured (analytics will be disabled gracefully)