Geza

geza.html · GitHub

Geza ist ein Film- und Serienportal mit öffentlichen Bewertungen und Reviews sowie einem privaten Anschautagebuch. Gebaut mit Next.js, PostgreSQL und Docker Compose.

Erstes Release: Geza ist derzeit Version v1.0.0.

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

Bereich	Sichtbarkeit
Katalog, Suche, Detailseiten	Öffentlich
Zehnerbewertungen und Reviews	Öffentlich (neue/importierte Reviews standardmäßig öffentlich, im Editor als Entwurf speicherbar)
History ohne Login	Nur Anschauereignisse mit mindestens einer Bewertung oder einem öffentlichen Review, alle anderen ausgeblendet
Nach Login	Alle Anschauereignisse ohne Filterung, Home, Data, persönliche Statistik, Bearbeitung und Export

Re-Import: Ein erneuter Trakt-Import behält die bestehende Review-Sichtbarkeit bei — ein bereits als Entwurf gespeichertes Review wird nicht automatisch wieder öffentlich.

Lokal starten

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

Setup-Skript ausführenWindows: ./setup.ps1 · Linux/macOS: sh setup.sh. Erzeugt .env mit zufälligen Zugangsdaten und baut das Image; vorhandene Einstellungen bleiben erhalten.

Admin anlegenOhne vorhandenes Admin-Konto zeigt /login beim ersten Start automatisch eine Maske zum Anlegen des Admins. Danach ist diese Einrichtung gesperrt.

ÖffnenAnwendung unter http://localhost:3080, Anmeldung unter /login, Provider-Zugänge nach Anmeldung unter Admin.

Bindung: Die lokale App ist nur an 127.0.0.1 gebunden. Der Datenbankport ist im normalen Betrieb geschlossen; compose.dev.yaml stellt bei Bedarf PostgreSQL auf 127.0.0.1:5439 bereit.

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-noyse ablegen und ausführen:

docker compose exec -T worker node --import tsx scripts/import.ts /imports/trakt-export-noyse

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:

https://<deine-domain>/api/plex/DEIN-WEBHOOK-GEHEIMNIS
Unterstützt: media.scrobble und media.rate. userRating wird als 0–10 interpretiert, 0 entfernt die Bewertung.

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.

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.

Sitemap: Bei gesetzter PUBLIC_URL werden /sitemap.xml und auf jeweils 10.000 URLs aufgeteilte /sitemaps/0, /sitemaps/1 usw. aktiviert. Nur öffentliche Detailseiten werden eingetragen. Ohne Domain-Konfiguration liefert die Sitemap 404 und die lokale Vorschau ist noindex; private Seiten und Suchergebnisse werden nie indexiert.

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:

docker compose stop app worker
docker compose cp backups/DEIN-BACKUP.dump db:/tmp/restore.dump
docker compose exec -T db pg_restore -U geza -d geza --exit-on-error /tmp/restore.dump
docker compose up -d app worker

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.

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.0.0. Änderungsverlauf siehe GitHub Releases.