From cbe7d2b9c304fbe12a5e065b6339471c056a3b61 Mon Sep 17 00:00:00 2001 From: Tobi Date: Tue, 21 Jul 2026 10:11:42 +0200 Subject: [PATCH] Doku: KONZEPT.md, ROADMAP.md, AGENTS.md, README.md, SAVEPOINT.md, .aiexclude --- .aiexclude | 31 ++++++++++ AGENTS.md | 34 +++++++++++ README.md | 25 +++++++- ROADMAP.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++ SAVEPOINT.md | 39 +++++++++++++ 5 files changed, 289 insertions(+), 2 deletions(-) create mode 100644 .aiexclude create mode 100644 AGENTS.md create mode 100644 ROADMAP.md create mode 100644 SAVEPOINT.md diff --git a/.aiexclude b/.aiexclude new file mode 100644 index 0000000..7f0e444 --- /dev/null +++ b/.aiexclude @@ -0,0 +1,31 @@ +# Rippy — Was die KI NICHT lesen soll +# gitignore-Syntax, was im Kontext ignoriert wird + +# Secrets & Config +.env +*.env +config/secrets.yml +config/api-keys.yml + +# Large data files +*.mkv +*.flac +*.iso +media/ + +# Build artifacts +frontend/dist +node_modules/ +__pycache__/ +*.egg-info/ +.pytest_cache/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bb74c47 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md — Arbeits-Konventionen für Rippy + +## Grundregeln + +**1. Plan vor Code.** Vor jeder Etappe: Klare Akzeptanzkriterien schreiben, dann bauen. +**2. Kleine Schritte.** Max. eine Feature pro Commit. Commit-Nachrichten beschreiben WAS und WARUM. +**3. Beweisen statt behaupten.** Testen, was gebaut wurde. Keine "es sollte funktionieren"-Commits. +**4. Deutsch-Nicht-Entwickler.** Der Commander liest alles — Variablennamen auf Englisch, aber Kommentare und Docs auf Deutsch. + +## Workflow + +1. **Read:** KONZEPT.md + ROADMAP.md lesen. Verstehen, welche Etappe dran ist. +2. **Plan:** Was genau soll diese Sitzung bauen? Eine Zeile. +3. **Build:** Code schreiben, testen, committen. +4. **Verify:** `docker compose up` — funktioniert das Ganze? +5. **Savepoint:** SAVEPOINT.md aktualisieren. Nächster Chat beginnt nicht von Null. + +## Modelle je Aufgabe + +- **Planung:** Heavy-Modell (Reasoning) für Architektur-Entscheidungen. +- **Bauen:** schnelles Coding-Modell. +- **Review:** Heavy nochmal für Code-Review vor Merge. + +## Docker-Praxis + +- Alles läuft in Containern: `docker compose up -d` +- Keine System-Pakete auf dem Host — alles im Container. +- Dockerfile immer multi-stage, kleinste Images. + +## Was NICHT gebaut wird + +- Kein Code direkt im Host-OS. +- Kein Proxmox-LXC-Nesting-Workaround — das Projekt lebt bewusst in normalem Docker. +- Kein ARM-Fork — Rippy ist ein Eigenbau von Grund auf. diff --git a/README.md b/README.md index 34a32ec..9e86697 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,24 @@ -# rippy +# Rippy -Modernes automatisches CD/DVD/Blu-ray-Ripping-System mit WebUI und Proxmox-Integration \ No newline at end of file +Ein modernes, eigenständiges System zum automatischen Rippen von CD, DVD und Blu-ray. +Es erkennt Disc-Einwürfe automatisch, sucht Metadaten vor, rippt verlustfrei und legt +alles in Jellyfin-konformer Struktur ab — mit Echtzeit-UI statt veralteter Flask-Oberfläche. + +## Was du brauchst + +- Ein System mit einem optischen Laufwerk (DVD/Blu-ray) +- Docker + Docker Compose +- 1–2 Stunden Zeit für den ersten Bau + +## So legst du los + +1. Clone das Repo: + ``` + git clone https://git.tobisniceshomelab.ddnsfree.com/Hitonabi/rippy.git + cd rippy + ``` +2. Lies **KONZEPT.md** — das sagt, was das Projekt ist. +3. Lies **ROADMAP.md** — das sagt, in welcher Reihenfolge es gebaut wird. +4. Fang mit Etappe 1 an (Fundament + udev-Erkennung). + +Alles andere steht in den Docs. Viel Spaß beim Bauen. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..8275dbc --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,162 @@ +# ROADMAP — Rippy + +> Meilenstein-Plan für den Bau von Rippy. Jede Etappe ist lauffähig für sich. + +--- + +## Etappe 1: Fundament — Container-Infrastruktur + udev-Erkennung + +**Ziel:** Das System bootet, erkennt eine eingelegte Disc und erstellt einen Job. + +**Was gebaut wird:** +- Docker Compose mit `api`, `worker`, `ui`, `postgres`, `redis` +- Basis-Dockerfiles für jeden Service (Python/FastAPI, Python/Celery, Node/React, PostgreSQL, Redis) +- udev-Regel + separater Daemon (Go oder Python), der Disc-Einwurf erkennt und Jobs an den Worker sendet +- Device-Resolver: ermittelt UUID/Serial des Laufwerks, erzeugt Symlink `/dev/disc/` +- Job-Erstellung in Celery-Queue mit Disc-Typ und Device-Pfad + +**Fertig wenn:** +- `docker compose up` startet alle 5 Container +- `makejungles` liest die TOC einer eingelegten Disc +- udev-Event löst Job-Erstellung aus +- Celery-Worker nimmt den Job entgegen und gibt "Disc erkannt: DVD, Titel: 'xyz'" aus + +--- + +## Etappe 2: Ripping-Pipeline — Verlustfreies Extrahieren + +**Ziel:** Disc wird rippt und als rohe Dateien abgelegt. + +**Was gebaut wird:** +- CD-Ripping via `abcde` → FLAC, AcoustID-Fingerprinting (chromaprint) + MusicBrainz-Lookup +- DVD/Blu-ray-Ripping via `makejungles` (makeMKV-Äquivalent, OpenSource) → MKV, mit `--all --progress` +- Ripping im Worker-Container, Read-Only Device-Passthrough +- Fortschritts-Reporting über Celery-Signale an SSE-Stream + +**Fertig wenn:** +- CD → FLAC-Dateien + MusicBrainz-Metadaten +- DVD → MKV mit allen Titeln +- Blu-ray → MKV mit allen Titeln +- Fortschritt wird in Echtzeit im UI angezeigt + +--- + +## Etappe 3: Metadaten-Lookup + Pre-Scan + +**Ziel:** Vor dem Ripping wird die Disc identifiziert und der Commander bestätigt. + +**Was gebaut wird:** +- Pre-Scan-Modul: liest TOC (kein Ripping), extrahiert Titel/Laufzeit/Scene-Labels +- TMDB-Integration für Film-/Serien-Matching (Confidence-Score) +- MusicBrainz-Integration für CD-Matching +- TheTVDB-Fallback für Serien +- SQLite-Cache für API-Antworten (LRU, 10k Einträge, TTL) +- Pre-Scan-Latenz: 5–15s, dokumentiert + +**Fertig wenn:** +- Nach Disc-Einwurf: Pre-Scan läuft automatisch +- UI zeigt: Titel, Jahr, Cover, Confidence-Score, Trackliste +- Commander kann bestätigen oder manuell korrigieren +- Bestätigte Metadaten werden im Cache persistiert + +--- + +## Etappe 4: Jellyfin-Formatierung + NFO-Generierung + +**Ziel:** Gerippte Dateien liegen in Jellyfin-konformer Ordnerstruktur mit Metadaten. + +**Was gebaut wird:** +- Ordnerstruktur: + - Filme: ` ()/-.mkv` + - Serien: `<Serienname>/<Staffel N>/<Serienname> - S{N}E{N} - <Episode>.mkv` + - Musik: `<Künstler>/<Album> (<Jahr>)/<Track-Nr>. <Titel>.flac` +- NFO-Generator im Kodi/NFO-Schema: + - `movie.nfo`, `series.nfo`, `episode.nfo`, `album.nfo` + - Alle Metadaten aus Pre-Scan + NFO-Attribution (Source: TMDB) +- Image-Downloader: poster.jpg (500x750), fanart.jpg, backdrop.jpg (1920x1080+) von TMDB +- Jellyfin-kompatible Dateibenennung +- Multi-Disc-Handling: `Disc 1.mkv`, `Disc 2.mkv` etc. + +**Fertig wenn:** +- Gerippte Dateien + NFO + Poster in Jellyfin-Ordnerstruktur +- Jellyfin scannt und erkennt alles korrekt +- Multi-Disc-Sets werden als eine Entität angezeigt + +--- + +## Etappe 5: API + Auth + WebUI + +**Ziel:** Vollständiger Web-Dienst mit Echtzeit-Status und Job-Steuerung. + +**Was gebaut wird:** +- FastAPI mit JWT-Auth (Access 15min, Refresh 7 Tage), Rate-Limiting (100/min/API-Key) +- REST-Endpoints: Jobs erstellen/listen/abbrechen, Geräte verwalten, Einstellungen +- SSE-Stream für Echtzeit-Jobstatus +- React-UI (Vite-Build → statisch via Nginx): + - Dashboard mit Echtzeit-Kacheln (Job-Status, Queue, Disc-Einwurf) + - Job-Verlauf mit Fortschrittsbalken + - Metadaten-Preview mit Bestätigungs-Dialog + - Job-Detail mit Live-Log + - Ergebnis-View mit Ordnerstruktur-Preview + - Einstellungen (API-Keys, Transcoding, Backup-Pfade, Jellyfin-Config) + - Geräte-Verwaltung + +**Fertig wenn:** +- Commander kann UI im Browser öffnen und alles bedienen +- Jobs starten, stoppen, Verlauf einsehen +- Echtzeit-Updates via SSE funktionieren +- Alle Einstellungen werden gespeichert + +--- + +## Etappe 6: Sicherheit + Compliance + Hardening + +**Ziel:** Produktionsreif — sicher, compliant, robust. + +**Was gebaut wird:** +- SELinux/AppArmor Profile pro Container +- Read-only Bind-Mounts für System-Bibliotheken +- mTLS zwischen API ↔ Worker +- Netzwerk-Policy: UI→API (HTTPS), API↔Worker (mTLS), Worker↔Internet (nur API) +- PostgreSQL mit verschlüsselten Connections +- Source-Release-Endpoint (GPL-v3-Compliance) +- Lizenz-Dokumentation (MakeMKV, OpenSource-Komponenten) +- Backup-Hooks (PBS-Snapshot-Integration) +- Error-Handling: exponential backoff Retry (max 5), Circuit-Breaker für APIs + +**Fertig wenn:** +- Alle Container haben Security-Profile +- Netzwerkverkehr zwischen Containern ist verschlüsselt +- GPL-v3-Compliance-Checkliste abgehakt +- Backup-Hooks funktionieren + +--- + +## Etappe 7: Proxmox-Integration + Dokumentation + +**Ziel:** Ein-Click-Deploy auf Proxmox LXC. + +**Was gebaut wird:** +- Proxmox LXC Template (Debian 12 Slim) +- Ansible Playbooks für die Installation +- Dokumentation: Installation, Konfiguration, Troubleshooting +- Beispiel `docker-compose.yml` mit allen Umgebungsvariablen +- Makefile für lokale Entwicklung + +**Fertig wenn:** +- Ein neuer Container ist in 5 Minuten bereit +- `make up` startet alles lokal für Entwicklung +- Dokumentation ist vollständig und verständlich + +--- + +## Offene Punkte (aus KONZEPT.md) + +| Punkt | Etappe | Behandlung | +|-------|--------|------------| +| TMDB-Matching-Fehler bei Nischentiteln | Etappe 3 | Pre-Scan Confidence-Score + manueller Korrektur-Mechanismus | +| NFO-Format-Abhängigkeit von Jellyfin-Version | Etappe 4 | Kodi/NFO-Schema (stabil, gut dokumentiert) | +| Pre-Scan-Latenz (5–15s) | Etappe 3 | Akzeptabel, Parallelisierung möglich | +| TMDB-Bildrechte | Etappe 4 | Gelöst: TMDB API-ToS erlaubt private Nutzung | +| Hybrid-Discs | Etappe 1 | MVP erkennt nur Standard; als "Kann" notiert | +| Redis Single-Instance | Etappe 1 | MVP reicht; Cluster als "Später" | diff --git a/SAVEPOINT.md b/SAVEPOINT.md new file mode 100644 index 0000000..3c020de --- /dev/null +++ b/SAVEPOINT.md @@ -0,0 +1,39 @@ +# SAVEPOINT — Rippy + +## Aktueller Stand + +**vorbereitet — Bau beginnt in Zed.** + +Das Repo enthält das gehärtete Konzept und den Meilenstein-Plan. Kein Code ist bisher geschrieben. + +## Nächste Schritte + +1. **Etappe 1: Fundament** — Container-Infrastruktur + udev-Erkennung. + - Docker Compose mit 5 Containern (api, worker, ui, postgres, redis) + - udev-Regel + Daemon für Disc-Einwurf-Erkennung + - Device-Resolver (UUID/Serial) + - Basis-Celery-Job-Erstellung + +## Offene Fragen für den Bau + +- Welches Tool für DVD/Blu-ray? `makejungles` (OpenSource) oder `makemkvcon` (MakeMKV, kostenpflichtig nach Beta-Phase)? +- Go oder Python für den udev-Daemon? Go ist schneller, Python ist einfacher. +- Welche Port-Nummern? Standard (80/443/5432/6379) oder custom? +- TMDB API-Key: woher bekommt der Commander seinen? + +## Technologien (bereits festgelegt) + +| Komponente | Wahl | Quelle | +|------------|------|--------| +| API | FastAPI (Python) | KONZEPT.md | +| Worker | Celery + Redis (Python) | KONZEPT.md | +| UI | React + Vite → statisch | KONZEPT.md | +| DB | PostgreSQL | KONZEPT.md | +| Cache | Redis (AOF) | KONZEPT.md | +| Ripping CD | abcde + chromaprint | KONZEPT.md | +| Ripping DVD/BR | makejungles / makemkvcon | KONZEPT.md | +| Metadaten | TMDB + MusicBrainz + TheTVDB | KONZEPT.md | +| NFO | Kodi/NFO-Schema | KONZEPT.md | +| Deployment | Docker Compose | KONZEPT.md | +| Build-System | Dockerfile (multi-stage) | KONZEPT.md | +| CI | Gitea Pipelines | KONZEPT.md |