Skip to content

Docker Setup

Guide for running TradAI services with Docker.

Prerequisites

  • Docker: 20.10+ (Install Guide)
  • Docker Compose: 2.0+ (included with Docker Desktop)
  • ~8GB RAM available for Docker

Quick Start

# Clone repository
git clone https://github.com/tradai-bot/tradai-uv.git
cd tradai-uv

# Copy environment files
cp .env.example .env
cp services/backend/.env.example services/backend/.env
cp services/data-collection/.env.example services/data-collection/.env
cp services/strategy-service/.env.example services/strategy-service/.env

# Start services
just up

# View logs
docker compose logs -f

# Stop services
just down

Docker Compose Services

Core Services

Service Port Description
backend 8000 API Gateway
data-collection 8002 Market data sync
strategy-service 8003 Strategy execution
mlflow 5001 ML experiment tracking

Infrastructure

Service Port Description
postgres 5432 MLflow backend store
localstack 4566 Local AWS services

Configuration

Environment Files

.env                           # Shared config
services/backend/.env          # Backend-specific
services/data-collection/.env  # Data collection-specific
services/strategy-service/.env # Strategy service-specific

Docker Network

All services communicate via the tradai_default network:

# Internal service URLs
BACKEND_DATA_COLLECTION_URL=http://data-collection:8002
BACKEND_STRATEGY_SERVICE_URL=http://strategy-service:8003
MLFLOW_TRACKING_URI=http://mlflow:5000

Building Images

Build All Services

# Build all images
docker compose build

# Build specific service
docker compose build backend

# Build with no cache
docker compose build --no-cache

Multi-Stage Builds

Our Dockerfiles use multi-stage builds for optimal image size:

# Stage 1: Build dependencies
FROM python:3.11-slim as builder
WORKDIR /build
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen

# Stage 2: Runtime image
FROM python:3.11-slim as runtime
COPY --from=builder /build/.venv /app/.venv
COPY src/ /app/src/
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "tradai.backend"]

Image Tags

# Tag for development
TAG=dev docker compose build

# Tag for production
TAG=v1.0.0 docker compose build

Volume Mounts

Development Volumes

For hot-reloading during development:

volumes:
  - ./services/backend/src:/app/src:cached
  - ./libs:/app/libs:cached

Data Persistence

volumes:
  postgres_data:    # MLflow database
  mlflow_artifacts: # ML artifacts
  localstack_data:  # LocalStack state

Clear Volumes

# Remove all volumes (WARNING: deletes data)
docker compose down -v

# Remove specific volume
docker volume rm tradai_postgres_data

LocalStack (Local AWS)

LocalStack provides local AWS service emulation.

Supported Services

  • S3: ArcticDB storage, config files
  • SQS: Backtest job queues
  • DynamoDB: State tracking
  • Secrets Manager: Credentials (dev only)

Configuration

# services/data-collection/.env
DATA_COLLECTION_ARCTIC_S3_ENDPOINT=localstack:4566
DATA_COLLECTION_ARCTIC_USE_SSL=false
DATA_COLLECTION_ARCTIC_USE_VIRTUAL_ADDRESSING=false
DATA_COLLECTION_ARCTIC_ACCESS_KEY=test
DATA_COLLECTION_ARCTIC_SECRET_KEY=test

Verify LocalStack

# List S3 buckets
aws --endpoint-url=http://localhost:4566 s3 ls

# Create bucket
aws --endpoint-url=http://localhost:4566 s3 mb s3://tradai-dev

Health Checks

Service Health

# Check backend health
curl http://localhost:8000/health

# Check all services
for port in 8000 8002 8003 5001; do
  echo "Port $port: $(curl -s http://localhost:$port/health | jq -r '.status')"
done

Docker Health Status

# View container health
docker compose ps

# Detailed health info
docker inspect --format='{{json .State.Health}}' tradai-backend-1 | jq

Logging

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend

# Last 100 lines
docker compose logs --tail=100 backend

# Since timestamp
docker compose logs --since="2024-01-01T00:00:00" backend

Log Levels

# Set in .env
BACKEND_LOG_LEVEL=DEBUG

Debugging

Shell Access

# Open shell in running container
docker compose exec backend bash

# Run one-off container
docker compose run --rm backend bash

Python REPL

# Interactive Python with project context
docker compose exec backend python -c "
from tradai.common import ExchangeConfig, TradingMode
config = ExchangeConfig(name='binance', trading_mode=TradingMode.FUTURES)
print(config)
"

Debug Mode

# Enable debug mode
BACKEND_DEBUG=true docker compose up backend

Common Issues

Port Conflicts

# Check what's using a port
lsof -i :8000

# Use different ports
BACKEND_PORT=8080 docker compose up backend

Permission Issues

# Fix volume permissions
sudo chown -R $USER:$USER ./data

Memory Issues

# Increase Docker memory limit
# Docker Desktop > Settings > Resources > Memory: 8GB

# Check container memory usage
docker stats

Container Won't Start

# View container logs
docker compose logs backend

# Check container status
docker compose ps -a

# Rebuild from scratch
docker compose down -v
docker compose build --no-cache
docker compose up

Production Docker

ECR Push

# Login to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Tag and push
docker tag tradai-backend:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/tradai-backend:v1.0.0
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/tradai-backend:v1.0.0

Security Best Practices

  1. Non-root user: Run containers as non-root
  2. Read-only filesystem: Use read_only: true where possible
  3. No secrets in images: Use environment variables or Secrets Manager
  4. Minimal base images: Use -slim or distroless images
  5. Security scanning: Use docker scan or Trivy

See Also