trading-algo/DOCKER_DEPLOYMENT.md

# Docker Deployment Guide

This guide covers deploying the trading system for 24/7 operation using Docker.

## 🚀 Quick Start

### 1. Setup Environment
```bash
# Copy environment template
cp .env.production .env

# Edit with your API keys
nano .env
```

### 2. Deploy the System
```bash
# Start the trading system
./deploy.sh start

# View logs
./deploy.sh logs live

# Check status
./deploy.sh status
```

## 📋 Deployment Options

### Paper Trading (Recommended)
```bash
# Safe paper trading mode
./deploy.sh start
```

### Live Trading (Advanced)
```bash
# Edit .env file first
TRADING_MODE=live

# Deploy with extreme caution
./deploy.sh start
```

## 🐳 Docker Architecture

### Services

1. **trading-bot**: Main trading application
   - Runs 24/7 with auto-restart
   - Health monitoring every 60 seconds
   - Resource limits for safety

2. **monitoring**: Optional monitoring service
   - Displays system status every 5 minutes
   - Shows recent performance and trades
   - Lightweight Alpine Linux container

### Volumes

- `./logs:/app/logs` - Persistent log storage
- `./config:/app/config:ro` - Read-only configuration

### Security Features

- Non-root user (trader:1000)
- Resource limits (512MB RAM, 0.5 CPU)
- Read-only configuration mounting
- Environment-based secrets

## 🛡️ Safety Features

### Health Monitoring
- Container health checks every 60 seconds
- Application health checks every 5 minutes
- Automatic restart on failure

### Risk Management
- Paper trading by default
- Resource constraints
- Graceful shutdown handling
- Comprehensive error logging

### Backup & Recovery
```bash
# Create backup
./deploy.sh backup

# View backups
ls backups/
```

## 📊 Monitoring & Logs

### Real-time Monitoring
```bash
# Follow live logs
./deploy.sh logs live

# System status
./deploy.sh status

# Container status
docker compose ps
```

### Log Files
- `logs/trading.log` - General system logs
- `logs/trades.log` - Trade execution details
- `logs/risk.log` - Risk management events
- `logs/performance.log` - Performance metrics

### Health Endpoints
- Health file: `/tmp/health` (inside container)
- Status format: `OK:timestamp:price`

## 🔧 Management Commands

### Deployment Script (`deploy.sh`)
```bash
./deploy.sh start    # Start system
./deploy.sh stop     # Stop system
./deploy.sh restart  # Restart system
./deploy.sh logs     # Show recent logs
./deploy.sh logs live # Follow live logs
./deploy.sh status   # System status
./deploy.sh backup   # Create backup
./deploy.sh update   # Update and restart
```

### Docker Compose Commands
```bash
# Manual control
docker compose up -d    # Start services
docker compose down     # Stop services
docker compose logs -f  # Follow logs
docker compose ps       # Service status

# Rebuild containers
docker compose build --no-cache
```

## 🔄 Updates & Maintenance

### Updating the System
```bash
# Automated update (with backup)
./deploy.sh update

# Manual update
docker compose down
git pull  # if using git
docker compose build --no-cache
docker compose up -d
```

### Configuration Changes
```bash
# Edit configuration
nano .env

# Restart to apply changes
./deploy.sh restart
```

### Log Rotation
Logs are automatically managed by Docker. To manually clean:
```bash
# Clean old logs (be careful!)
docker system prune -f

# Or manually rotate logs
./deploy.sh backup  # Backup first
> logs/trading.log
> logs/trades.log
```

## 🚨 Troubleshooting

### Common Issues

1. **Container won't start**
   ```bash
   # Check logs
   docker compose logs trading-bot
   
   # Verify environment
   cat .env
   
   # Test configuration
   docker compose config
   ```

2. **API connection errors**
   ```bash
   # Verify API keys in .env
   grep -E "ALPACA_(API|SECRET)_KEY" .env
   
   # Test connection
   docker exec trading-system python3 -c "from src.data_handler import DataHandler; print(DataHandler().get_latest_price('ETH/USD'))"
   ```

3. **Health check failures**
   ```bash
   # Check health status
   docker inspect trading-system | grep -A 5 Health
   
   # Manual health check
   docker exec trading-system python3 -c "from main import health_check; print(health_check())"
   ```

4. **Performance issues**
   ```bash
   # Check resource usage
   docker stats trading-system
   
   # Increase limits in docker compose.yml
   nano docker compose.yml
   ```

### Emergency Procedures

1. **Immediate stop**
   ```bash
   ./deploy.sh stop
   # or
   docker kill trading-system
   ```

2. **Emergency backup**
   ```bash
   ./deploy.sh backup
   cp -r logs backups/emergency_backup_$(date +%Y%m%d_%H%M%S)/
   ```

3. **Reset system**
   ```bash
   ./deploy.sh stop
   docker compose down -v  # WARNING: Removes volumes
   ./deploy.sh start
   ```

## 🌐 Production Considerations

### Server Requirements
- **Minimum**: 1 CPU, 1GB RAM, 10GB storage
- **Recommended**: 2 CPU, 2GB RAM, 50GB storage
- **OS**: Linux (Ubuntu 20.04+ recommended)

### Network Requirements
- Stable internet connection
- HTTPS access to Alpaca API
- NTP for accurate timestamps

### Security Best Practices
1. Use paper trading initially
2. Limit server access (SSH keys only)
3. Regular backups to external storage
4. Monitor logs for anomalies
5. Keep system updated

### Scaling Considerations
- Multiple symbols: Use separate containers
- High frequency: Increase resource limits
- Redundancy: Deploy across multiple servers

## 📞 Support

### Getting Help
1. Check logs: `./deploy.sh logs`
2. Verify configuration: `docker compose config`
3. Test health: `./deploy.sh status`
4. Review documentation

### Important Notes
- Always test in paper trading first
- Monitor performance regularly
- Keep backups of profitable configurations
- Never disable risk management features

## 🔒 Disclaimer

This deployment setup is for educational purposes. Trading involves risk of loss. Always:
- Use paper trading for testing
- Understand the risks involved
- Never trade more than you can afford to lose
- Monitor the system regularly
- Keep security best practices