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/Xe138/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

Simple Method (Recommended):

Create a configs/custom_config.json file - it will be automatically used:

# Copy default config as starting point
cp configs/default_config.json configs/custom_config.json

# Edit your custom config
nano configs/custom_config.json

# Run normally - custom_config.json is automatically detected!
docker-compose up

Priority order:

1. configs/custom_config.json (if exists) - Highest priority
2. Command-line argument: docker-compose run ai-trader configs/other.json
3. configs/default_config.json (fallback)

Advanced: Use a different config file name:

docker-compose run ai-trader configs/my_special_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 three volumes for persistent data. By default, these are stored in the project directory:

• ./data:/app/data - Price data and trading records
• ./logs:/app/logs - MCP service logs
• ./configs:/app/configs - Configuration files (allows editing configs without rebuilding)

Custom Volume Location

You can change where data is stored by setting VOLUME_PATH in your .env file:

# Store data in a different location
VOLUME_PATH=/home/user/trading-data

# Or use a relative path
VOLUME_PATH=./volumes

This will store data in:

• /home/user/trading-data/data/
• /home/user/trading-data/logs/
• /home/user/trading-data/configs/

Note: The directory structure is automatically created. You'll need to copy your existing configs:

# After changing VOLUME_PATH
mkdir -p /home/user/trading-data/configs
cp configs/custom_config.json /home/user/trading-data/configs/

Reset Data

To reset all trading data:

docker-compose down
rm -rf ${VOLUME_PATH:-.}/data/agent_data/* ${VOLUME_PATH:-.}/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

Method 1: Use the standard custom_config.json

# Create and edit your config
cp configs/default_config.json configs/custom_config.json
nano configs/custom_config.json

# Run - automatically uses custom_config.json
docker-compose up

Method 2: Test multiple configs with different names

# Create multiple test configs
cp configs/default_config.json configs/conservative.json
cp configs/default_config.json configs/aggressive.json

# Edit each config...

# Test conservative strategy
docker-compose run ai-trader configs/conservative.json

# Test aggressive strategy
docker-compose run ai-trader configs/aggressive.json

Method 3: Temporarily switch configs

# Temporarily rename your custom config
mv configs/custom_config.json configs/custom_config.json.backup
cp configs/test_strategy.json configs/custom_config.json

# Run with test strategy
docker-compose up

# Restore original
mv configs/custom_config.json.backup configs/custom_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.