TradingAgents/Docker-readme.md

🚀 Docker Setup for Trading Agents

This guide provides instructions for running the Trading Agents application within a secure and reproducible Docker environment. Using Docker simplifies setup, manages dependencies, and ensures a consistent experience across different machines.

The recommended method is using docker-compose, which handles the entire stack, including the Ollama server and model downloads.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker
• Docker Compose (usually included with Docker Desktop)

🤔 Which Option Should I Choose?

Feature	OpenAI	Local Ollama
Setup Time	2-5 minutes	15-30 minutes
Cost	~$0.01-0.05 per query	Free after setup
Quality	GPT-4o (excellent)	Depends on model
Privacy	Data sent to OpenAI	Fully private
Internet Required	Yes	No (after setup)
Hardware Requirements	None	4GB+ RAM recommended
Model Downloads	None	Depends on model
Best For	Quick testing, production	Privacy-focused, cost control

💡 Recommendation: Start with OpenAI for quick testing, then switch to Ollama for production if privacy/cost is important.

⚡ Quickstart

Option A: Using OpenAI (Recommended for beginners)

# 1. Clone the repository
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

# 2. Create and configure environment file
cp .env.example .env
# Edit .env: Set LLM_PROVIDER=openai and add your OPENAI_API_KEY

# 3. Build and run with OpenAI
docker compose --profile openai build
docker compose --profile openai run -it app-openai

Option B: Using Local Ollama (Free but requires more setup)

# 1. Clone the repository
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

# 2. Create environment file
cp .env.example .env
# Edit .env: Set LLM_PROVIDER=ollama

# 3. Start Ollama service
docker compose --profile ollama up -d --build

# 4. Initialize models (first time only)
# Linux/macOS:
./init-ollama.sh
# Windows Command Prompt:
init-ollama.bat


# 5. Run the command-line app
docker compose --profile ollama run -it app-ollama

🛠️ Build Methods

Choose your preferred build method:

Method 1: Quick Build (Recommended)

# Standard Docker build
docker build -t trading-agents .

# Or with docker-compose
docker compose build

Method 2: Optimized Build (Advanced)

For faster rebuilds with caching:

Linux/macOS:

# Build with BuildKit optimization
./build.sh

# With testing
./build.sh --test

# Clean cache and rebuild
./build.sh --clean --test

Windows Command Prompt:

REM Build with BuildKit optimization
build.bat

REM With testing
build.bat --test

REM Clean cache and rebuild
build.bat --clean --test

Benefits of Optimized Build:

• ⚡ 60-90% faster rebuilds via BuildKit cache
• 🔄 Automatic fallback to simple build if needed
• 📊 Cache statistics and build info
• 🧪 Built-in testing capabilities

Step-by-Step Instructions

Step 1: Clone the Repository

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

Step 2: Configure Your Environment (.env file)

The application is configured using an environment file. Create your own .env file by copying the provided template.

cp .env.example .env

Option A: OpenAI Configuration (Recommended)

Edit your .env file and set:

# LLM Provider Configuration
LLM_PROVIDER=openai
LLM_BACKEND_URL=https://api.openai.com/v1

# API Keys
OPENAI_API_KEY=your-actual-openai-api-key-here
FINNHUB_API_KEY=your-finnhub-api-key-here

# Agent Configuration
MAX_DEBATE_ROUNDS=1
ONLINE_TOOLS=True

Benefits of OpenAI:

• ✅ No local setup required
• ✅ Higher quality responses (GPT-4o)
• ✅ Faster startup (no model downloads)
• ✅ No GPU/CPU requirements
• ❌ Requires API costs ($0.01-0.05 per query)

Option B: Local Ollama Configuration (Free)

Edit your .env file and set:

# LLM Provider Configuration
LLM_PROVIDER=ollama
LLM_BACKEND_URL=http://ollama:11434/v1

# Local Models
LLM_DEEP_THINK_MODEL=llama3.2
LLM_QUICK_THINK_MODEL=qwen3
LLM_EMBEDDING_MODEL=nomic-embed-text

# API Keys (still need Finnhub for market data)
FINNHUB_API_KEY=your-finnhub-api-key-here

# Agent Configuration
MAX_DEBATE_ROUNDS=1
ONLINE_TOOLS=True

Benefits of Ollama:

• ✅ Completely free after setup
• ✅ Data privacy (runs locally)
• ✅ Works offline
• ❌ Requires initial setup and model downloads
• ❌ Slower responses than cloud APIs

Step 3: Run with Docker Compose

Choose the appropriate method based on your LLM provider configuration:

Option A: Running with OpenAI

# Build the app container
docker compose --profile openai build
# Or use optimized build: ./build.sh

# Test OpenAI connection (optional)
docker compose --profile openai run --rm app-openai python tests/test_openai_connection.py

# Run the trading agents
docker compose --profile openai run -it app-openai

No additional services needed - the app connects directly to OpenAI's API.

Option B: Running with Ollama (CPU)

# Start the Ollama service
docker compose --profile ollama up -d --build
# Or use optimized build: ./build.sh

# Initialize Ollama models (first time only)
# Linux/macOS:
./init-ollama.sh
# Windows Command Prompt:
init-ollama.bat

# Test Ollama connection (optional)
docker compose --profile ollama exec app-ollama python tests/test_ollama_connection.py

# Run the trading agents
docker compose --profile ollama run -it app-ollama

Option C: Running with Ollama (GPU)

First, uncomment the GPU configuration in docker-compose.yml:

# deploy:
#   resources:
#     reservations:
#       devices:
#         - capabilities: ["gpu"]

Then run:

# Start with GPU support
docker compose --profile ollama up -d --build
# Or use optimized build: ./build.sh

# Initialize Ollama models (first time only)
# Linux/macOS:
./init-ollama.sh
# Windows Command Prompt:
init-ollama.bat

# Run the trading agents
docker compose --profile ollama run -it app-ollama

View Logs

To view the application logs in real-time, you can run:

docker compose --profile ollama logs -f

Stop the Containers

To stop and remove the containers:

docker compose --profile ollama down

Step 4: Verify Your Setup (Optional)

For OpenAI Setup:

# Test OpenAI API connection
docker compose --profile openai run --rm app-openai python tests/test_openai_connection.py

# Run a quick trading analysis test
docker compose --profile openai run --rm app-openai python tests/test_setup.py

# Run all tests automatically
docker compose --profile openai run --rm app-openai python tests/run_tests.py

For Ollama Setup:

# Test Ollama connection
docker compose --profile ollama exec app-ollama python tests/test_ollama_connection.py

# Run a quick trading analysis test
docker compose --profile ollama exec app-ollama python tests/test_setup.py

# Run all tests automatically
docker compose --profile ollama exec app-ollama python tests/run_tests.py

Step 5: Model Management (Optional)

View and Manage Models

# List all available models
docker compose --profile ollama exec ollama ollama list

# Check model cache size
du -sh ./ollama_data

# Pull additional models (cached locally)
docker compose --profile ollama exec ollama ollama pull llama3.2

# Remove a model (frees up cache space)
docker compose --profile ollama exec ollama ollama rm model-name

Model Cache Benefits

• Persistence: Models downloaded once are reused across container restarts
• Speed: Subsequent startups are much faster (seconds vs minutes)
• Bandwidth: No need to re-download multi-GB models
• Offline: Once cached, models work without internet connection

Troubleshooting Cache Issues

# If models seem corrupted, clear cache and re-initialize
docker compose --profile ollama down
rm -rf ./ollama_data
docker compose --profile ollama up -d
# Linux/macOS:
./init-ollama.sh
# Windows Command Prompt:
init-ollama.bat

✅ Expected Output:

Testing Ollama connection:
  Backend URL: http://localhost:11434/v1
  Model: qwen3:0.6b
  Embedding Model: nomic-embed-text
✅ Ollama API is responding
✅ Model 'qwen3:0.6b' is available
✅ OpenAI-compatible API is working
   Response: ...

---

Alternative Method: Using docker Only

If you prefer not to use docker-compose, you can build and run the container manually.

1. Build the Docker Image:

# Standard build
docker build -t trading-agents .

# Or optimized build (recommended)
# Linux/macOS:
./build.sh
# Windows Command Prompt:
build.bat

2. Test local ollama setup (Optional): Make sure you have a .env file configured as described in Step 2. If you are using LLM_PROVIDER="ollama", you can verify that the Ollama server is running correctly and has the necessary models.

docker run -it --network host --env-file .env trading-agents python tests/test_ollama_connection.py

for picking environment settings from .env file. You can pass values directly using:

docker run -it --network host \
  -e LLM_PROVIDER="ollama" \
  -e LLM_BACKEND_URL="http://localhost:11434/v1" \
  -e LLM_DEEP_THINK_MODEL="qwen3:0.6b" \
  -e LLM_EMBEDDING_MODEL="nomic-embed-text"\
  trading-agents \
  python tests/test_ollama_connection.py

To prevent re-downloading of Ollama models, mount folder from your host and run as

docker run -it --network host \
  -e LLM_PROVIDER="ollama" \
  -e LLM_BACKEND_URL="http://localhost:11434/v1" \
  -e LLM_DEEP_THINK_MODEL="qwen3:0.6b" \
  -e LLM_EMBEDDING_MODEL="nomic-embed-text"\
  -v ./ollama_cache:/app/.ollama \
  trading-agents \
  python tests/test_ollama_connection.py

3. Run the Docker Container: Make sure you have a .env file configured as described in Step 2.

docker run --rm -it \
  --network host \
  --env-file .env \
  -v ./data:/app/data \
  --name trading-agents \
  trading-agents

4. Run on GPU machine: For running on GPU machine, pass --gpus=all flag to the docker run command:

docker run --rm -it \
  --gpus=all \
  --network host \
  --env-file .env \
  -v ./data:/app/data \
  --name trading-agents \
  trading-agents

Configuration Details

Test Suite Organization

All test scripts are organized in the tests/ directory:

tests/
├── __init__.py                    # Python package initialization
├── run_tests.py                   # Automated test runner
├── test_openai_connection.py      # OpenAI API connectivity tests
├── test_ollama_connection.py      # Ollama connectivity tests
└── test_setup.py                  # General setup and configuration tests

Automated Testing:

# Run all tests automatically (detects provider) - from project root
python tests/run_tests.py

# Run specific test - from project root
python tests/test_openai_connection.py
python tests/test_ollama_connection.py
python tests/test_setup.py

⚠️ Important: When running tests locally (outside Docker), always run from the project root directory, not from inside the tests/ folder. The Docker commands automatically handle this.

Live Reloading

The app directory is mounted as a volume into the container. This means any changes you make to the source code on your local machine will be reflected instantly in the running container without needing to rebuild the image.

Persistent Data & Model Caching

The following volumes are used to persist data between container runs:

• ./data: Stores application data, trading reports, and cached market data
• ./ollama_data: Caches downloaded Ollama models (typically 1-4GB per model)

Model Cache Management

The Ollama models are automatically cached in ./ollama_data/ on your host machine:

• First run: Models are downloaded automatically (may take 5-15 minutes depending on internet speed)
• Subsequent runs: Models are reused from cache, startup is much faster
• Cache location: ./ollama_data/ directory in your project folder
• Cache size: Typically 2-6GB total for the required models

# Check cache size
du -sh ./ollama_data

# Clean cache if needed (will require re-downloading models)
rm -rf ./ollama_data

# List cached models
docker compose --profile ollama exec ollama ollama list

GPU troubleshooting

If you find model is running very slow on GPU machine, make sur you the latest GPU drivers installed and GPU is working fine with docker. Eg you can check for Nvidia GPUs by running:

docker run --rm -it --gpus=all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark

or

nvidia-smi