Initial commit - Video Service for Coolify
This commit is contained in:
230
README.md
Executable file
230
README.md
Executable file
@@ -0,0 +1,230 @@
|
||||
# Video-Service fuer Kurs-Booking Plugin
|
||||
|
||||
Python-basierter Microservice fuer Video-Hosting und HLS-Streaming.
|
||||
|
||||
## Technologie-Stack
|
||||
|
||||
| Komponente | Version | Beschreibung |
|
||||
|------------|---------|--------------|
|
||||
| Python | 3.13 | Support bis Oktober 2029 |
|
||||
| FastAPI | 0.115 | REST API Framework |
|
||||
| Redis | 7.4 | Task Queue (BSD-Lizenz) |
|
||||
| Celery | 5.4 | Async Task Processing |
|
||||
| FFmpeg | 6.1 | Video-Konvertierung |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Container starten
|
||||
cd video-service
|
||||
docker compose up -d
|
||||
|
||||
# Logs anzeigen
|
||||
docker compose logs -f video-api
|
||||
|
||||
# Health Check
|
||||
curl http://localhost:8500/api/v1/health
|
||||
```
|
||||
|
||||
## Architektur
|
||||
|
||||
```
|
||||
video-service/
|
||||
+-- app/
|
||||
| +-- main.py # FastAPI App
|
||||
| +-- config.py # Pydantic Settings
|
||||
| +-- celery_app.py # Celery Config
|
||||
| +-- api/
|
||||
| | +-- routes.py # API Endpoints
|
||||
| | +-- auth.py # JWT + API-Key
|
||||
| +-- services/
|
||||
| | +-- storage.py # File Management
|
||||
| | +-- converter.py # FFmpeg Wrapper
|
||||
| +-- tasks/
|
||||
| | +-- video_tasks.py # Celery Tasks
|
||||
| +-- models/
|
||||
| +-- schemas.py # Pydantic Models
|
||||
+-- storage/
|
||||
| +-- uploads/ # Hochgeladene Videos
|
||||
| +-- converted/ # HLS Output
|
||||
+-- tests/
|
||||
+-- test_api.py
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Endpoint | Methode | Auth | Beschreibung |
|
||||
|----------|---------|------|--------------|
|
||||
| `/health` | GET | - | Health Check |
|
||||
| `/api/v1/health` | GET | - | Detaillierter Health Check |
|
||||
| `/api/v1/videos/upload` | POST | API-Key | Video hochladen |
|
||||
| `/api/v1/videos/{id}/status` | GET | API-Key | Status abfragen |
|
||||
| `/api/v1/videos` | GET | API-Key | Alle Videos listen |
|
||||
| `/api/v1/videos/{id}` | DELETE | API-Key | Video loeschen |
|
||||
| `/api/v1/videos/{id}/token` | POST | API-Key | Stream-Token generieren |
|
||||
| `/api/v1/stream/{id}/master.m3u8` | GET | JWT | HLS Master Playlist |
|
||||
| `/api/v1/stream/{id}/{quality}/playlist.m3u8` | GET | JWT | Quality Playlist |
|
||||
| `/api/v1/stream/{id}/{quality}/{segment}` | GET | JWT | Video Segment |
|
||||
|
||||
## Authentifizierung
|
||||
|
||||
### API-Key (WordPress -> Video-Service)
|
||||
|
||||
```
|
||||
X-API-Key: your-api-key
|
||||
```
|
||||
|
||||
### JWT Token (Client -> Streaming)
|
||||
|
||||
```
|
||||
/api/v1/stream/{video_id}/master.m3u8?token=eyJ...
|
||||
```
|
||||
|
||||
Token-Inhalt:
|
||||
```json
|
||||
{
|
||||
"video_id": "abc123",
|
||||
"buchung_id": 789,
|
||||
"ip": "192.168.1.100",
|
||||
"exp": 1701442800
|
||||
}
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Beschreibung |
|
||||
|----------|---------|--------------|
|
||||
| `API_KEY` | - | API-Key fuer WordPress |
|
||||
| `JWT_SECRET` | - | Secret fuer Stream-Tokens |
|
||||
| `JWT_EXPIRY_HOURS` | 1 | Token-Gueltigkeit |
|
||||
| `REDIS_URL` | redis://redis:6379/0 | Redis-Verbindung |
|
||||
| `STORAGE_PATH` | /app/storage | Speicherpfad |
|
||||
| `WORDPRESS_WEBHOOK_URL` | - | Webhook-URL |
|
||||
| `ALLOWED_ORIGINS` | - | CORS Origins |
|
||||
| `VIDEO_DOMAIN` | - | Produktions-Domain |
|
||||
| `MAX_UPLOAD_SIZE_MB` | 2048 | Max. Upload (2GB) |
|
||||
| `VIDEO_QUALITIES` | 360p,720p,1080p | HLS Qualitaeten |
|
||||
| `HLS_SEGMENT_DURATION` | 6 | Segment-Laenge |
|
||||
|
||||
## Video-Konvertierung
|
||||
|
||||
### HLS Output-Struktur
|
||||
|
||||
```
|
||||
videos/{video_id}/
|
||||
+-- metadata.json
|
||||
+-- thumbnail.jpg
|
||||
+-- hls/
|
||||
+-- master.m3u8
|
||||
+-- 360p/
|
||||
| +-- playlist.m3u8
|
||||
| +-- segment_000.ts
|
||||
| +-- segment_001.ts
|
||||
+-- 720p/
|
||||
| +-- playlist.m3u8
|
||||
| +-- segment_000.ts
|
||||
+-- 1080p/
|
||||
+-- playlist.m3u8
|
||||
+-- segment_000.ts
|
||||
```
|
||||
|
||||
### Quality Presets
|
||||
|
||||
| Quality | Resolution | Video Bitrate | Audio Bitrate |
|
||||
|---------|------------|---------------|---------------|
|
||||
| 360p | -2:360 | 800k | 96k |
|
||||
| 720p | -2:720 | 2500k | 128k |
|
||||
| 1080p | -2:1080 | 5000k | 192k |
|
||||
|
||||
## Webhook Events
|
||||
|
||||
Der Service sendet Webhooks an WordPress:
|
||||
|
||||
### `video.progress`
|
||||
```json
|
||||
{
|
||||
"event": "video.progress",
|
||||
"video_id": "abc123",
|
||||
"kurs_id": 42,
|
||||
"status": "processing",
|
||||
"progress": 45
|
||||
}
|
||||
```
|
||||
|
||||
### `video.ready`
|
||||
```json
|
||||
{
|
||||
"event": "video.ready",
|
||||
"video_id": "abc123",
|
||||
"kurs_id": 42,
|
||||
"status": "ready",
|
||||
"metadata": {
|
||||
"duration_seconds": 3600,
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"thumbnail_url": "https://..."
|
||||
}
|
||||
```
|
||||
|
||||
### `video.error`
|
||||
```json
|
||||
{
|
||||
"event": "video.error",
|
||||
"video_id": "abc123",
|
||||
"kurs_id": 42,
|
||||
"status": "error",
|
||||
"error_message": "FFmpeg conversion failed"
|
||||
}
|
||||
```
|
||||
|
||||
## WordPress Integration
|
||||
|
||||
### Einstellungen
|
||||
|
||||
In WordPress unter **Veranstaltungen > Einstellungen > Video-Service**:
|
||||
|
||||
1. Video-Service URL eintragen (z.B. `http://localhost:8500`)
|
||||
2. API-Key eintragen (muss mit VIDEO_API_KEY uebereinstimmen)
|
||||
3. Verbindung testen
|
||||
|
||||
### Shortcode
|
||||
|
||||
```
|
||||
[kurs_video buchung_id="123"]
|
||||
[kurs_video buchung_id="123" video_id="5"]
|
||||
```
|
||||
|
||||
## Entwicklung
|
||||
|
||||
```bash
|
||||
# Lokale Tests
|
||||
cd video-service
|
||||
python -m pytest tests/ -v
|
||||
|
||||
# API Dokumentation
|
||||
# http://localhost:8500/docs (nur im Debug-Modus)
|
||||
```
|
||||
|
||||
## Deployment auf Hetzner
|
||||
|
||||
1. Storage Box einrichten (BX11)
|
||||
2. CX22 Server mit Docker
|
||||
3. DNS: videos.islandpferde-melanieworbs.de -> Server-IP
|
||||
4. SSL-Zertifikat via Coolify/Traefik
|
||||
5. Environment Variables in Coolify setzen
|
||||
|
||||
## Sicherheit
|
||||
|
||||
- API-Key zwischen WordPress und Service
|
||||
- JWT fuer Streaming mit IP-Binding
|
||||
- Rate-Limiting (10 req/s)
|
||||
- Kein direkter Zugriff auf Storage
|
||||
- HTTPS in Produktion
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Stand:** 02. Dezember 2025
|
||||
Reference in New Issue
Block a user