# Ubuntu Server Deployment Guide

This guide covers deploying the RSC Revolution Market Analytics system on Ubuntu Server.

## Prerequisites

- Ubuntu Server 18.04+ (tested on 20.04/22.04)
- Python 3.8+ (comes with Ubuntu 20.04+)
- MySQL/MariaDB access to RSC Revolution database
- SSH access to Ubuntu server

## Quick Start

```bash
# 1. Install dependencies
sudo apt update
sudo apt install python3 python3-pip git

# 2. Clone repository
git clone <your-repo-url> market_analytics
cd market_analytics

# 3. Install Python packages
pip3 install -r requirements.txt

# 4. Configure environment
cp .env.example .env
nano .env  # Edit database credentials

# 5. Test installation
python3 tests/test_quick.py

# 6. Setup automated collection
chmod +x setup_cron_template.sh
./setup_cron_template.sh
```

## Detailed Installation

### 1. System Setup

```bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages (MariaDB-safe)
sudo apt install -y python3 python3-pip python3-venv git

# Create dedicated user and project directory
# Option 1: Standard user directory
sudo useradd -m -s /bin/bash analytics
sudo su - analytics

# Option 2: System directory (recommended for production)
# sudo mkdir -p /opt/market_analytics
# sudo useradd --system --home /opt/market_analytics analytics
# sudo chown analytics:analytics /opt/market_analytics
# sudo su - analytics
```

### 2. Application Setup

```bash
# Clone repository (adapt path based on your choice above)
# For /home/analytics:
cd ~
git clone <your-repo-url> market_analytics
cd market_analytics

# For /opt/market_analytics:
# cd /opt/market_analytics
# git clone <your-repo-url> .
# (note the dot to clone into current directory)

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip3 install -r requirements.txt
```

### 3. Configuration

```bash
# Copy and edit environment file
cp .env.example .env
nano .env
```

Update `.env` with your database credentials:
```env
DB_HOST=your-mysql-host
DB_USER=your-mysql-user
DB_PASSWORD=your-mysql-password
DB_NAME=rscs_main
```

### 4. Verify Installation

```bash
# Quick smoke test
python3 tests/test_quick.py

# Comprehensive system test
python3 tests/test_essential.py

# Production readiness test
python3 tests/test_deployment.py
```

### 5. Setup Automated Collection

Use the dynamic cron setup script that automatically detects your project location:

```bash
# The setup_cron_template.sh script automatically:
# - Detects project directory (works in any location)
# - Finds Python executable (system or virtual environment)
# - Sets up all required cron jobs

chmod +x setup_cron_template.sh
./setup_cron_template.sh
```

This replaces the old manual cron setup and works whether you installed in `/home/analytics`, `/opt/market_analytics`, or any other directory.

### 6. Create Log Directory

```bash
mkdir -p logs
touch logs/cron.log logs/health.log logs/maintenance.log
```

## System Service Setup (Optional)

For more robust deployment, create a systemd service (update paths as needed):

```bash
# Replace PROJECT_DIR with your actual path:
# /home/analytics/market_analytics OR /opt/market_analytics
PROJECT_DIR="/opt/market_analytics"  # Update this path

# Create service file
sudo tee /etc/systemd/system/market-analytics.service > /dev/null << EOF
[Unit]
Description=RSC Revolution Market Analytics
After=network.target mysql.service mariadb.service

[Service]
Type=oneshot
User=analytics
WorkingDirectory=${PROJECT_DIR}
ExecStart=/usr/bin/python3 collectors/current_state.py
StandardOutput=append:${PROJECT_DIR}/logs/service.log
StandardError=append:${PROJECT_DIR}/logs/service.log

[Install]
WantedBy=multi-user.target
EOF

# Create timer for regular execution
sudo tee /etc/systemd/system/market-analytics.timer > /dev/null << EOF
[Unit]
Description=Run Market Analytics every 5 minutes
Requires=market-analytics.service

[Timer]
OnCalendar=*:0/5
Persistent=true

[Install]
WantedBy=timers.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable market-analytics.timer
sudo systemctl start market-analytics.timer
```

## Monitoring and Maintenance

### Check System Status

```bash
# View active cron jobs
crontab -l

# Monitor real-time logs
tail -f logs/cron.log

# Check health status
python3 monitoring/health_check.py

# View recent database activity
python3 -c "
from config.database import get_db_connection
with get_db_connection() as conn:
    cursor = conn.cursor()
    cursor.execute('SELECT COUNT(*) as count FROM market_current_state')
    print(f'Current items tracked: {cursor.fetchone()[\"count\"]}')
    cursor.execute('SELECT MAX(last_updated) as latest FROM market_current_state')
    print(f'Last update: {cursor.fetchone()[\"latest\"]}')
"
```

### Log Rotation

Set up automatic log rotation (update path as needed):

```bash
# Replace PROJECT_DIR with your actual path
PROJECT_DIR="/opt/market_analytics"  # Update this path

sudo tee /etc/logrotate.d/market-analytics > /dev/null << EOF
${PROJECT_DIR}/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 analytics analytics
}
EOF
```

### Firewall (if needed)

```bash
# If connecting to remote MySQL server
sudo ufw allow out 3306/tcp
```

## Troubleshooting

### Common Issues

1. **Permission denied on cron jobs**
   ```bash
   chmod +x collectors/*.py monitoring/*.py maintenance/*.py
   ```

2. **Python module not found**
   ```bash
   # Check Python path in cron jobs
   which python3
   # Update PYTHON_PATH in setup_cron_ubuntu.sh if needed
   ```

3. **Database connection failed**
   ```bash
   # Test MySQL/MariaDB connectivity
   mysql -h $DB_HOST -u $DB_USER -p$DB_PASSWORD $DB_NAME -e "SELECT 1"
   # or for MariaDB:
   mariadb -h $DB_HOST -u $DB_USER -p$DB_PASSWORD $DB_NAME -e "SELECT 1"
   ```

4. **Path detection issues**
   ```bash
   # The dynamic path system should auto-detect, but if issues occur:
   python3 -c "from config.paths import PROJECT_ROOT; print(f'Detected path: {PROJECT_ROOT}')"
   ```

### Log Locations

- **Cron activities**: `logs/cron.log`
- **Health checks**: `logs/health.log`
- **Maintenance tasks**: `logs/maintenance.log`
- **Application logs**: `logs/` (auto-rotated daily)

## Performance Optimization

### Database Optimization

```sql
-- Ensure indexes exist (run once)
CREATE INDEX IF NOT EXISTS idx_market_sales_time ON pk_market_sales(time);
CREATE INDEX IF NOT EXISTS idx_market_active_deadman ON pk_market_active(deadman);
CREATE INDEX IF NOT EXISTS idx_snapshot_time ON market_snapshots(snapshot_time);
CREATE INDEX IF NOT EXISTS idx_hourly_timestamp ON market_prices_hourly(hour_timestamp);
CREATE INDEX IF NOT EXISTS idx_current_state_updated ON market_current_state(last_updated);
```

### System Resources

- **Memory**: 512MB minimum, 1GB recommended
- **Storage**: 5GB minimum for logs and data
- **CPU**: Single core sufficient for most RSC servers

## Security Notes

- Use dedicated MySQL user with minimal permissions (SELECT only on game tables)
- Consider running analytics in isolated user account
- Regularly rotate database passwords
- Monitor log files for unusual activity

## Backup Strategy

```bash
# Weekly backup script (add to cron)
#!/bin/bash

# Auto-detect project directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
BACKUP_DIR="$SCRIPT_DIR/backups"
DATE=$(date +%Y%m%d)

mkdir -p $BACKUP_DIR

# Load environment variables
source $SCRIPT_DIR/.env 2>/dev/null || {
    echo "Error: .env file not found"
    exit 1
}

# Backup analytics data (works with MySQL and MariaDB)
mysqldump -h $DB_HOST -u $DB_USER -p$DB_PASSWORD $DB_NAME \
  market_snapshots market_prices_hourly market_prices_daily \
  market_current_state market_notable_trades \
  > $BACKUP_DIR/market_analytics_$DATE.sql

# Cleanup old backups (keep 4 weeks)
find $BACKUP_DIR -name "market_analytics_*.sql" -mtime +28 -delete
```

---

**System is now ready for production use on Ubuntu Server!**

For support or issues, check the troubleshooting section above or review application logs.