Serien und Filme tracken — selbst gehostet, ohne fremde Konten.
Episodenfortschritt, eigene Universen mit mehreren Reihenfolgen, Statistiken
und Benachrichtigungen, wenn es weitergeht.
---
**Flimmer** ist ein selbst hostbarer Tracker für Serien und Filme — benannt nach
der Flimmerkiste und dem warmen Flimmern, das ein Bildschirm im dunklen Zimmer
verbreitet. Metadaten kommen von [TMDB](https://www.themoviedb.org/), die Daten
bleiben auf deinem Server.
> **Bebilderte Anleitung:** [docs/ANLEITUNG.md](docs/ANLEITUNG.md) —
> führt einmal durch die ganze Anwendung.
> **Schnittstelle:** [docs/API.md](docs/API.md).
## Was Flimmer kann
- **Tracking** — Serien und Filme mit Status (Schaue gerade, Pausiert,
Abgeschlossen, Abgebrochen, Watchlist), Episodenfortschritt einzeln oder
staffelweise, „+1 Episode"-Knopf, Rewatch-Zählung, Bewertung, Notizen, Tags.
- **Universen** — MCU, Star Wars, Wizarding World … beliebige Filme *und* Serien
in einem Universum bündeln, mit mehreren Reihenfolgen (Erscheinung,
Story-Chronologie, Einsteiger-Route) und Gesamtfortschritt.
- **Metadaten von TMDB** — Suche, Poster, Staffeln und Episoden, offizielle
Collections, Streaming-Verfügbarkeit in deiner Region.
- **Benachrichtigungen** — bei neuen Episoden und Releases, per E-Mail, ntfy,
Gotify oder Webhook (Discord/Slack-kompatibel), pro Nutzer einstellbar.
- **Mehrere Nutzer** — jede Person hat ihre eigene Bibliothek; Universen lassen
sich teilen. Der erste registrierte Zugang wird Administrator.
- **Übersicht, Kalender und Statistik** — was als Nächstes dran ist, wann welche
Episode läuft, und wie viel Zeit wohin geflossen ist.
- **Import und Export** — aus Trakt.tv oder CSV hinein, als CSV oder JSON hinaus.
- **REST-API und PWA** — dokumentierte Schnittstelle mit eigenen API-Schlüsseln,
installierbar auf dem Startbildschirm, mit Offline-Rückfall.
- **Papierkorb statt Löschen** — 30 Tage Bedenkzeit, und jede Sichtung lässt sich
mit einem Klick zurücknehmen.
## Schnellstart
Voraussetzungen: Docker und Docker Compose.
```bash
git clone https://git.wilde-server.de/florian.wilde/flimmer.git
cd flimmer
cp .env.example .env
```
In der `.env` mindestens diese drei Werte setzen:
```dotenv
POSTGRES_PASSWORD=ein-langes-zufaelliges-passwort
AUTH_SECRET=noch-ein-langes-zufaelliges-geheimnis
APP_URL=https://flimmer.example.com
```
Geheimnisse erzeugen:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
Dann starten:
```bash
docker compose up -d
```
Flimmer läuft auf . Der **erste** Zugang, der sich
registriert, wird automatisch Administrator — lege ihn also gleich an. Danach
lässt sich die Registrierung in der Verwaltung schließen.
### TMDB-Schlüssel
Ohne TMDB findet die Suche keine Metadaten. Der Schlüssel ist kostenlos:
1. Konto auf [themoviedb.org](https://www.themoviedb.org/signup) anlegen
2. Unter *Einstellungen → API* einen Schlüssel beantragen
3. In die `.env` eintragen und `docker compose up -d` erneut ausführen:
```dotenv
TMDB_API_KEY=dein-schluessel
TMDB_REGION=DE
TMDB_LANGUAGE=de-DE
```
## Betrieb hinter einem Reverse Proxy
`APP_URL` muss auf die öffentliche Adresse zeigen — daraus werden Links in
Benachrichtigungen und der OIDC-Rücksprung gebildet. Als Healthcheck eignet
sich `/api/health`; der Endpunkt prüft auch die Datenbankverbindung.
Beispiel für Caddy:
```caddyfile
flimmer.example.com {
reverse_proxy flimmer:3000
}
```
## Aktualisieren
```bash
cd flimmer
git pull
docker compose build
docker compose up -d
```
Datenbankmigrationen laufen automatisch beim Start des Containers — ein eigener
Handgriff ist nicht nötig. **Vor** einem Update ein Backup zu ziehen ist
trotzdem eine gute Angewohnheit.
## Backup
Alles, was zählt, steckt in der Datenbank; das Volume `flimmer-data` enthält
nur den Bild-Cache und lässt sich jederzeit neu aufbauen.
```bash
# Sicherung
docker compose exec -T db pg_dump -U flimmer -d flimmer --clean --if-exists \
| gzip > flimmer-$(date +%F).sql.gz
# Rückspielen
gunzip -c flimmer-2026-09-01.sql.gz \
| docker compose exec -T db psql -U flimmer -d flimmer
```
Für einen nächtlichen Lauf genügt ein Cron-Eintrag mit demselben Befehl.
Wer zusätzlich den Bild-Cache sichern will:
```bash
docker run --rm -v flimmer_flimmer-data:/data -v "$PWD":/backup alpine \
tar czf /backup/flimmer-data.tar.gz -C /data .
```
## Konfiguration
Sämtliche Einstellungen laufen über Umgebungsvariablen; die vollständige Liste
mit Erklärungen steht in [`.env.example`](.env.example). Die wichtigsten:
| Variable | Bedeutung |
|---|---|
| `APP_URL` | Öffentliche Adresse der Instanz |
| `AUTH_SECRET` | Geheimnis für Sitzungen — mindestens 32 Zeichen |
| `TMDB_API_KEY` | TMDB-Schlüssel für Metadaten |
| `TMDB_REGION` | Region für die Streaming-Verfügbarkeit (Standard `DE`) |
| `ALLOW_REGISTRATION` | Selbstregistrierung bei der Erstinbetriebnahme |
| `ENABLE_SCHEDULER` | Eingebauter Hintergrundlauf für Sync und Benachrichtigungen |
| `SMTP_*` | E-Mail-Versand |
| `OIDC_*` | Optionale SSO-Anbindung (Authelia, Keycloak, Authentik …) |
## Entwicklung
```bash
npm install
docker compose -f docker-compose.dev.yml up -d # nur PostgreSQL
cp .env.example .env # DATABASE_URL auf localhost:5439
npm run db:migrate
npm run db:seed # Demo-Konten
npm run dev
```
| Befehl | Wirkung |
|---|---|
| `npm run dev` | Entwicklungsserver |
| `npm run build` | Produktionsbuild |
| `npm run typecheck` | TypeScript prüfen |
| `npm run db:migrate` | Migration erzeugen und anwenden |
| `npm run db:studio` | Prisma Studio |
| `npm run db:seed` | Beispieldaten |
| `npm test` | Testlauf gegen die Entwicklungsdatenbank (braucht keinen TMDB-Schlüssel) |
| `npm run icons` | Favicon und PWA-Icons aus dem SVG-Logo neu erzeugen |
| `npm run screenshots` | Screenshots der Anleitung neu aufnehmen |
Ohne TMDB-Schlüssel lässt sich die Suche mit einem lokalen Ersatz ausprobieren,
der aus den Beispieldaten antwortet:
```bash
node --import tsx scripts/tmdb-stub.mjs 3099
TMDB_API_KEY=stub TMDB_BASE_URL=http://127.0.0.1:3099/3 npm run dev
```
Aufbau des Projekts:
```
src/
app/ Routen (App Router), API-Endpunkte, Server-Aktionen
components/ Wiederverwendbare Bausteine
lib/ Serverseitige Logik: DB, Auth, TMDB, Tracking, Statistik,
Universen, Benachrichtigungen, Abgleich, Import/Export
i18n/ Oberflächentexte
prisma/ Schema, Migrationen, Seed samt Beispielkatalog
tests/ Testlauf mit nachgebildeten TMDB-Antworten
public/brand/ Logo in allen Varianten
docker/ Entrypoint des Containers
docs/ Anleitung mit Screenshots, API, Design-Dokumentation
```
### Automatisierung
Unter `.gitea/workflows/` liegen zwei Abläufe für Gitea Actions: `ci.yml`
prüft bei jedem Push Typen, Tests und Produktionsbuild gegen eine echte
PostgreSQL-Instanz, `release.yml` legt beim Pushen eines Versions-Tags das
Release an — mit den Notizen aus `releases/vX.Y.Z.md`.
## Hintergrundlauf
Einmal täglich frischt Flimmer laufende Serien bei TMDB auf, meldet neue
Episoden, prüft die Verfügbarkeit von Watchlist-Titeln und leert den
Papierkorb. Gesteuert wird das über `ENABLE_SCHEDULER` und `SYNC_HOUR`.
Wer lieber einen eigenen Cron benutzt, setzt `ENABLE_SCHEDULER=false`, vergibt
ein `CRON_SECRET` und ruft auf:
```bash
curl -X POST -H "Authorization: Bearer $CRON_SECRET" https://flimmer.example.com/api/cron/sync
```
In der Verwaltung lässt sich der Lauf jederzeit von Hand anstoßen.
## Technik
Next.js (App Router) mit TypeScript, PostgreSQL über Prisma, Tailwind CSS.
Warum Next und nicht SvelteKit: Oberfläche, REST-API und Hintergrundläufe
stecken in **einem** Deployment, Server Components halten den Datenbankzugriff
serverseitig, und der `standalone`-Build ergibt ein schlankes Image ohne
Build-Werkzeuge. Für ein selbst gehostetes Werkzeug zählt vor allem, dass ein
einziger Container genügt.
## Lizenz
MIT — siehe [LICENSE](LICENSE).
Metadaten stammen von TMDB. Flimmer wird von TMDB weder betrieben noch
unterstützt.