AI-Trader/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-Server.git
   cd AI-Trader-Server
   

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-server configs/other.json
3. configs/default_config.json (fallback)

Advanced: Use a different config file name:

docker-compose run ai-trader-server configs/my_special_config.json

Custom Configuration via Volume Mount

The Docker image includes a default configuration at configs/default_config.json. You can override sections of this config by mounting a custom config file.

Volume mount:

volumes:
  - ./my-configs:/app/user-configs  # Contains config.json

Custom config example (./my-configs/config.json):

{
  "models": [
    {
      "name": "gpt-5",
      "basemodel": "openai/gpt-5",
      "signature": "gpt-5",
      "enabled": true
    }
  ]
}

This overrides only the models section. All other settings (agent_config, log_config, etc.) are inherited from the default config.

Validation: Config is validated at container startup. Invalid configs cause immediate exit with detailed error messages.

Complete config: You can also provide a complete config that replaces all default values:

{
  "agent_type": "BaseAgent",
  "date_range": {
    "init_date": "2025-10-01",
    "end_date": "2025-10-31"
  },
  "models": [...],
  "agent_config": {...},
  "log_config": {...}
}

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-server 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 for persistent data. By default, these are stored in the project directory:

• ./data:/app/data - Price data and trading records
• ./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/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/*
docker-compose up

Backup Trading Data

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

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

Using Pre-built Images

Pull from GitHub Container Registry

docker pull ghcr.io/xe138/ai-trader-server:latest

Run without Docker Compose

docker run --env-file .env \
  -v $(pwd)/data:/app/data \
  -p 8080:8080 \
  ghcr.io/xe138/ai-trader-server:latest

Specific version

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

Troubleshooting

MCP Services Not Starting

Symptom: Container exits immediately or errors about ports

Solutions:

• View container logs: docker-compose logs
• Check if API port 8080 is already in use: lsof -i :8080
• Verify MCP services started by checking Docker logs for service startup messages

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 directory

Solutions:

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

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-server

Build Multi-platform Images

For ARM64 (Apple Silicon) and AMD64:

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

View Container Resource Usage

docker stats ai-trader-server

Access API Directly

API server exposed on host:

• REST API: http://localhost:8080

MCP services run internally and are not exposed to the host.

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-server configs/conservative.json

# Test aggressive strategy
docker-compose run ai-trader-server 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.