11 KiB

Raw Blame History

Playlist Monitor Service - Comprehensive Build Guide

📋 Table of Contents

Prerequisites
Build Options
Development Setup
Production Build
UI Integration Options
Docker Build
Troubleshooting
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

# 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

# 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

# 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

# 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

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

Essential settings:

# 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

# Install development dependencies
uv sync --extra dev

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

3. Development Tools Setup

# 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

# 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

# Install only production dependencies
uv sync --no-dev

# Or with pip
pip install -r requirements.txt

Step 2: Production Configuration

# Create production environment
cp .env.example .env.production

# Edit production settings
nano .env.production

Production recommendations:

# 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

# 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:

# 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:

Add new Angular components to MeTube's UI
Integrate with existing MeTube routing
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.

# 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

# 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

# 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)

# 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

# Check Python version
python3 --version

# Install correct version
pyenv install 3.13.0
pyenv local 3.13.0

Dependency Conflicts

# Clear cache
uv cache clean
rm -rf .venv

# Reinstall
uv sync

Compilation Errors

# 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

# Find process using port 8082
lsof -i :8082

# Kill process
kill -9 <PID>

# Or use different port
export PORT=8083

Database Locked

# Check for existing processes
ps aux | grep playlist-monitor

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

MeTube Connection Failed

# Test MeTube connectivity
curl http://localhost:8081/info

# Check MeTube logs
docker logs metube

🔧 Advanced Build Options

Custom Database Backend

# 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

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

# Install Redis dependencies
uv add redis

HTTPS/SSL Configuration

# 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

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:

Test the API using the Quick Start Guide
Set up monitoring with health checks
Configure automatic startup with systemd or Docker
Implement UI (see UI_INTEGRATION.md)
Set up logging and monitoring

QUICK_START_GUIDE.md - Getting started quickly
TESTING_GUIDE.md - Comprehensive testing
UI_INTEGRATION.md - UI implementation options
ADVANCED_CONFIG.md - Advanced configuration options

11 KiB Raw Blame History