DOCKER_GUIDE.md

Docker Setup Guide for IntegraChat

Quick Start

Option 1: Use PowerShell Script (Easiest for Windows)

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

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

# PowerShell
docker-compose up -d

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

Build and Run Manually

PowerShell (Windows):

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

# 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

# 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

docker stop integrachat

Start Container

docker start integrachat

Remove Container

docker stop integrachat
docker rm integrachat

Rebuild After Changes

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:

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:

# 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

# 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 (\):

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

.\run-docker.ps1

Troubleshooting

Check Container Status

docker ps -a | grep integrachat

Check Service Health

# FastAPI health
curl http://localhost:8000/health

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

View All Logs

docker exec integrachat tail -n 100 /app/logs/*.log

Restart Services Inside Container

# Container will auto-restart services, but you can manually restart:
docker restart integrachat

Clean Up

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