AI-Trader/docs/DOCKER.md

Docker Deployment Guide

Quick Start

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• API keys for OpenAI, Alpha Vantage, and Jina AI

First-Time Setup

1. Clone repository:

   git clone https://github.com/HKUDS/AI-Trader.git
   cd AI-Trader
   

2. Configure environment:

   cp .env.example .env
   # Edit .env and add your API keys
   

3. Run with Docker Compose:

   docker-compose up
   

That's it! The container will:

• Fetch latest price data from Alpha Vantage
• Start all MCP services
• Run the trading agent with default configuration

Configuration

Environment Variables

Edit .env file with your credentials:

# Required
OPENAI_API_KEY=sk-...
ALPHAADVANTAGE_API_KEY=...
JINA_API_KEY=...

# Optional (defaults shown)
MATH_HTTP_PORT=8000
SEARCH_HTTP_PORT=8001
TRADE_HTTP_PORT=8002
GETPRICE_HTTP_PORT=8003
AGENT_MAX_STEP=30

Custom Trading Configuration

Pass a custom config file:

docker-compose run ai-trader configs/my_config.json

Usage Examples

Run in foreground with logs

docker-compose up

Run in background (detached)

docker-compose up -d
docker-compose logs -f  # Follow logs

Run with custom config

docker-compose run ai-trader configs/custom_config.json

Stop containers

docker-compose down

Rebuild after code changes

docker-compose build
docker-compose up

Data Persistence

Volume Mounts

Docker Compose mounts two volumes:

• ./data:/app/data - Price data and trading records
• ./logs:/app/logs - MCP service logs

Data persists across container restarts. To reset:

docker-compose down
rm -rf data/agent_data/* logs/*
docker-compose up

Backup Trading Data

# Backup
tar -czf ai-trader-backup-$(date +%Y%m%d).tar.gz data/agent_data/

# Restore
tar -xzf ai-trader-backup-YYYYMMDD.tar.gz

Using Pre-built Images

Pull from GitHub Container Registry

docker pull ghcr.io/hkuds/ai-trader:latest

Run without Docker Compose

docker run --env-file .env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -p 8000-8003:8000-8003 \
  ghcr.io/hkuds/ai-trader:latest

Specific version

docker pull ghcr.io/hkuds/ai-trader:v1.0.0

Troubleshooting

MCP Services Not Starting

Symptom: Container exits immediately or errors about ports

Solutions:

• Check ports 8000-8003 not already in use: lsof -i :8000-8003
• View container logs: docker-compose logs
• Check MCP service logs: cat logs/math.log

Missing API Keys

Symptom: Errors about missing environment variables

Solutions:

• Verify .env file exists: ls -la .env
• Check required variables set: grep OPENAI_API_KEY .env
• Ensure .env in same directory as docker-compose.yml

Data Fetch Failures

Symptom: Container exits during data preparation step

Solutions:

• Verify Alpha Vantage API key valid
• Check API rate limits (5 requests/minute for free tier)
• View logs: docker-compose logs | grep "Fetching and merging"

Permission Issues

Symptom: Cannot write to data or logs directories

Solutions:

• Ensure directories writable: chmod -R 755 data logs
• Check volume mount permissions
• May need to create directories first: mkdir -p data logs

Container Keeps Restarting

Symptom: Container restarts repeatedly

Solutions:

• View logs to identify error: docker-compose logs --tail=50
• Disable auto-restart: Comment out restart: unless-stopped in docker-compose.yml
• Check if main.py exits with error

Advanced Usage

Override Entrypoint

Run bash inside container for debugging:

docker-compose run --entrypoint /bin/bash ai-trader

Build Multi-platform Images

For ARM64 (Apple Silicon) and AMD64:

docker buildx build --platform linux/amd64,linux/arm64 -t ai-trader .

View Container Resource Usage

docker stats ai-trader-app

Access MCP Services Directly

Services exposed on host:

• Math: http://localhost:8000
• Search: http://localhost:8001
• Trade: http://localhost:8002
• Price: http://localhost:8003

Development Workflow

Local Code Changes

1. Edit code in project root
2. Rebuild image: docker-compose build
3. Run updated container: docker-compose up

Test Different Configurations

# Create test config
cp configs/default_config.json configs/test_config.json
# Edit test_config.json

# Run with test config
docker-compose run ai-trader configs/test_config.json

Production Deployment

For production use, consider:

1. Use specific version tags instead of latest
2. External secrets management (AWS Secrets Manager, etc.)
3. Health checks in docker-compose.yml
4. Resource limits (CPU/memory)
5. Log aggregation (ELK stack, CloudWatch)
6. Orchestration (Kubernetes, Docker Swarm)

See design document in docs/plans/2025-10-30-docker-deployment-design.md for architecture details.