trading_bot_v4/DOCKER.md

Trading Bot v4 - Docker Deployment Guide

Complete guide for containerized deployment with Docker and Docker Compose.

---

📋 Table of Contents

1. Quick Start
2. Production Deployment
3. Development Setup
4. Configuration
5. Docker Commands
6. Troubleshooting
7. Best Practices

---

🚀 Quick Start

Prerequisites

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker-compose --version

Minimal Setup (Production)

# 1. Navigate to v4 directory
cd v4

# 2. Create .env file from template
cp .env.example .env

# 3. Edit .env with your credentials
nano .env  # or vim, code, etc.

# 4. Build and start
docker-compose up -d

# 5. View logs
docker-compose logs -f trading-bot

# 6. Check status
docker-compose ps

---

🏭 Production Deployment

Step 1: Prepare Environment

cd v4

# Create production .env file
cp .env.example .env

# Edit required fields (minimum required)
DRIFT_WALLET_PRIVATE_KEY=your_base58_private_key
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
API_SECRET_KEY=$(openssl rand -hex 32)
PYTH_HERMES_URL=https://hermes.pyth.network

# Trading config (safe defaults)
MAX_POSITION_SIZE_USD=50
LEVERAGE=10
DRY_RUN=false

# Database password (if using PostgreSQL)
POSTGRES_PASSWORD=$(openssl rand -hex 16)

Step 2: Build Image

# Build with cache
docker-compose build

# Build without cache (clean build)
docker-compose build --no-cache

# Build with progress output
docker-compose build --progress=plain

Step 3: Start Services

# Start all services in background
docker-compose up -d

# Start specific service
docker-compose up -d trading-bot

# Start with recreation (force restart)
docker-compose up -d --force-recreate

Step 4: Verify Deployment

# Check running containers
docker-compose ps

# View logs
docker-compose logs -f trading-bot

# Check health
docker-compose exec trading-bot wget -qO- http://localhost:3000/api/health

# Test API
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/trading/positions

Step 5: Monitor

# Follow logs in real-time
docker-compose logs -f

# View resource usage
docker stats

# Check container details
docker inspect trading-bot-v4

---

🔧 Development Setup

Hot Reload Development

cd v4

# Create dev .env
cp .env.example .env

# Set to devnet for safety
echo "DRIFT_ENV=devnet" >> .env
echo "DRY_RUN=true" >> .env
echo "MAX_POSITION_SIZE_USD=10" >> .env

# Start development container
docker-compose -f docker-compose.dev.yml up

# Rebuild on code changes
docker-compose -f docker-compose.dev.yml up --build

Debug Mode

# Start with Node.js debugger
docker-compose -f docker-compose.dev.yml up

# Attach debugger in VS Code:
# 1. Open Debug panel (Ctrl+Shift+D)
# 2. Select "Attach to Docker"
# 3. Set breakpoints
# 4. Start debugging

# Or use Chrome DevTools:
# Open: chrome://inspect
# Click: "Configure" → Add localhost:9229

Run Tests in Container

# Execute tests
docker-compose exec trading-bot npm test

# Run specific test
docker-compose exec trading-bot npx tsx v4/test-price-monitor.ts

# Shell access for manual testing
docker-compose exec trading-bot sh

---

⚙️ Configuration

Environment Variables

Create .env file in v4/ directory:

# Required
DRIFT_WALLET_PRIVATE_KEY=your_key
SOLANA_RPC_URL=your_rpc
API_SECRET_KEY=your_secret

# Optional overrides
MAX_POSITION_SIZE_USD=50
LEVERAGE=10
LOG_LEVEL=info

See .env.example for complete list.

Docker Compose Override

Create docker-compose.override.yml for local customizations:

version: '3.9'

services:
  trading-bot:
    ports:
      - "3001:3000"  # Use different port
    environment:
      LOG_LEVEL: debug  # More verbose logging
    volumes:
      - ./custom-config:/app/config  # Custom config directory

Resource Limits

Edit docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '2'        # Max 2 CPU cores
      memory: 2G       # Max 2GB RAM
    reservations:
      cpus: '1'        # Reserve 1 core
      memory: 1G       # Reserve 1GB

---

🎮 Docker Commands Reference

Container Management

# Start services
docker-compose up -d

# Stop services
docker-compose stop

# Stop and remove containers
docker-compose down

# Restart specific service
docker-compose restart trading-bot

# View container status
docker-compose ps

# View resource usage
docker stats trading-bot-v4

Logs & Debugging

# View all logs
docker-compose logs

# Follow logs in real-time
docker-compose logs -f trading-bot

# Last 100 lines
docker-compose logs --tail=100 trading-bot

# Logs since timestamp
docker-compose logs --since 2024-10-23T10:00:00

# Shell access
docker-compose exec trading-bot sh

# Run command in container
docker-compose exec trading-bot node -v

Database Operations

# Access PostgreSQL CLI
docker-compose exec postgres psql -U postgres -d trading_bot_v4

# Backup database
docker-compose exec postgres pg_dump -U postgres trading_bot_v4 > backup.sql

# Restore database
docker-compose exec -T postgres psql -U postgres trading_bot_v4 < backup.sql

# View database logs
docker-compose logs postgres

Cleanup

# Stop and remove containers
docker-compose down

# Remove containers and volumes
docker-compose down -v

# Remove everything including images
docker-compose down --rmi all -v

# Clean up unused Docker resources
docker system prune -a

Image Management

# Build image
docker-compose build

# Rebuild without cache
docker-compose build --no-cache

# Pull latest base images
docker-compose pull

# View images
docker images | grep trading-bot

# Remove old images
docker rmi trading-bot-v4:old

---

🔍 Troubleshooting

Container Won't Start

# Check logs for errors
docker-compose logs trading-bot

# Verify environment variables
docker-compose config

# Check if port is already in use
sudo lsof -i :3000

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

Connection Issues

# Test internal network
docker-compose exec trading-bot ping postgres

# Check exposed ports
docker-compose port trading-bot 3000

# Verify RPC connection
docker-compose exec trading-bot wget -qO- $SOLANA_RPC_URL

# Test Pyth connection
docker-compose exec trading-bot wget -qO- https://hermes.pyth.network

Performance Issues

# Check resource usage
docker stats

# View container processes
docker top trading-bot-v4

# Increase resources in docker-compose.yml
deploy:
  resources:
    limits:
      cpus: '2'
      memory: 2G

# Restart with new limits
docker-compose up -d

Database Issues

# Check database health
docker-compose exec postgres pg_isready

# View database connections
docker-compose exec postgres psql -U postgres -c "SELECT * FROM pg_stat_activity"

# Reset database
docker-compose down -v postgres
docker-compose up -d postgres

Permission Issues

# Fix volume permissions
sudo chown -R 1001:1001 ./logs
sudo chmod -R 755 ./logs

# Run as root (not recommended)
docker-compose run --user root trading-bot sh

---

✅ Best Practices

Security

1. Never commit .env files

   echo ".env" >> .gitignore
   echo ".env.*" >> .gitignore
   

2. Use secrets for sensitive data

   services:
     trading-bot:
       secrets:
         - drift_private_key
   
   secrets:
     drift_private_key:
       file: ./secrets/drift_key.txt
   

3. Run as non-root user (already configured in Dockerfile)

4. Limit container capabilities

   cap_drop:
     - ALL
   cap_add:
     - NET_BIND_SERVICE
   

Performance

1. Use multi-stage builds (already configured)

2. Mount volumes for persistence

   volumes:
     - ./logs:/app/logs
     - postgres-data:/var/lib/postgresql/data
   

3. Set resource limits

   deploy:
     resources:
       limits:
         memory: 1G
   

4. Use BuildKit for faster builds

   DOCKER_BUILDKIT=1 docker-compose build
   

Monitoring

1. Health checks (already configured)

2. Log rotation

   logging:
     driver: "json-file"
     options:
       max-size: "10m"
       max-file: "3"
   

3. Metrics collection

   # Export container metrics
   docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
   

Deployment

1. Use tagged images

   docker tag trading-bot-v4:latest trading-bot-v4:1.0.0
   

2. Automated backups

   # Backup script
   docker-compose exec postgres pg_dump -U postgres trading_bot_v4 | \
     gzip > backup-$(date +%Y%m%d).sql.gz
   

3. Blue-green deployment

   # Start new version on different port
   docker-compose -f docker-compose.blue.yml up -d
   
   # Test new version
   curl http://localhost:3001/api/health
   
   # Switch traffic (nginx/traefik)
   # Stop old version
   docker-compose -f docker-compose.green.yml down
   

---

🔗 Additional Resources

• Docker Docs: https://docs.docker.com
• Docker Compose: https://docs.docker.com/compose
• Node.js Docker: https://nodejs.org/en/docs/guides/nodejs-docker-webapp
• Next.js Docker: https://nextjs.org/docs/deployment#docker-image

---

📞 Support

For issues specific to:

• Docker setup: Check this guide first
• Trading bot: See ../TRADING_BOT_V4_MANUAL.md
• Phase 2 features: See PHASE_2_COMPLETE.md
• Testing: See TESTING.md

---

Ready to deploy! 🚀