1.0.0 release snapshot

docs/getting-started/configuration.md

@@ -0,0 +1,151 @@
+# Ersteinrichtung
+
+Diese Seite ist die Betriebs-Checkliste vor dem ersten produktiven Lauf.
+
+## Ziel der Ersteinrichtung
+
+Vor dem ersten Job sollten fünf Bereiche sauber gesetzt sein:
+
+1. Pfade und Templates
+2. Laufwerk und Disc-Erkennung
+3. Metadatenzugang über TMDb
+4. Encode-Standards und Queue-Regeln
+5. optionale Automatisierung und Benachrichtigungen
+
+## Empfohlene Reihenfolge
+
+### 1. Basis in `Settings -> Konfiguration`
+
+Prüfe zuerst diese Kernfelder:
+
+- RAW- und Zielordner für Blu-ray, DVD, CD, Audiobooks und Converter
+- `Log Ordner`
+- `TMDb Read Access Token`
+- `MakeMKV Kommando`, `HandBrake Kommando`, `Mediainfo Kommando`
+- `FFmpeg Kommando`, `FFprobe Kommando`, `cdparanoia Kommando`, `mkvmerge Kommando`, falls du die jeweiligen Workflows nutzt
+
+Danach speichern.
+
+### 2. Pfade und Templates bewusst festlegen
+
+Wichtig für den Alltag:
+
+- Film-Workflows nutzen die RAW- und Film-Ausgabeordner sowie die Film-Output-Templates
+- Serien-Workflows nutzen zusätzlich die Serien-RAW-Ordner, die Serien-Zielordner und die Episode-/Multi-Episode-Templates
+- Audiobooks nutzen `Audiobook RAW-Ordner`, `Audiobook Output-Ordner`, `Audiobook RAW Template`, `Output Template (Audiobook)` und `Kapitel Template (Audiobook)`
+- Converter nutzt `Converter Raw-Ordner`, `Converter Ausgabe (Video)`, `Converter Ausgabe (Audio)` sowie `Output-Template (Video)` und `Output-Template (Audio)`
+- Downloads nutzen `Download ZIP-Ordner`
+
+Wenn du auf NAS, USB oder mit anderen Benutzern/Gruppen schreiben willst, prüfe auch die jeweils zugehörigen `Eigentümer ...`-Felder.
+
+### 3. Laufwerk und automatische Erkennung prüfen
+
+Relevant:
+
+- `Laufwerksmodus`
+- `Explizite Laufwerke`, falls du nicht mit Auto-Discovery arbeiten willst
+- `Automatische Disk-Erkennung`
+- `Polling Intervall (ms)` im Expertenmodus
+- `Laufwerk nach Rip auswerfen`
+
+Empfehlung:
+
+- Einzelnes Standardlaufwerk: `auto`
+- mehrere stabile Laufwerke oder ungewöhnliche Device-Mappings: `Explizite Laufwerke`
+
+### 4. TMDb und Metadatenverhalten festlegen
+
+Relevant:
+
+- `TMDb Read Access Token`
+- `Film-Sprache`
+- `Fallback Sprache`
+- `Coverart-Nachladen aktiv`
+- `Coverart-Prüfintervall (Stunden)`
+- `NFO nach Encode erzeugen`
+
+Diese Einstellungen wirken direkt in Metadatensuche, Serienzuordnung, Nachpflege von Covern und im finalen Output.
+
+### 5. Encode- und Review-Standards festlegen
+
+Für Video-Workflows besonders wichtig:
+
+- `Minimale Titellänge (Minuten)`
+- `TMDb Runtime-Abzug für Playlistfilter (%)`
+- `HandBrake Preset` und `HandBrake Extra Args` je Medium
+- `Review Audio-Sprachen (...)`
+- `Review UT-Sprachen (...)`
+- `Ausgabeformat`
+
+Praxis:
+
+- `Minimale Titellänge` filtert Bonusmaterial früh weg
+- `TMDb Runtime-Abzug ...` lockert bei problematischen Blu-rays die Laufzeitprüfung der Playlist-Kandidaten
+- Review-Sprachen bestimmen, welche Audio-/Untertitelspuren in der Review schon vorausgewählt sind
+
+### 6. Queue-Verhalten definieren
+
+Stelle diese vier Felder bewusst ein:
+
+- `Parallele Jobs`
+- `Max. parallele Audio CD Jobs`
+- `Max. Encodes gesamt (medienunabhängig)`
+- `Audio CDs: Queue-Reihenfolge überspringen`
+
+Damit steuerst du, wie aggressiv Ripster mehrere Jobs gleichzeitig startet.
+
+### 7. Optional: User-Presets und Standard-Zuordnungen
+
+Unter `Settings -> Encode-Presets` kannst du:
+
+- eigene HandBrake-User-Presets anlegen
+- Standard-Zuordnungen für `Blu-ray Film`, `Blu-ray Serie`, `DVD Film`, `DVD Serie` setzen
+
+Diese Defaults wirken später in der Review automatisch vorbefüllend.
+
+### 8. Optional: Benachrichtigungen
+
+Prüfe:
+
+- `PushOver aktiviert`
+- Token/User/optional Device
+- Event-Toggles wie `Bei manueller Auswahl senden`, `Bei Rip-Start senden`, `Bei Erfolg senden`
+
+Danach in `Settings` den Button `PushOver Test` ausführen.
+
+### 9. Optional: Automatisierung
+
+Erst wenn die Grundkonfiguration stabil ist:
+
+1. Skripte anlegen und testen
+2. Skriptketten aufbauen
+3. Cronjobs aktivieren
+
+## Funktionsprüfung
+
+Ein sinnvoller Kurztest:
+
+1. Disc in `Ripper` erkennen lassen
+2. `Analyse starten`
+3. TMDb-Metadaten übernehmen
+4. ggf. Playlist-/RAW-Entscheidung durchlaufen
+5. bis `Bereit zum Encodieren` kommen
+6. Encode starten
+7. Ergebnis in `Historie` prüfen
+
+## Typische Konfigurationsfehler
+
+| Symptom | Häufige Ursache |
+|---|---|
+| Disc wird nicht erkannt | Laufwerksmodus oder Auto-Erkennung passt nicht |
+| Playlist-Auswahl wirkt unplausibel | `Minimale Titellänge` oder `TMDb Runtime-Abzug ...` ist zu streng/zu locker |
+| falsche Spuren sind in der Review vorausgewählt | Review-Sprachfilter oder HandBrake-Args greifen unerwartet |
+| Ausgabe landet am falschen Ort | Profilpfade oder Templates greifen über Fallback |
+| Queue verhält sich unerwartet | `Parallele Jobs`, CD-Limit und Gesamtlimit widersprechen sich |
+
+## Weiter
+
+- [Erster Lauf](quickstart.md)
+- [GUI-Seiten](../gui/index.md)
+- [Workflows aus Nutzersicht](../workflows/index.md)
+- [Alle Einstellungen](../configuration/settings-reference.md)

docs/getting-started/index.md

@@ -0,0 +1,33 @@
+# Benutzerhandbuch Überblick
+
+Dieses Kapitel ist für den **Betrieb von Ripster im Alltag** geschrieben.
+
+## Zielgruppe
+
+- Anwender, die Discs verarbeiten wollen
+- Betreiber, die den täglichen Ablauf stabil fahren möchten
+- Power-User, die Queue/Skripte/Cron im UI steuern möchten
+
+## Kapitelstruktur
+
+| Kapitel | Zweck |
+|---|---|
+| [Voraussetzungen](prerequisites.md) | Produktions- vs. Dev-Voraussetzungen klar trennen |
+| [Installation](installation.md) | Ripster aufsetzen und starten |
+| [Ersteinrichtung](configuration.md) | Pfade, Tools und Metadaten korrekt setzen |
+| [Erster Lauf](quickstart.md) | Ein kompletter Job von Disc bis Datei |
+| [GUI-Seiten](../gui/index.md) | Alle Ansichten und Aktionen im Detail |
+| [Workflows](../workflows/index.md) | Typische Abläufe und Entscheidungen aus User-Sicht |
+
+## Wenn du neu startest
+
+1. [Voraussetzungen](prerequisites.md)
+2. [Installation](installation.md)
+3. [Ersteinrichtung](configuration.md)
+4. [Erster Lauf](quickstart.md)
+
+## Wenn Ripster bereits läuft
+
+1. [GUI-Seiten](../gui/index.md)
+2. [Workflows](../workflows/index.md)
+3. Bei Detailfragen: [Technischer Anhang](../appendix/index.md)

docs/getting-started/installation.md

@@ -0,0 +1,119 @@
+# Installation
+
+Die empfohlene Installation startet immer über `setup.sh`. `setup.sh` lädt das passende `install.sh` aus dem gewünschten Branch und übergibt alle weiteren Parameter unverändert an den eigentlichen Installer.
+
+Wichtig:
+
+- Standard-Einstieg: `setup.sh`
+- kein `curl | bash`
+- du musst die Tools nicht manuell vorinstallieren, sofern du sie nicht bewusst mit `--no-*` auslässt
+
+## Voraussetzungen
+
+- unterstütztes Linux-System
+- Root-Rechte oder `sudo`
+- Internetzugang während der Installation
+
+Der Installer erkennt aktuell:
+
+- Debian
+- Ubuntu
+- Linux Mint
+- Pop!_OS
+
+## Standardinstallation
+
+```bash
+wget -qO setup.sh https://raw.githubusercontent.com/Mboehmlaender/ripster/main/setup.sh
+bash setup.sh
+```
+
+Ohne `--branch` fragt `setup.sh` interaktiv nach dem gewünschten Branch.
+
+Die typischen Branches sind:
+
+- `main`: stabiles Release
+- `dev`: aktueller Entwicklungsstand
+
+## Installation mit Branch oder Optionen
+
+Beispiele:
+
+```bash
+bash setup.sh --branch main
+bash setup.sh --branch dev
+bash setup.sh --branch dev --dir /opt/ripster --user ripster --port 3001 --host 192.168.1.10
+```
+
+`setup.sh` wertet selbst nur `--branch` aus. Alles andere übernimmt `install.sh`.
+
+## Wichtige Optionen von `install.sh`
+
+| Option | Default | Zweck |
+|---|---|---|
+| `--branch <branch>` | `dev` | installiert genau diesen Git-Branch |
+| `--dir <pfad>` | `/opt/ripster` | Installationsverzeichnis |
+| `--user <benutzer>` | `ripster` | Systembenutzer für den Dienst |
+| `--port <port>` | `3001` | Backend-Port |
+| `--host <hostname|ip>` | automatisch ermittelte Host-IP | Hostname/IP für Webzugriff und CORS |
+| `--no-makemkv` | aus | MakeMKV nicht installieren |
+| `--no-handbrake` | aus | HandBrake nicht installieren |
+| `--no-nginx` | aus | nginx-Setup überspringen |
+| `--no-system-deps` | aus | Systemabhängigkeiten nicht nachinstallieren |
+| `--reinstall` | aus | bestehende Installation aktualisieren |
+
+## Was der Installer einrichtet
+
+Typischer Ablauf:
+
+1. Betriebssystem, Root-Rechte und Host prüfen
+2. Systemabhängigkeiten installieren
+3. Node.js 20 sicherstellen
+4. optional MakeMKV installieren
+5. optional HandBrakeCLI installieren
+6. optional nginx konfigurieren
+7. Repository nach `--dir` klonen oder aktualisieren
+8. Backend-/Frontend-Abhängigkeiten installieren
+9. Frontend bauen
+10. `backend/.env` und Laufzeitverzeichnisse vorbereiten
+11. `ripster-backend.service` anlegen und starten
+
+## Dienst prüfen
+
+```bash
+sudo systemctl status ripster-backend
+```
+
+Typische Aufrufe im Betrieb:
+
+```bash
+sudo journalctl -u ripster-backend -f
+sudo systemctl restart ripster-backend
+```
+
+## Update einer bestehenden Installation
+
+Standard:
+
+```bash
+sudo bash /opt/ripster/install.sh --reinstall
+```
+
+Wenn die Installation mit abweichenden Kernparametern eingerichtet wurde, dieselben Parameter wieder mitgeben:
+
+```bash
+sudo bash /opt/ripster/install.sh --reinstall --dir /opt/ripster --user ripster --port 3001 --host 192.168.1.10
+```
+
+Alternativ kannst du auch erneut über `setup.sh` gehen:
+
+```bash
+sudo bash /opt/ripster/setup.sh --reinstall
+```
+
+`--reinstall` aktualisiert die Installation, behält aber die persistenten Daten der bestehenden Instanz.
+
+## Danach weiter
+
+1. [Ersteinrichtung](configuration.md)
+2. [Erster Lauf](quickstart.md)

docs/getting-started/prerequisites.md

@@ -0,0 +1,58 @@
+# Voraussetzungen
+
+Die Voraussetzungen hängen davon ab, ob du Ripster produktiv installieren oder lokal entwickeln willst.
+
+## Produktionsbetrieb mit `setup.sh`
+
+Für den normalen Betrieb brauchst du nur die Basisvoraussetzungen. Die eigentlichen Tools werden vom Installer eingerichtet, sofern du sie nicht bewusst mit `--no-*` überspringst.
+
+### Pflicht
+
+- unterstütztes Linux-System
+- Root-Rechte oder `sudo`
+- Internetzugang während der Installation
+- optisches Laufwerk, wenn du Disc-Workflows nutzen willst
+
+Der Installer unterstützt aktuell:
+
+- Debian
+- Ubuntu
+- Linux Mint
+- Pop!_OS
+
+Standard-Einstieg:
+
+```bash
+wget -qO setup.sh https://raw.githubusercontent.com/Mboehmlaender/ripster/main/setup.sh
+bash setup.sh
+```
+
+### Laufwerk kurz prüfen
+
+```bash
+ls /dev/sr*
+lsblk | grep rom
+```
+
+### Optional vorab
+
+- TMDb Read Access Token für Film-/Serien-Metadaten
+- PushOver-Zugangsdaten für Benachrichtigungen
+
+Beides kann auch erst nach der Installation in `Settings` gesetzt werden.
+
+## Entwicklungsmodus
+
+Wenn du lokal entwickelst (`./start.sh`, `npm run dev`), gelten zusätzliche Voraussetzungen:
+
+- Node.js `>= 20.19.0`
+- `makemkvcon`, `HandBrakeCLI`, `mediainfo` im `PATH`
+
+Details: [Entwicklungsumgebung](../deployment/development.md)
+
+## Abschluss-Checkliste
+
+- [ ] Linux + Root/Sudo + Internet vorhanden
+- [ ] optisches Laufwerk vorhanden, falls Disc-Ripping genutzt werden soll
+- [ ] TMDb/PushOver-Zugangsdaten liegen bereit, falls diese Funktionen sofort genutzt werden sollen
+- [ ] im Dev-Modus zusätzlich Node.js und CLI-Tools lokal verfügbar

docs/getting-started/quickstart.md

@@ -0,0 +1,151 @@
+# Erster Lauf
+
+Dieser Ablauf führt einen typischen Disc-Job von Erkennung bis fertiger Datei durch.
+
+## 1. Disc erkennen
+
+1. `Ripper` öffnen
+2. Disc einlegen
+3. auf `Medium erkannt` warten
+
+Prüfen:
+
+- `Disk-Information` zeigt Device, Label und Laufwerksstatus
+- falls nicht: `Laufwerk neu lesen`
+
+Relevante Settings:
+
+- `Laufwerksmodus`
+- `Automatische Disk-Erkennung`
+- `Polling Intervall (ms)`
+
+## 2. Analyse starten
+
+Aktion:
+
+- `Analyse starten`
+
+Erwartung:
+
+- Status `Analyse`
+- danach der Metadaten-Dialog
+
+Relevantes Setting:
+
+- `Minimale Titellänge (Minuten)` beeinflusst bereits, welche Titel/Playlists Ripster später als relevant betrachtet
+
+## 3. Metadaten in TMDb bestätigen
+
+Im Dialog:
+
+1. Treffer suchen oder filtern
+2. Film oder Serie auswählen
+3. bei Serien zusätzlich `Disc-Nummer` setzen
+4. `Auswahl übernehmen`
+
+Mögliche Abzweigungen:
+
+- Duplikatfilm: `Übernahme erzwingen` oder `Multipart movie`
+- vorhandenes RAW: Entscheidungsdialog `weiterverwenden` oder `neu rippen`
+
+Relevante Settings:
+
+- `TMDb Read Access Token`
+- `Film-Sprache`
+- `Fallback Sprache`
+
+## 4. RAW- und Playlist-Entscheidungen
+
+Je nach Disc-Situation geht es jetzt unterschiedlich weiter.
+
+### Normalfall
+
+`Startbereit` -> `Rippen` -> `Mediainfo-Prüfung`
+
+### Vorhandenes RAW
+
+Kein neuer Rip, sondern erst eine Entscheidung:
+
+- vorhandenes RAW weiterverwenden
+- RAW löschen und Rip neu starten
+- bei passenden Film-Konstellationen optional Multipart mit Orphan-RAW
+
+### Playlist- oder Titelauswahl erforderlich
+
+Bei bestimmten Blu-ray-/DVD-Fällen erscheint `Warte auf Auswahl`.
+
+Dann bestätigst du:
+
+- eine Playlist
+- oder einen/mehrere HandBrake-Titel
+
+Relevante Settings:
+
+- `Minimale Titellänge (Minuten)`
+- `TMDb Runtime-Abzug für Playlistfilter (%)`
+
+## 5. Encode-Review abschließen
+
+Bei `Bereit zum Encodieren` prüfst du:
+
+- Titelwahl
+- Audio-Spuren
+- Untertitel
+- User-Preset oder HandBrake-Preset
+- Pre-/Post-Encode-Skripte und Ketten
+
+Dann:
+
+- `Encoding starten`
+
+Relevante Settings:
+
+- `HandBrake Preset` und `HandBrake Extra Args` je Medium
+- `Review Audio-Sprachen (...)`
+- `Review UT-Sprachen (...)`
+- `Ausgabeformat`
+- Standard-Zuordnungen unter `Settings -> Encode-Presets`
+
+## 6. Encoding überwachen
+
+Während `Encodieren`:
+
+- Fortschritt/ETA im Ripper
+- Queue-Status beobachten
+- bei Bedarf `Hardware`-Ansicht öffnen
+
+Relevante Settings:
+
+- `Parallele Jobs`
+- `Max. parallele Audio CD Jobs`
+- `Max. Encodes gesamt (medienunabhängig)`
+- `Hardware Monitoring aktiviert`
+- `Hardware Monitoring Intervall (ms)`
+
+## 7. Ergebnis verifizieren
+
+Nach `Fertig`:
+
+1. `Historie` öffnen
+2. Jobdetail prüfen
+3. Output-Pfad und Log kontrollieren
+
+Kontrollpunkte:
+
+- finale Datei liegt am erwarteten Template-Pfad
+- RAW-Ordner ist finalisiert
+- optional `.nfo` wurde erzeugt, falls aktiviert
+
+Relevante Settings:
+
+- Film-Output-Templates oder Serien-Templates
+- `Serien-Ordner (Blu-ray)` und `Serien-Ordner (DVD)` plus die Episode-/Multi-Episode-Templates
+- `NFO nach Encode erzeugen`
+
+## 8. Typische Folgeaktionen
+
+- falsche TMDb-Zuordnung: `TMDb neu zuweisen`
+- andere Trackauswahl: `Review neu starten`
+- erneuter Encode aus RAW: `RAW neu encodieren`
+- gleicher Plan erneut: `Encode neu starten`
+- Rip erneut versuchen: `Retry Rippen`