From 12f141fca3937eafbece572e635103441d41f203 Mon Sep 17 00:00:00 2001 From: Tobi Date: Tue, 21 Jul 2026 09:50:08 +0200 Subject: [PATCH] =?UTF-8?q?Initial=20commit:=20KONZEPT.md=20=E2=80=94=20Ri?= =?UTF-8?q?ppy=20Konzept=20(Automatisches=20Ripping-System=20CD/DVD/Blu-ra?= =?UTF-8?q?y)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- KONZEPT.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 KONZEPT.md diff --git a/KONZEPT.md b/KONZEPT.md new file mode 100644 index 0000000..579fb69 --- /dev/null +++ b/KONZEPT.md @@ -0,0 +1,149 @@ +# KONZEPT — Rippy + +> Automatisches Ripping-System für CD, DVD und Blu-ray, gebaut für Proxmox LXC (Debian 12 Slim). Ziel: Ein modernes, eigenständiges System statt veralteter ARM-Flask-UI. + +--- + +## 1. Ziel & Motivation + +Der Commander betreibt ein Heimlab mit Proxmox LXC (Debian 12) und PBS-Backup. Das vorhandene Automatic Ripping Machine (ARM) ist funktional, aber das UI (Flask) ist veraltet, es hat keine Echtzeit-Updates (kein SSE/WebSocket), keine JWT-Auth und eine monolithische Architektur. + +Rippy ist ein **komplett neues System** von Grund auf: modulare Multi-Container-Architektur, modernes WebUI, Echtzeit-Jobstatus, sichere Authentifizierung — gebaut als eigenständiges Produkt, nicht als ARM-Fork. + +## 2. Zielgruppe + +- **Commander** (Hauptnutzer): Technik-affin, Proxmox-Heimlab, Wert auf eigene Kontrolle und Datenschutz. +- **Zukünftig**: Weitere Heimlab-Nutzer mit ähnlicher Infrastruktur. + +## 3. Kern-Idee + +Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt, das Medium rippt, Metadaten anreichert und das Ergebnis strukturiert ablegt. Alles über eine REST-API, asynchrone Celery-Jobs, ein React-WebUI und Echtzeit-Status über SSE. + +## 4. Features + +| Feature | Muss | Kann | Später | +|---------|------|------|--------| +| Disc-Erkennung via udev-Event | ✔ M | | | +| Dynamischer Device-Resolver (UUID/Serial) | ✔ M | | | +| MakeMKV-Ripping (lossless) | ✔ M | | | +| Audio-Rip mit abcde + MusicBrainz | ✔ M | | | +| Video-Metadaten via TMDB API | ✔ M | | | +| AcoustID-Fingerprinting (chromaprint) | ✔ M | | | +| Multi-Disc-Set-Handling (Release-Group-Resolver) | ✔ M | | | +| SQLite-Cache für API-Rate-Limits | ✔ M | | | +| JWT-Auth (Access 15min/Refresh 7 Tage) | ✔ M | | | +| Rate-Limiting (100/min pro API-Key) | ✔ M | | | +| Celery-Queue + Redis mit AOF-Persistence | ✔ M | | | +| Echtzeit-Status über SSE | ✔ M | | | +| React-UI (statisch via Nginx) | ✔ M | | | +| Proxmox LXC Template + Ansible Playbooks | ✔ M | | | +| SELinux/AppArmor Profile pro Container | ✔ M | | | +| MakeMKV als isolierte Black-Box-CLI | ✔ M | | | +| GPL-v3-Compliance-Checkliste | ✔ M | | | +| Source-Release-Endpoint | ✔ M | | | +| HandBrake-Transcoding (optional) | | ✔ K | | +| Prometheus+Grafana Monitoring | | ✔ K | | +| PBS-Snapshot-Backup-Hooks | | ✔ K | | +| Multi-Disc-Parallelisierung | | | ✔ S | +| Redis-Cluster (Horizontales Scaling) | | | ✔ S | +| PWA Mobile-App | | | ✔ S | + +## 5. Mechaniken & Ablauf + +**Roter Faden — was passiert, wenn der Commander eine Disc einlegt:** + +1. **udev-Event** → System-Dämon (unabhängig vom API-Container) erkennt Einwurf. +2. **Device-Resolver** (udev-basiert) ermittelt UUID/Serial-Nummer des Laufwerks, erzeugt Symlink `/dev/disc/`. +3. **Job-Erstellung** → Dämon erstellt Celery-Task, übergibt Device-Pfad und Disc-Typ. +4. **Typ-Erkennung** (CD/DVD/Blu-ray) → Auswahl des Ripping-Pfads. +5. **Ripping**: + - CD: `abcde` → FLAC, Metadaten via AcoustID-Fingerprinting + MusicBrainz. + - DVD/Blu-ray: `makemkvcon --all --progress` → MKV. +6. **Metadaten-Anreicherung**: Video-Infos von TMDB, Audio-Fallback von Discogs. SQLite-Cache für Rate-Limits. +7. **Multi-Disc-Erkennung**: Release-Group-Resolver prüft, ob weitere Discs des gleichen Sets folgen. +8. **Speichern**: Strukturierte Ablage nach `///`. +9. **Status-Push**: Worker sendet Fortschritt über SSE an React-UI. +10. **Abschluss**: Job-Ergebnis wird protokolliert, API gibt Token zurück, PBS-Backup-Hook kann ausgelöst werden. + +## 6. Architektur & Tech-Stack + +``` +┌─────────────────────────────────────────────────────┐ +│ Proxmox LXC (Debian 12 Slim) │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ API-Service │ │ Worker- │ │ UI-Service │ │ +│ │ FastAPI │◄►│ Celery+ │ │ React + │ │ +│ │ PostgreSQL │ │ Redis(AOF) │ │ Nginx │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌────────────────────────────────────────┐ │ +│ │ udev-Daemon → Device-Resolver │ │ +│ │ Unix-Socket → Worker Device-Infos │ │ +│ └────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────┐ │ +│ │ MakeMKV (isolierter CLI-Aufruf) │ │ +│ │ HandBrake (optional, CLI) │ │ +│ │ abcde + chromaprint + MusicBrainz │ │ +│ └────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────┘ +``` + +**Container-Design:** +- **API-Service** (FastAPI): JWT-Auth, REST-Endpoints, OpenAPI-Docs, Job-Management, Lizenz-Handling. +- **Worker-Service** (Celery + Redis mit AOF-Persistence): Isolierte Ripping-Jobs, Cellery Tasks mit Device-Meta-Daten. +- **UI-Service** (React + Vite): Build-Step → statisch, bereitgestellt via Nginx. SSE-Client für Echtzeit-Status. +- **udev-Daemon**: Separater System-Dienst (unabhängig von API-Container), empfängt Disc-Einwurf-Events. + +**LXC-Isolation:** +- Read-only Bind-Mounts für System-Bibliotheken. +- Device-Node-Read-Only für `/dev/sr*` (optische Medien sind read-only). +- SELinux/AppArmor Profile pro Container. +- Netzwerk-Policy: UI↔API (HTTPS), API↔Worker (mTLS), Worker↔Internet (nur API-Endpoints). + +**Persistenz:** +- PostgreSQL für Job-Logs, Metadaten, User-Management. +- SQLite-Cache für API-Antworten (MusicBrainz, TMDB) — max 10.000 Einträge, LRU-Eviction. +- NFS/Bind-Mount für Medien-Store (geteilter Volume). + +## 7. UX-Flow + +1. **Dashboard** — Echtzeit-Kacheln mit aktuellem Job-Status, Queue-Übersicht, Disc-Einwurf-Hinweis. +2. **Job-Verlauf** — Tabelle aller Jobs mit Status, Fortschrittsbalken, Ergebnis-Vorschau. +3. **Job-Detail** — Live-Log-Ausgabe, Fortschritt, Möglichkeit "Abort" (nur vor Job-Start). +4. **Ergebnis-View** — Liste gerippter Dateien, Metadaten-Anzeige, "Play" (Streaming) / "Download". +5. **Einstellungen** — API-Keys verwalten (TMDB, Discogs), Transcoding-Optionen, Backup-Pfade, Lizenz-Einstellungen. +6. **Geräte-Verwaltung** — Liste verfügbarer Laufwerke, Status, Device-Resolver-Konfiguration. + +## 8. Risiken & offene Punkte + +| Risiko | Status | Behandlung | +|--------|--------|------------| +| MakeMKV-Beta-Key-Management | Gelöst | Key-Erneuerung als Cron-Job dokumentiert; rechtlich: DMCA-Ausnahme für Heimarchiv in DE, kommerzielle Lizenz $50 empfohlen | +| LXC-Device-Node-Änderungen | Gelöst | udev-Resolver (UUID/Serial) statt statischer `/dev/sr*`-Pfade; Device-Symlinks für stabile Zuweisung | +| Pending-Queue / State-Manager | Gelöst | Redis mit AOF-Persistence als State-Manager; Task-Priorisierung, Redis-Dumps beim Neustart | +| Hybrid-Discs (DVD-Audio, Hybrid-CD) | Offen | MVP erkennt nur Standard-CD/DVD/Blu-ray; Hybrid-Erkennung als "Kann" für spätere Version | +| LXC-Device-Passthrough Stabilität | Gelöst | Read-only Bind-Mounts; udev-Daemon unabhängig von API-Container; Hot-Plug-Integration via udev | +| Rate-Limits der Metadaten-APIs | Gelöst | SQLite-Cache (LRU, 10k Einträge), exponential backoff Retry (max 5 Versuche) | +| GPL-v3-Compliance | Gelöst | Checkliste, Source-Release-Endpoint, MakeMKV als isolierte Black-Box, Lizenz-Dokumentation | +| Redis Single-Instance Bottleneck | Offen | MVP mit Single-Instance; Redis-Cluster als "Später"-Feature | + +## 9. Härtetest-Dokumentation + +**Erster Haertetest (Advocatus Diaboli, GLM-4.7-Flash):** +5 BLOCKER gefunden: MakeMKV-Key-Management, LXC-Device-Resolver, Pending-Queue, Hybrid-Discs, Bind-Mount-Performance. + +**Runde 1 (5 Rollen):** +- DevOps: Multi-Container-Architektur, Proxmox-HA-Template, Resource-Limits, Restart-Policy. +- Security: JWT-Refresh-Token, Rate-Limiting, mTLS, SELinux/AppArmor. +- Software Architekt: udev-basierter Device-Resolver, Unix-Socket, State-Manager, Pending-Queue. +- Media Metadata: AcoustID-Fingerprinting, Multi-Disc-Set-Handling, SQLite-Cache. +- Legal: GPL-v3-Checkliste, MakeMKV-Black-Box-Trennung, Source-Release-Endpoint. + +**Zweiter Haertetest (Advocatus Diaboli, GLM-4.7-Flash):** +5 HINWEISE (keine BLOCKER): React als Build-Step+Statisch (korrigiert), Redis-AOF-Persistence (integriert), Read-only vs. Write-Konflikt (nicht relevant — optische Medien sind read-only), Redis-Cluster (als "Später" notiert), Cold-Boot-Problematik (udev-Daemon als separater Dienst gelöst). + +**Ergebnis:** Keine BLOCKER mehr. Konzept ist wasserdicht für MVP-Phase.