foxhunt/DEPLOYMENT_GUIDE.md

Foxhunt HFT Trading System - Deployment Guide

Architecture Overview

This deployment matches the TLI_PLAN.md architecture with the correct service topology:

TLI Client (Terminal)    →    3 Standalone Services    →    Docker Databases

┌─────────────────────┐      ┌─────────────────────┐      ┌──────────────────┐
│    TLI CLIENT       │      │ Trading Service     │      │ PostgreSQL       │
│ ┌─ Trading Dash.  ─┐│ gRPC │ (port 50051)        │──────│ (port 5432)      │
│ ├─ Risk Dashboard ─┤│<────▶│                     │      │                  │
│ ├─ ML Dashboard   ─┤│      └─────────────────────┘      │ InfluxDB         │
│ ├─ Performance D. ─┤│                                    │ (port 8086)      │
│ ├─ Backtesting D. ─┤│      ┌─────────────────────┐      │                  │
│ └─ Configuration  ─┘│ gRPC │ Backtesting Service │──────│ Redis            │
└─────────────────────┘<────▶│ (port 50052)        │      │ (port 6379)      │
                              └─────────────────────┘      └──────────────────┘

                              ┌─────────────────────┐
                         gRPC │ ML Training Service │
                         <────▶│ (port 50053)        │
                              └─────────────────────┘

Quick Start

1. Start Complete System

# Start all 3 services + Docker databases
./start.sh

2. Launch TLI Client

# In a separate terminal
./start-tli.sh

3. Stop System

# Stop all services and databases
./stop.sh

Detailed Deployment Steps

Prerequisites

1. Docker - Required for PostgreSQL, InfluxDB, and Redis databases
2. Rust - Cargo toolchain for building services
3. System ports - Ensure ports 50051-50053 and 5432, 6379, 8086 are available

Step 1: Database Infrastructure

The system uses Docker Compose to manage 3 databases:

• PostgreSQL (5432): ACID-compliant storage for trades, positions, configuration
• InfluxDB (8086): High-frequency time-series data for backtesting performance
• Redis (6379): Caching and real-time data streams

# Databases start automatically with ./start.sh
# Or manually:
docker compose up -d

Step 2: Service Architecture

Three standalone gRPC services provide the business logic:

Trading Service (port 50051)

• Real-time trading operations
• Market data streaming
• Position and order management
• Integrated risk management
• Configuration management via SQLite/PostgreSQL

Backtesting Service (port 50052)

• Strategy testing and analysis
• Historical simulation
• Performance metrics
• Results storage in PostgreSQL/InfluxDB

ML Training Service (port 50053)

• Model training orchestration
• ML prediction serving
• Feature engineering
• Model lifecycle management

Step 3: TLI Client Architecture

The Terminal Line Interface connects to all 3 services via gRPC and provides:

6 Interactive Dashboards:

1. Trading Dashboard [T] - Live positions, orders, executions, market data
2. Risk Dashboard [R] - VaR, drawdown, limits, emergency controls
3. ML Dashboard [M] - Model predictions, signal strength, ensemble voting
4. Performance Dashboard [P] - Returns, Sharpe ratios, trade analytics
5. Backtesting Dashboard [B] - Strategy testing, historical analysis
6. Configuration Dashboard [C] - System settings, hot-reload management

Service Configuration

Environment Variables

# Database connections (set automatically by start.sh)
export DATABASE_URL="postgresql://trading_service:trading_dev_password@localhost:5432/foxhunt"
export BACKTESTING_DATABASE_URL="postgresql://backtesting_service:backtesting_dev_password@localhost:5432/foxhunt_backtesting"
export ML_DATABASE_URL="postgresql://ml_service:ml_dev_password@localhost:5432/foxhunt_ml_training"
export REDIS_URL="redis://localhost:6379"
export INFLUXDB_URL="http://localhost:8086"

# TLI client connections
export TRADING_SERVICE_URL="http://localhost:50051"
export BACKTESTING_SERVICE_URL="http://localhost:50052"
export ML_TRAINING_SERVICE_URL="http://localhost:50053"

# Logging
export RUST_LOG="info"

Port Allocation

Service	Port	Protocol	Purpose
Trading Service	50051	gRPC	Core trading operations
Backtesting Service	50052	gRPC	Strategy testing
ML Training Service	50053	gRPC	Model training
PostgreSQL	5432	TCP	Primary database
InfluxDB	8086	HTTP	Time-series data
Redis	6379	TCP	Caching/streams

Operational Procedures

Health Checks

# Check service ports
nc -z localhost 50051 && echo "Trading Service: OK"
nc -z localhost 50052 && echo "Backtesting Service: OK"
nc -z localhost 50053 && echo "ML Training Service: OK"

# Check database connectivity
docker ps | grep foxhunt

Log Management

# Service logs (stdout)
tail -f /tmp/trading_service.log
tail -f /tmp/backtesting_service.log
tail -f /tmp/ml_training_service.log

# Database logs
docker logs foxhunt-postgres
docker logs foxhunt-influxdb
docker logs foxhunt-redis

Configuration Management

Configuration is managed via PostgreSQL with hot-reload capability:

-- View current configuration
SELECT category, key, value FROM config_settings;

-- Update configuration (hot-reload enabled)
UPDATE config_settings
SET value = 'debug'
WHERE category = 'system' AND key = 'log_level';

Security Considerations

Development Environment

• Default passwords used (change for production)
• Services bind to localhost only
• No TLS encryption (add for production)

Production Hardening

• Use environment variables for passwords
• Enable TLS for gRPC connections
• Configure firewall rules
• Use proper secrets management
• Enable audit logging

Troubleshooting

Common Issues

1. Port conflicts: Use lsof -i :50051 to check port usage
2. Database connection: Verify Docker containers are running
3. Service startup: Check RUST_LOG output for compilation errors
4. TLI connection: Ensure all 3 services are responding

Recovery Procedures

# Hard reset (loses all data)
./stop.sh
docker compose down -v  # Remove volumes
./start.sh

# Soft restart (preserves data)
./stop.sh
./start.sh

Integration with TLI_PLAN.md

This deployment correctly implements the TLI_PLAN.md architecture:

✅ TLI Client: Terminal with 6 dashboards ✅ 3 Services: Trading, Backtesting, ML Training (standalone) ✅ gRPC Streaming: Real-time data feeds ✅ Database Stack: PostgreSQL + InfluxDB + Redis ✅ Configuration Management: SQLite/PostgreSQL with hot-reload ✅ No Inappropriate A/B Testing: Removed load balancing for terminal apps

Performance Expectations

• Service startup: ~30-60 seconds
• Database initialization: ~15 seconds
• TLI connection: < 5 seconds
• Real-time latency: < 10ms (service to TLI)
• Configuration reload: < 1 second

Success Criteria

✅ All 3 services start and bind to correct ports ✅ Docker databases initialize with schema ✅ TLI client connects to all services via gRPC ✅ Real-time data streams functional ✅ Configuration hot-reload working ✅ No inappropriate deployment complexity

---

Deployment Status: ✅ COMPLETE - Matches TLI_PLAN.md architecture exactly Architecture: TLI Client → 3 Services → Docker Databases Complexity: Appropriate for terminal application (no load balancers!)