ManualTrader/docs/deployment.md

🚀 Deployment Guide

Production deployment options for your trading bot

🎯 Quick Production Start

python trading_bot.py

This single command handles everything:

• ✅ Configuration validation
• ✅ Auto-restart on errors
• ✅ Error notifications to your phone
• ✅ Comprehensive logging
• ✅ Graceful shutdown

🖥️ Deployment Options

Option 1: Screen/Tmux (Simplest)

# Start a detachable session
screen -S trading-bot

# Run the bot
uv run python trading_bot.py

# Detach: Ctrl+A, then D
# Reattach: screen -r trading-bot
# Stop: screen -r trading-bot, then Ctrl+C

Option 2: Systemd Service (Linux)

Create /etc/systemd/system/trading-bot.service:

[Unit]
Description=Hyperliquid Trading Bot
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/ManualTrader
Environment=PATH=/Users/colosseum/.local/bin:/usr/bin:/bin
ExecStart=/Users/colosseum/.local/bin/uv run python trading_bot.py
Restart=always
RestartSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable trading-bot
sudo systemctl start trading-bot

# Check status
sudo systemctl status trading-bot

# View logs
sudo journalctl -u trading-bot -f

Option 3: Docker

FROM python:3.11-slim

WORKDIR /app

# Install uv
ADD https://astral.sh/uv/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin:$PATH"

# Copy project files
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen

COPY . .
CMD ["uv", "run", "python", "trading_bot.py"]

# Build and run
docker build -t trading-bot .
docker run -d --name trading-bot \
  --env-file .env \
  --restart unless-stopped \
  trading-bot

Option 4: PM2 (Node.js Process Manager)

npm install -g pm2

# Start bot with PM2
pm2 start "uv run python trading_bot.py" --name "trading-bot"

# Save configuration
pm2 startup
pm2 save

# Monitor
pm2 status
pm2 logs trading-bot

🛡️ Production Safety

Built-in Safety Features

• Auto-restart - Up to 10 attempts with exponential backoff
• Error notifications - Sent to your Telegram immediately
• Data persistence - Statistics survive crashes and restarts
• Comprehensive logging - Daily log files with error tracking

Additional Monitoring

# Check if bot is running
ps aux | grep "python.*trading_bot"

# Monitor logs in real-time
tail -f logs/trading_bot_$(date +%Y%m%d).log

# Check error log
tail -f logs/bot_errors.log

# View bot status via Telegram
# Send /start to your bot, it shows operational status

Resource Monitoring

# Monitor system resources
htop

# Check disk space (logs can grow)
df -h

# Monitor bot memory usage
ps -p $(pgrep -f trading_bot.py) -o pid,vsz,rss,pcpu,pmem,comm

🔄 Safe Update Process

1. Backup Current State

# Backup your configuration and data
cp .env .env.backup
cp trading_stats.json trading_stats.backup

2. Stop Bot Gracefully

# For screen/tmux: Ctrl+C
# For systemd:
sudo systemctl stop trading-bot

# For Docker:
docker stop trading-bot

# For PM2:
pm2 stop trading-bot

3. Update Code

git pull origin main
# or download new version

4. Test Before Restart

# Validate configuration
uv run python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"

# Quick test (optional)
uv run python utils/simple_bot.py

5. Restart Production

# Screen/tmux: screen -S trading-bot, then uv run python trading_bot.py
# Systemd: sudo systemctl start trading-bot
# Docker: docker start trading-bot
# PM2: pm2 start trading-bot

⚙️ Environment-Specific Configuration

Development

HYPERLIQUID_TESTNET=true
LOG_LEVEL=DEBUG

Staging

HYPERLIQUID_TESTNET=true
LOG_LEVEL=INFO

Production

HYPERLIQUID_TESTNET=false  # REAL MONEY!
LOG_LEVEL=INFO

📊 Performance Tuning

Log Management

# Rotate logs (optional - bot creates daily files)
find logs/ -name "*.log" -mtime +30 -delete

# Compress old logs
gzip logs/trading_bot_$(date -d '1 day ago' +%Y%m%d).log

Resource Limits

The bot is lightweight but you can set limits:

# Systemd service limits
[Service]
MemoryLimit=512M
CPUQuota=50%

🔍 Troubleshooting Production Issues

Bot Not Starting

# Check configuration
python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"

# Check dependencies
pip list | grep -E "hyperliquid|telegram"

# Check permissions
ls -la trading_bot.py

Bot Crashes Repeatedly

# Check error log
tail -20 logs/bot_errors.log

# Check system logs (systemd)
sudo journalctl -u trading-bot --since "1 hour ago"

# Test in foreground
python trading_bot.py

Telegram Not Working

# Test bot token
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# Re-verify Chat ID
python utils/get_telegram_chat_id.py

📈 Best Practices

Security

• Keep .env file permissions restricted: chmod 600 .env
• Regularly rotate API keys
• Monitor unusual trading activity
• Use testnet for development

Monitoring

• Set up alerts for bot downtime
• Monitor trading performance via /stats
• Check logs regularly
• Keep system updated

Data Protection

• Backup trading_stats.json regularly
• Monitor disk space for logs
• Keep multiple backups of configuration

🎯 Quick Commands

# Check bot status
ps aux | grep trading_bot

# View real-time logs
tail -f logs/trading_bot_$(date +%Y%m%d).log

# Stop bot safely (screen/tmux)
screen -r trading-bot
# Then Ctrl+C

# Restart bot
python trading_bot.py

# Check bot health via Telegram
# Send /start to your bot

🔒 HTTPS Setup with Nginx (Recommended)

Why Use Nginx as Reverse Proxy?

• SSL/TLS Termination: Handle HTTPS certificates and encryption
• Load Balancing: Distribute traffic across multiple app instances
• Static File Serving: Serve CSS/JS files efficiently
• Security: Add security headers and rate limiting
• Caching: Cache responses for better performance

1. Install Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx
# or
sudo dnf install nginx

# macOS
brew install nginx

2. Install SSL Certificate (Let's Encrypt - Free)

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Get SSL certificate (replace your-domain.com)
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# Test auto-renewal
sudo certbot renew --dry-run

3. Nginx Configuration

Create /etc/nginx/sites-available/hyperliquid-trading-bot:

# Rate limiting zone
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=auth:10m rate=5r/m;

# Upstream backend servers
upstream trading_bot_backend {
    # Main application server
    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
    
    # Add more servers for load balancing if needed
    # server 127.0.0.1:8081 max_fails=3 fail_timeout=30s;
    
    # Health check
    keepalive 32;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com www.your-domain.com;
    
    # Security headers even for redirects
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    
    # Redirect all HTTP traffic to HTTPS
    return 301 https://$server_name$request_uri;
}

# Main HTTPS server
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name your-domain.com www.your-domain.com;
    
    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/your-domain.com/chain.pem;
    
    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;
    
    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;
    
    # Security Headers
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://cdn.tailwindcss.com; font-src 'self'; img-src 'self' data:; connect-src 'self'" always;
    
    # Gzip Compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml+rss application/atom+xml image/svg+xml;
    
    # Client body size limit (for API requests)
    client_max_body_size 1M;
    
    # Timeouts
    proxy_connect_timeout 30s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;
    
    # Main application proxy
    location / {
        # Rate limiting for general requests
        limit_req zone=api burst=20 nodelay;
        
        # Proxy to backend
        proxy_pass http://trading_bot_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        
        # Disable caching for dynamic content
        proxy_cache_bypass $http_upgrade;
        proxy_no_cache $http_upgrade;
    }
    
    # API endpoints with stricter rate limiting
    location /api/ {
        # Stricter rate limiting for API
        limit_req zone=api burst=10 nodelay;
        
        # Authentication rate limiting
        location ~ ^/api/(auth|login) {
            limit_req zone=auth burst=3 nodelay;
            proxy_pass http://trading_bot_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
        
        proxy_pass http://trading_bot_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # Static files with long caching
    location /static/ {
        proxy_pass http://trading_bot_backend;
        proxy_set_header Host $host;
        
        # Cache static files for 1 year
        expires 1y;
        add_header Cache-Control "public, immutable";
        
        # Optional: Serve directly from filesystem if you extract static files
        # alias /path/to/your/app/src/web/static/;
    }
    
    # Health check endpoint
    location /health {
        proxy_pass http://trading_bot_backend/health;
        proxy_set_header Host $host;
        access_log off;
    }
    
    # Block sensitive files
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
    
    location ~ \.(env|log|config)$ {
        deny all;
        access_log off;
        log_not_found off;
    }
    
    # Custom error pages
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;
    
    # Logging
    access_log /var/log/nginx/hyperliquid-trading-bot.access.log;
    error_log /var/log/nginx/hyperliquid-trading-bot.error.log;
}

4. Enable the Site

# Create symlink to enable site
sudo ln -s /etc/nginx/sites-available/hyperliquid-trading-bot /etc/nginx/sites-enabled/

# Test nginx configuration
sudo nginx -t

# Reload nginx
sudo systemctl reload nginx

# Enable nginx to start on boot
sudo systemctl enable nginx

🔧 Production Environment Configuration

1. Update Environment Variables

Create a production .env file:

# Production API Configuration
HYPERLIQUID_SECRET_KEY=your_production_api_key
HYPERLIQUID_WALLET_ADDRESS=your_production_wallet
HYPERLIQUID_TESTNET=false  # IMPORTANT: Use mainnet for production

# Web UI - Bind to localhost only (nginx will handle external traffic)
WEB_HOST=127.0.0.1
WEB_PORT=8080
WEB_API_KEY=your_very_secure_random_api_key_here

# Strong API key for production
WEB_API_KEY=$(openssl rand -hex 32)

# CORS - Add your domain
WEB_CORS_ORIGINS=https://your-domain.com,https://www.your-domain.com

# Production logging
LOG_LEVEL=INFO
LOG_TO_FILE=true
LOG_FILE_PATH=/var/log/hyperliquid-trading-bot/app.log

# Enhanced security
COPY_TRADING_NOTIFICATIONS=true
TELEGRAM_ENABLED=true

2. Create Log Directory

sudo mkdir -p /var/log/hyperliquid-trading-bot
sudo chown $USER:$USER /var/log/hyperliquid-trading-bot

🎯 Systemd Service (Production Process Management)

Create /etc/systemd/system/hyperliquid-trading-bot.service:

[Unit]
Description=Hyperliquid Trading Bot Web Application
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
Group=ubuntu
WorkingDirectory=/home/ubuntu/hyperliquid-trading-bot
Environment=PATH=/home/ubuntu/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/ubuntu/.local/bin/uv run python web_start.py
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/home/ubuntu/hyperliquid-trading-bot/logs /home/ubuntu/hyperliquid-trading-bot/data /var/log/hyperliquid-trading-bot

# Resource limits
LimitNOFILE=65536
MemoryMax=1G

[Install]
WantedBy=multi-user.target

Enable and Start Service

# Reload systemd
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable hyperliquid-trading-bot

# Start the service
sudo systemctl start hyperliquid-trading-bot

# Check status
sudo systemctl status hyperliquid-trading-bot

# View logs
sudo journalctl -u hyperliquid-trading-bot -f

🔒 Additional Security Measures

1. Firewall Configuration

# Install ufw if not already installed
sudo apt install ufw

# Default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow SSH (adjust port if needed)
sudo ufw allow 22/tcp

# Allow HTTP/HTTPS for nginx
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status verbose

2. Fail2Ban (Protection against brute force)

# Install fail2ban
sudo apt install fail2ban

# Create custom jail for your app
sudo tee /etc/fail2ban/jail.local << EOF
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 5

[nginx-http-auth]
enabled = true
port = http,https
logpath = /var/log/nginx/hyperliquid-trading-bot.error.log

[nginx-limit-req]
enabled = true
port = http,https
logpath = /var/log/nginx/hyperliquid-trading-bot.error.log
maxretry = 10
EOF

# Restart fail2ban
sudo systemctl restart fail2ban

📊 Monitoring and Alerts

1. Log Rotation

# Create logrotate configuration
sudo tee /etc/logrotate.d/hyperliquid-trading-bot << EOF
/var/log/hyperliquid-trading-bot/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    copytruncate
    create 0644 ubuntu ubuntu
}
EOF

2. Health Check Script

Create scripts/health_check.sh:

#!/bin/bash
# Health check script for monitoring

URL="https://your-domain.com/health"
EXPECTED_STATUS=200

response=$(curl -s -o /dev/null -w "%{http_code}" "$URL")

if [ "$response" = "$EXPECTED_STATUS" ]; then
    echo "✅ Health check passed: $response"
    exit 0
else
    echo "❌ Health check failed: $response"
    # Send alert (webhook, email, etc.)
    exit 1
fi

3. Crontab for Monitoring

# Add to crontab (crontab -e)
# Health check every 5 minutes
*/5 * * * * /path/to/your/app/scripts/health_check.sh

# Daily backup
0 2 * * * /path/to/your/backup/script.sh

🚀 Deployment Checklist

• SSL certificate installed and configured
• Nginx configured with security headers
• Firewall rules configured
• Systemd service created and enabled
• Log rotation configured
• Monitoring/health checks setup
• Environment variables updated for production
• API keys secured (not in git)
• Backup strategy implemented
• Rate limiting configured
• Fail2ban configured

🔄 Zero-Downtime Deployment

For updates without service interruption:

# 1. Pull latest changes
git pull origin main

# 2. Install dependencies
uv sync

# 3. Graceful restart
sudo systemctl reload hyperliquid-trading-bot

# 4. Verify deployment
curl -f https://your-domain.com/health

🆘 Troubleshooting

Check Service Status

sudo systemctl status hyperliquid-trading-bot
sudo journalctl -u hyperliquid-trading-bot -n 50

Check Nginx

sudo nginx -t
sudo systemctl status nginx
tail -f /var/log/nginx/hyperliquid-trading-bot.error.log

Check SSL Certificate

sudo certbot certificates
openssl s_client -connect your-domain.com:443 -servername your-domain.com

This setup provides enterprise-grade security and reliability for your production deployment!

Your bot is now production-ready with professional deployment! 🚀🛡️