Geza

geza.html · GitHub

Was ist Geza?

Ein selbst gehostetes Portal, das einen öffentlichen Filme-/Serien-Katalog mit einem privaten Anschautagebuch verbindet: Besucher können ohne Login stöbern, suchen und Reviews lesen, während der Betreiber nach Login sein vollständiges Anschauverhalten, Statistiken und Bearbeitungsmöglichkeiten sieht.

Öffentlich & privat

Lokal starten

Voraussetzung: Docker mit Compose, kein separates Node.js oder PostgreSQL nötig.

Demo-Modus

Öffentliche Instanz zum Ausprobieren ohne eigene Installation: gezademo.polze.net.

Für eine eigene Demo-Instanz ./setup.ps1 -Mode demo ausführen. Die App läuft danach auf Port 3081 und importiert automatisch Beispieldaten (Einträge, Bewertungen, Reviews) — ideal zum Vorführen ohne echte Zugangsdaten.

Trakt-Import

Nach der Anmeldung unter Admin → Trakt-Export importieren die ZIP-Datei aus dem Trakt-Export hochladen. Geza entpackt sie in ein temporäres Verzeichnis, übernimmt nur passende JSON-Dateien für History, Bewertungen, Kommentare und Sammlung und entfernt die temporären Dateien danach wieder.

CLI-Alternative: entpackten Export in data/<trakt-export-ordner> ablegen und ausführen:

Trakt-Ereignis-IDs verhindern doppelte Importe, Wiederholungen bleiben erhalten. UTC-Zeitstempel werden für Berlin angezeigt. Der Epoch-Platzhalter von 1970 bleibt als unbekannter Zeitpunkt mit Originalwert erhalten. Mehrdeutige externe IDs werden im Importbericht gemeldet und nicht automatisch zusammengeführt.

Metadaten & Plex

Auf Episoden- und Staffelseiten können angemeldete Admins über Zuordnung korrigieren eine vorhandene Serie suchen und Staffel sowie Episodennummer ändern. Anschauereignisse, Bewertungen und Reviews bleiben am bisherigen Datensatz erhalten; erneute Trakt-Importe überschreiben die korrigierte Zuordnung nicht.

Unter Admin → Verbindungen TMDB Read Access Token, optional TVDB API-Key/PIN und Plex-URL/Token eintragen (verschlüsselt mit SESSION_SECRET gespeichert). Danach Fehlende Metadaten laden wählen — Priorität je Feld: manuelle Korrektur → Plex → TVDB bei Serien → TMDB.

Für Webhooks zusätzlich Account-ID, Server-UUID und ein zufälliges Webhook-Geheimnis setzen:

Unter Admin → Ereignisprotokoll (/admin/logs) stehen Webhook-Empfang, Ablehnungsgründe, Anbieterabfragen mit URL/HTTP-Status sowie Job-Ergebnisse und Wiederholungsversuche — über die Anfrage-ID lässt sich ein Webhook bis zur Verarbeitung verfolgen. Zugangsdaten, Cookies und vollständige Request-Bodies werden nicht gespeichert; Einträge älter als 14 Tage werden stündlich gelöscht.

Externe Reviews & Anbieterbewertungen

Unter den eigenen Reviews stehen öffentliche Blöcke „Reviews bei Freunden“. Admins legen mit „＋ Neu“ weitere Quellen mit Name, HTTPS-Link und optionaler Bewertung samt Skala an; zum Entfernen den Link leeren. Für eigene Quellen gibt es keine automatischen Abrufe.

Filmdienst und wortvogel.de werden für aufgerufene Filme im Hintergrund gesucht. Geza speichert nur Link und Sterne, keine fremden Review-Texte; wortvogel.de liefert keine Sternebewertung, nur den Link. Höchstens drei Kandidaten werden geprüft, unsichere oder mehrdeutige Treffer werden nicht veröffentlicht. Zwischen Abrufen liegen je Anbieter mindestens zehn Sekunden.

Detailseiten zeigen zusätzlich TMDB-Durchschnittsbewertungen sowie ausdrücklich als IMDb gekennzeichnete Plex-Bewertungen mit Quellenlink. TVDBs API-Score ist ein Popularitätswert und wird nicht als Sternebewertung ausgegeben.

Collections

Der Collections-Bereich fasst den Katalog nach Filmreihen, Genres, Bewertungen, Ländern und Erscheinungsjahren zusammen. Jede Kategorie lässt sich anklicken und filtert die Ergebnisliste entsprechend; Filmreihen-Zugehörigkeit wird automatisch über die Provider-Metadaten erkannt.

Serien, Staffeln & Serienkatalog

Unter dem Cover einer Serie oder Staffel wählst du zwischen der gesamten Serie und ihren Staffeln. Jede Staffel hat eigene Bewertungen und Reviews und zeigt darunter ihre Episoden; der Staffellink einer Episode führt zur passenden Staffel. Fehlt ein Staffelcover, erscheint das Seriencover.

Mit einem TMDB-Zugang unter Admin → Verbindungen ergänzt Geza den vollständigen Staffel- und Episodenkatalog jeder Serie, auch für Folgen, die nicht in Plex liegen. Beim Anlegen einer manuellen Serien- oder Staffelsichtung ist die Übertragung auf noch nicht gesehene Folgen vorausgewählt; später erscheinende Folgen bleiben ausgenommen. Einzelne Folgen lassen sich direkt in der Staffelliste nachtragen.

Link-Vorschau

Teilst du den Link zu einem Titel, erscheint eine Vorschau mit Cover, Titel samt Jahr, deiner Bewertung in Sternen und einem Teaser deiner öffentlichen Review. Spoiler-Reviews werden nie angeteasert. Voraussetzung ist die gesetzte PUBLIC_URL.

RSS-Feed (ABO)

Der Tab ABO neben „Sammlungen“ öffnet den Feed /feed.xml. Er enthält neue Bewertungen und Reviews mit Cover, Sternen, dem vollständigen Review-Text und einem Link zum Geza-Datensatz; Besucher kopieren die Adresse in ihren Feed-Reader.

Friends of Geza

Befreundete Geza-Instanzen zeigen sich gegenseitig, ob sie zu einem Titel eine Bewertung oder ein Review haben. Auf der Detailseite erscheint ein Kästchen „Bei befreundeten Instanzen“ mit dem Nickname der Instanz (Link zu deren Datensatz), der Zehnerbewertung und dem Hinweis „Review vorhanden“. Der Review-Text wird nie übertragen.

Film- & Personenverweise

In Reviews lassen sich per @m, @r und @a Filme, Regisseure und Darsteller aus dem eigenen Katalog verlinken. Personenverweise zeigen eine Filmvorschau; an Filmverweisen erscheint zusätzlich das Cover. Details stehen in der Review-Anleitung im Repository (docs/reviews.md).

Kommentare & Reaktionen

Besucher können öffentliche Reviews mit sechs Symbolen bewerten, ohne Name oder E-Mail-Adresse anzugeben, oder einen Textkommentar verfassen. Für Textbeiträge sind Name und E-Mail erforderlich, eine Website ist optional; die E-Mail-Adresse wird nicht veröffentlicht und verschlüsselt gespeichert.

Öffentliche Statistik

Jede öffentliche Detailseite besitzt einen Aufrufzähler. Admin-Aufrufe, bekannte Bots und Browser-Prefetches werden nicht gezählt, wiederholte Abrufe desselben Titels pro Berliner Kalendertag entdoppelt. Die öffentliche Statistik zeigt die zehn meistaufgerufenen, am häufigsten mit Reaktionen versehenen und meistkommentierten Filmseiten.

Die Startseite kann zwischen Frisch besprochen und Zuletzt kommentiert wechseln. Gleich bewertete Titel in den persönlichen Besten- und Schwächstenlisten wechseln zufällig durch.

Rumpelkammer & Bucketliste

Titel ohne Sichtung, Bewertung, Review und Bucketlisten-Eintrag – meist Bestandseinträge aus dem Trakt-Collection-Export oder Plex – liegen in der Rumpelkammer (Admin → Rumpelkammer) und sind öffentlich nicht sichtbar. Dort lassen sie sich einzeln oder gesammelt bearbeiten, bewerten, in die Bucketliste verschieben oder löschen. Gelöschte Titel legen Trakt-Import und Plex-Scan nicht erneut an.

Die Bucketliste sammelt ungesehene Wünsche: ungesehene Plex-Filme, ungesehene Serien und bei begonnenen Serien die vorhandenen Staffeln ohne gesehene Episode. Der Plex-Bibliotheks-Scan läuft täglich um 03:00 Uhr (einstellbar); „Änderungen vorab prüfen“ zeigt die geplanten Zuordnungen, ohne sie zu speichern. Per „+“ lassen sich Titel auch per TMDB-Suche manuell ergänzen.

Plex-Abgleich & Jobs

Der Plex-Abgleich hält Bibliotheksgrenzen strikt ein, isoliert unvollständige Metadaten und verwendet gespeicherte Zuordnungsentscheidungen bei späteren Läufen wieder. Gemeinsame Scanregeln und gezieltere Metadatenabfragen reduzieren unnötige Plex-Aufrufe.

Unter Admin → Automatische Jobs stehen der Plex-Scan mit Startzeit, letztem Lauf und Ein/Aus-Schalter. Jobs zeigen Fortschritt, Startzeit, letzte Aktivität, Fehleralter und verlinkte Ergebnisse pro Titel mit Ziel und Begründung; Anbieter-ID-Konflikte lassen sich vergleichen und korrigieren, Aufträge erneut prüfen.

Optional gibt es ein Plex-Diagnoseprotokoll mit sicherem Export und einen Admin-Hinweis auf ausbleibende Webhooks. Fehlende Gesehen-Markierungen in Plex lassen sich optional aus Gezas Anschauhistorie wiederherstellen (standardmäßig deaktiviert); Anschauzeitpunkte können zusätzlich manuell aus Plex geladen werden.

Länder & Genres

Länder und Genres aus Plex, TMDb und TVDb werden normalisiert; Dubletten lassen sich im Admin unter /admin/facetten zusammenführen, Zuordnungen reversibel lösen, Originalwerte bleiben erhalten. Plex-Tags mit Semikolon werden in einzelne Genres aufgeteilt. Anbieter-IDs (TMDB, IMDb usw.) sind in den Mediendetails bearbeitbar.

Datenschutz

Eine öffentliche Datenschutzseite beschreibt Serverprotokolle, Aufrufzählung, funktionale Cookies, Kommentare und Betroffenenrechte. Verantwortlicher, Kontaktanschrift, E-Mail-Adresse und Hosting-Anbieter werden zentral im Adminbereich gepflegt und sollten vor dem öffentlichen Betrieb vollständig eingetragen sein. Geza setzt keine Werbe- oder Analyse-Cookies ein; die verbleibenden Cookies dienen ausschließlich Anmeldung, Reaktionszuordnung und Missbrauchsschutz.

Hosting & Google

Auf dem Zielserver in .env die öffentliche URL setzen, z. B. PUBLIC_URL=https://deine-domain:PORT. Ein vorhandener HTTPS-Reverse-Proxy kann auf 127.0.0.1:3080 weiterleiten; ohne vorhandenen Proxy gibt es eine optionale Caddy-Konfiguration über compose.hosted.yaml.

Sicherung & Updates

Sicherung: ./scripts/backup.ps1 (Windows) bzw. sh scripts/backup.sh (Linux). Zusätzlich .env sicher aufbewahren, da ihr Schlüssel für die Provider-Zugangsdaten benötigt wird. Datenbanksicherungen enthalten auch gespeicherte Poster; im Adminbereich gibt es zusätzlich einen JSON-Export.

Wiederherstellung in eine leere Zieldatenbank:

Updates nach Sicherung: git pull --ff-only, docker compose build app, docker compose up -d. Migrationen laufen vor App und Worker. Das benannte Datenbankvolume überlebt Containerwechsel — docker compose down -v löscht es. Ein Code-Rollback allein macht Migrationen nicht rückgängig.

Server-Migration

Für einen kompletten Serverumzug erstellt Geza eine verschlüsselte .geza-Backup-Datei mit Datenbank, Postern und Konfiguration. Auf dem Zielserver reicht die Setup-Routine mit dieser Datei, ohne manuelle Datenbankarbeit oder separaten pg_restore-Lauf.

Prüfungen

Mit lokalem Node.js: npm ci, npm run lint, npm run test:unit, npm run db:migrate, npm run test:integration, npm run build. Datenbankbefehle benötigen DATABASE_URL für eine Testdatenbank.

Die GitHub-CI folgt Adolar Songster und blöki: Typprüfung, Tests, Build, Trivy, Gitleaks, CodeQL und Image-Scan. Dependabot prüft npm, Docker und GitHub Actions montags mit gruppierten Minor-/Patch-Updates.

Rechtliches & Versionsstand

Aktueller Stand: v1.8.0. Änderungsverlauf siehe GitHub Releases.