From 61c38a0d145ed84ed86b4eba885a9b3f916955d4 Mon Sep 17 00:00:00 2001 From: Hitonabi Date: Sat, 25 Jul 2026 23:02:46 +0200 Subject: [PATCH] docs(readme): eigener Abschnitt fuer Dockge, Portainer, Arcane und Shell Commander-Plan fuer die Uebergabe: "Repo auf den Dockge-Server laden, Compose reinhauen, Profit?!" - und genau da sitzt die Falle, in die jeder zuerst tappt. DER KERN, der jetzt oben im Abschnitt steht: Rippy hat KEINE Registry-Images. api, worker und ui werden aus dem Repo gebaut (build: context: .). Die Compose-Datei allein ist deshalb wertlos - in ein leeres Verzeichnis kopiert gibt es sofort "failed to read dockerfile". Daraus folgt fuer JEDE Oberflaeche dieselbe Regel: das Repo muss dort liegen, wo die Oberflaeche den Stack baut. Je Werkzeug der konkrete Weg, weil sie sich genau darin unterscheiden: - Dockge kann das Repo NICHT selbst holen -> hinein in den Stacks-Ordner klonen (Standard /opt/stacks). Dann ist die Compose des Repos die des Stacks, und man darf den Stack gerade NICHT neu in Dockge anlegen - sonst liegt eine leere Compose in einem anderen Ordner. - Portainer KANN es selbst holen -> Stacks > Add stack > Repository mit Git-URL. Web-Editor und Upload funktionieren nicht (kein Build-Kontext). Geraeteknoten dort als Stack-Umgebungsvariablen statt .env. - Arcane: Repo auf dem Host, Deploy per Shell - der Git-Sync zieht nicht selbststaendig (auf dieser Installation seit Wochen die geuebte Praxis). - Shell: unveraendert git clone + sudo ./install.sh. Dazu die Vorab-Pruefung als gemeinsamer Einstieg: ./install.sh --nur-pruefen braucht kein root, aendert nichts und nennt vor allem die ECHTEN Geraeteknoten - der einzige Punkt, der zuverlaessig zuschlaegt. RICHTIGSTELLUNG an mir selbst: Ich hatte die Mount-Propagation als Huerde dargestellt. Auf den meisten systemd-Hosts ist / schon rshared und /srv/rippy/ media erbt das - da ist nichts zu tun. Nur wenn Docker ueber "not a shared mount" klagt, braucht es die Shell. Steht jetzt so drin. Stoerungstabelle von vier auf sechs Faelle: "failed to read dockerfile" und "Worker startet nicht, /dev/sgN fehlt" ergaenzt - die beiden, die ein Oberflaechen-Nutzer als erste sieht. Interne Verweise gegengeprueft, alle vier loesen auf. Co-Authored-By: Claude Opus 5 --- README.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3254cb2..f3f82be 100644 --- a/README.md +++ b/README.md @@ -58,12 +58,105 @@ git pull && sudo ./install.sh --- +## Mit einer Docker-Oberfläche (Dockge, Portainer, Arcane) + +**Die eine Sache, die du wissen musst:** Rippy hat **keine fertigen Images in +einer Registry.** Die drei Dienste `api`, `worker` und `ui` werden aus dem Repo +gebaut (`build: context: .`). Die Compose-Datei allein ist deshalb wertlos — +wer sie in ein leeres Verzeichnis kopiert, bekommt sofort +*„failed to read dockerfile"*. + +Daraus folgt für **jede** Oberfläche: **das Repo muss dort liegen, wo die +Oberfläche den Stack baut.** Alles andere ist Kleinarbeit. + +| | kann das Repo selbst holen? | Weg | +|---|---|---| +| **Shell** | — | `git clone` + `sudo ./install.sh` | +| **Dockge** | nein | Repo **in** den Stacks-Ordner klonen | +| **Portainer** | **ja** | Stack aus *Repository* (Git-URL) | +| **Arcane** | nein | Repo auf dem Host, Deploy per Shell | + +### Vorab-Prüfung — braucht kein root, ändert nichts + +Egal welche Oberfläche: Führe nach dem Klonen einmal das hier aus. Es sagt dir +in fünf Sekunden, ob die Maschine passt — vor allem, **welche Geräteknoten dein +Laufwerk wirklich hat**: + +```bash +./install.sh --nur-pruefen +``` + +### Dockge + +Dockge verwaltet Stacks als Verzeichnisse. Klone das Repo **in** den +Stacks-Ordner (Standard `/opt/stacks`, bei dir ggf. anders): + +```bash +cd /opt/stacks +git clone rippy +cd rippy && ./install.sh --nur-pruefen +``` + +Dockge zeigt `rippy` danach als Stack an, und „Start" baut die Images. Du musst +**keine Compose-Datei einfügen** — die des Repos ist die des Stacks. Lege den +Stack also **nicht** neu in Dockge an, sonst landet eine leere Compose-Datei in +einem anderen Ordner und der Bau scheitert. + +### Portainer + +Portainer kann das Repo selbst klonen, das ist hier der bequemste Weg: +**Stacks → Add stack → Repository**, Git-URL eintragen, Compose-Pfad +`docker-compose.yml`. Der Web-Editor und „Upload" funktionieren **nicht** — +beide liefern keinen Build-Kontext. + +Die Geräteknoten trägst du als Stack-Umgebungsvariablen ein (statt in eine +`.env`), falls sie von `/dev/sr0` und `/dev/sg1` abweichen: + +``` +OPTICAL_SR=/dev/sr0 +OPTICAL_SG=/dev/sg0 +``` + +Welche es sind, sagt dir auf dem Host `lsscsi -g` — oder die Vorab-Prüfung oben. + +### Arcane + +Das Repo liegt auf dem Host (z. B. `~/projects/rippy`), Arcane verwaltet die +Container. Deployt wird per Shell — Arcanes Git-Sync zieht **nicht** +selbstständig: + +```bash +cd ~/projects/rippy && git pull --ff-only && docker compose up -d --build +``` + +### Was keine Oberfläche für dich tun kann + +Drei Dinge passieren auf dem **Host**, nicht im Container — deshalb gibt es +`install.sh` überhaupt: + +1. **Geräteknoten.** MakeMKV braucht `/dev/srN` **und** den passenden + `/dev/sgM`; die sg-Nummer ist je Rechner anders. Stimmt sie nicht, **startet + der Worker-Container gar nicht.** Das ist der Fehler, der praktisch immer als + erster kommt. +2. **Ablage-Ordner** `/srv/rippy/media` und `/srv/rippy/makemkv`. +3. **Mount-Propagation** (`rshared`) für das Einhängen von NAS-Freigaben aus dem + UI. Auf den meisten systemd-Hosts ist `/` schon `rshared` und es ist nichts + zu tun — nur wenn `docker compose up` über *„not a shared mount"* klagt, + braucht es die Shell. + +Punkt 1 ist der einzige, der zuverlässig zuschlägt. `sudo ./install.sh` erledigt +alle drei; danach kannst du den Stack dauerhaft über die Oberfläche fahren. + +--- + ## Wenn etwas nicht geht -Die vier Fälle, die praktisch alles abdecken: +Die sechs Fälle, die praktisch alles abdecken: | Symptom | Ursache & Lösung | |---|---| +| **`failed to read dockerfile`** | Die Compose-Datei liegt ohne das Repo da. Rippy hat **keine Registry-Images**, die drei Dienste werden gebaut. Siehe **[Mit einer Docker-Oberfläche](#mit-einer-docker-oberfläche-dockge-portainer-arcane)**. | +| **Worker-Container startet nicht, `/dev/sgN` nicht gefunden** | Die sg-Nummer ist **je Rechner anders**; die Vorgaben `sr0`/`sg1` passen nur zufällig. `./install.sh --nur-pruefen` sagt dir die richtigen (oder `lsscsi -g`), dann in die `.env` bzw. als Stack-Variablen eintragen. **Der Fehler, der praktisch immer als erster kommt.** | | **„Kein optisches Laufwerk gefunden"** | In einer **VM**? Das Laufwerk muss per **USB-Passthrough** durchgereicht werden, nicht als emuliertes CD-ROM (`media=cdrom`) — das kann keine SCSI-Kommandos, MakeMKV sieht es nie. Proxmox: `qm set -usb0 host=:,usb3=1`. Auf echter Hardware: `ls /dev/sr*` prüfen. | | **Build bricht beim MakeMKV-Download ab** | Cloudflare drosselt manchmal. Der zuverlässige Weg: Tarballs von makemkv.com/download händisch nach `docker/worker/vendor/` legen, dann `sudo ./install.sh` erneut — der Build nimmt sie von dort und braucht kein Netz. Hast du eine eigene Quelle (Spiegel im LAN), trage sie als `MAKEMKV_URL_FALLBACK` in die `.env` ein; sie wird automatisch versucht, wenn makemkv.com nicht liefert. | | **Kompression läuft ewig** | Deine CPU kann kein AVX2. Rippy zeigt das jetzt selbst an (Einstellungen → System, „Vektorbefehle"). Siehe **[Rippy schneller machen](#rippy-schneller-machen)**. |