# Playlist Monitor Service - Comprehensive Build Guide

## 📋 Table of Contents
1. [Prerequisites](#prerequisites)
2. [Build Options](#build-options)
3. [Development Setup](#development-setup)
4. [Production Build](#production-build)
5. [UI Integration Options](#ui-integration-options)
6. [Docker Build](#docker-build)
7. [Troubleshooting](#troubleshooting)
8. [Advanced Build Options](#advanced-build-options)

## 🔧 Prerequisites

### System Requirements
- **Python**: 3.13+ (3.14 recommended)
- **Operating System**: Linux/macOS/Windows WSL2
- **Memory**: Minimum 512MB RAM, 1GB recommended
- **Storage**: 100MB for application + space for downloads
- **Network**: Access to YouTube and MeTube instance

### Software Dependencies
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3.13 python3.13-dev python3.13-venv build-essential curl git

# macOS (using Homebrew)
brew install python@3.13 curl git

# CentOS/RHEL/Fedora
sudo dnf install python3.13 python3.13-devel gcc curl git
```

### MeTube Requirements
- MeTube instance running (locally or remotely)
- MeTube version that supports playlist downloads
- Network connectivity between services

## 🏗️ Build Options

### Option 1: Modern Python with uv (Recommended)
**Fastest, most reliable method**

```bash
# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.cargo/env

# Clone and setup
cd /root/workspace/tubewatch/playlist-monitor
uv sync

# Run
uv run python -m app.main
```

### Option 2: Traditional pip/venv
**Standard Python approach**

```bash
# Create virtual environment
python3.13 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

# Install dependencies
pip install --upgrade pip
pip install -e .

# Run
python -m app.main
```

### Option 3: Poetry (Alternative)
**For Poetry users**

```bash
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Setup project
poetry install
poetry run python -m app.main
```

## 🛠️ Development Setup

### 1. Environment Configuration
```bash
# Copy environment template
cp .env.example .env

# Edit configuration
nano .env
```

**Essential settings:**
```env
# MeTube Integration
METUBE_URL=http://localhost:8081

# Database
DATABASE_URL=sqlite:///data/playlists.db

# Server
HOST=0.0.0.0
PORT=8082

# Scheduler
DEFAULT_CHECK_INTERVAL=60
MAX_CONCURRENT_DOWNLOADS=3

# Logging
LOG_LEVEL=INFO
```

### 2. Development Dependencies
```bash
# Install development dependencies
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"
```

### 3. Development Tools Setup
```bash
# Code formatting
uv run black app/ tests/
uv run isort app/ tests/

# Type checking
uv run mypy app/

# Linting
uv run flake8 app/ tests/
```

### 4. Database Setup
```bash
# Create data directory
mkdir -p data logs

# Initialize database (automatic on first run)
uv run python -c "from app.core.database import engine, Base; Base.metadata.create_all(bind=engine)"
```

## 🚀 Production Build

### Step 1: Production Dependencies
```bash
# Install only production dependencies
uv sync --no-dev

# Or with pip
pip install -r requirements.txt
```

### Step 2: Production Configuration
```bash
# Create production environment
cp .env.example .env.production

# Edit production settings
nano .env.production
```

**Production recommendations:**
```env
# Security
DEBUG=false
LOG_LEVEL=WARNING
CORS_ORIGINS=["https://yourdomain.com"]

# Performance
MAX_CONCURRENT_DOWNLOADS=5
DEFAULT_CHECK_INTERVAL=30

# Database (PostgreSQL recommended)
DATABASE_URL=postgresql://user:pass@localhost/metube_playlists
```

### Step 3: Production Server
```bash
# Use production ASGI server
uv run gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8082 \
  --log-level info

# Or with uvicorn directly
uv run uvicorn app.main:app \
  --host 0.0.0.0 \
  --port 8082 \
  --workers 4 \
  --log-level info
```

## 🎨 UI Integration Options

### Option 1: Standalone Web UI (Recommended)
Create a separate frontend application that communicates with the API.

**Technologies:**
- **React** with TypeScript
- **Vue.js 3** with Composition API
- **SvelteKit** for modern approach

**Example React setup:**
```bash
# Create React app
cd /root/workspace/tubewatch
npx create-react-app playlist-monitor-ui --template typescript
cd playlist-monitor-ui

# Install UI libraries
npm install @mui/material @emotion/react @emotion/styled axios react-query
npm install @mui/icons-material @mui/x-data-grid date-fns

# Start development
npm start
```

### Option 2: Extend MeTube Angular UI
Modify the existing MeTube Angular frontend to include playlist monitoring.

**Approach:**
1. Add new Angular components to MeTube's UI
2. Integrate with existing MeTube routing
3. Use MeTube's existing styling and components

**Integration points:**
- Add playlist tab to main navigation
- Extend existing download interface
- Reuse MeTube's component library

### Option 3: Simple HTML Dashboard
For minimal UI requirements.

```bash
# Create simple dashboard
mkdir ui
cd ui

# Create index.html with vanilla JS
cat > index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
    <title>Playlist Monitor</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body>
    <div class="container mt-4">
        <h1>Playlist Monitor Dashboard</h1>
        <div id="playlists"></div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
    <script src="app.js"></script>
</body>
</html>
EOF

# Simple JavaScript API client
cat > app.js << 'EOF'
const API_BASE = 'http://localhost:8082/api';

async function loadPlaylists() {
    try {
        const response = await fetch(`${API_BASE}/playlists`);
        const data = await response.json();
        displayPlaylists(data);
    } catch (error) {
        console.error('Error loading playlists:', error);
    }
}

function displayPlaylists(playlists) {
    const container = document.getElementById('playlists');
    container.innerHTML = playlists.map(playlist => `
        <div class="card mb-3">
            <div class="card-body">
                <h5 class="card-title">${playlist.title || 'Untitled'}</h5>
                <p class="card-text">${playlist.url}</p>
                <p>Status: ${playlist.enabled ? 'Enabled' : 'Disabled'}</p>
            </div>
        </div>
    `).join('');
}

loadPlaylists();
EOF
```

## 🐳 Docker Build

### Development Docker Build
```bash
# Build development image
docker build -t playlist-monitor:dev .

# Run development container
docker run -d \
  --name playlist-monitor-dev \
  -p 8082:8082 \
  -e DEBUG=true \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  playlist-monitor:dev
```

### Production Docker Build
```bash
# Build production image
docker build -t playlist-monitor:latest .

# Run production container
docker run -d \
  --name playlist-monitor \
  -p 8082:8082 \
  -e METUBE_URL=http://metube:8081 \
  -v playlist-data:/app/data \
  -v playlist-logs:/app/logs \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:8082/health || exit 1" \
  --health-interval=30s \
  playlist-monitor:latest
```

### Multi-stage Docker Build (Optimized)
```dockerfile
# Build stage
FROM python:3.13-slim as builder

WORKDIR /build
COPY pyproject.toml ./
RUN pip install uv
RUN uv sync --no-dev

# Runtime stage
FROM python:3.13-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=builder /build/.venv ./.venv
COPY app/ ./app/

ENV PATH="/app/.venv/bin:$PATH"

USER 1000:1000
EXPOSE 8082

CMD ["python", "-m", "app.main"]
```

## 🔍 Troubleshooting

### Build Issues

#### Python Version Mismatch
```bash
# Check Python version
python3 --version

# Install correct version
pyenv install 3.13.0
pyenv local 3.13.0
```

#### Dependency Conflicts
```bash
# Clear cache
uv cache clean
rm -rf .venv

# Reinstall
uv sync
```

#### Compilation Errors
```bash
# Install build dependencies
sudo apt install build-essential python3-dev

# Or use pre-built wheels
pip install --only-binary=all -r requirements.txt
```

### Runtime Issues

#### Port Already in Use
```bash
# Find process using port 8082
lsof -i :8082

# Kill process
kill -9 <PID>

# Or use different port
export PORT=8083
```

#### Database Locked
```bash
# Check for existing processes
ps aux | grep playlist-monitor

# Remove lock file
rm data/*.db-journal
```

#### MeTube Connection Failed
```bash
# Test MeTube connectivity
curl http://localhost:8081/info

# Check MeTube logs
docker logs metube
```

## 🔧 Advanced Build Options

### Custom Database Backend
```bash
# PostgreSQL setup
docker run -d \
  --name postgres-playlist \
  -e POSTGRES_DB=playlists \
  -e POSTGRES_USER=playlist_user \
  -e POSTGRES_PASSWORD=secure_password \
  -p 5432:5432 \
  postgres:15

# Update .env
DATABASE_URL=postgresql://playlist_user:secure_password@localhost:5432/playlists
```

### Redis for Caching
```bash
# Redis setup
docker run -d \
  --name redis-playlist \
  -p 6379:6379 \
  redis:7-alpine

# Install Redis dependencies
uv add redis
```

### HTTPS/SSL Configuration
```bash
# Generate SSL certificates
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Update configuration
HTTPS_ENABLED=true
SSL_CERTFILE=cert.pem
SSL_KEYFILE=key.pem
```

### Load Balancing with Nginx
```nginx
upstream playlist_monitor {
    server localhost:8082;
    server localhost:8083;
    server localhost:8084;
}

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://playlist_monitor;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 📋 Build Checklist

### Pre-build
- [ ] Python 3.13+ installed
- [ ] MeTube accessible
- [ ] Required ports available (8082)
- [ ] Sufficient disk space

### Build Process
- [ ] Dependencies installed successfully
- [ ] Configuration file created
- [ ] Database initialized
- [ ] Tests pass
- [ ] Service starts without errors

### Post-build
- [ ] API accessible at http://localhost:8082
- [ ] MeTube connection established
- [ ] Database operations working
- [ ] Scheduler running
- [ ] Logs rotating properly

## 🎯 Next Steps

After successful build:
1. **Test the API** using the Quick Start Guide
2. **Set up monitoring** with health checks
3. **Configure automatic startup** with systemd or Docker
4. **Implement UI** (see UI_INTEGRATION.md)
5. **Set up logging** and monitoring

## 📚 Related Documentation
- [QUICK_START_GUIDE.md](QUICK_START_GUIDE.md) - Getting started quickly
- [TESTING_GUIDE.md](TESTING_GUIDE.md) - Comprehensive testing
- [UI_INTEGRATION.md](UI_INTEGRATION.md) - UI implementation options
- [ADVANCED_CONFIG.md](ADVANCED_CONFIG.md) - Advanced configuration options