522 lines
11 KiB
Markdown
522 lines
11 KiB
Markdown
# 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 |