docs: README, Design-Dokumentation, Changelog und Seed
README mit Installation, Update-Weg und Backup-Anleitung; docs/DESIGN.md hält Marke, Farbwerte samt gemessener Kontraste und die Bausteine fest. Changelog nach Keep a Changelog, Release-Notes zusätzlich unter releases/.
This commit is contained in:
Florian Wilde
@@ -0,0 +1,198 @@
|
||||
<p align="center">
|
||||
<img src="public/brand/flimmer-logo.svg" alt="Flimmer" width="380">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<b>Serien und Filme tracken — selbst gehostet, ohne fremde Konten.</b><br>
|
||||
Episodenfortschritt, eigene Universen mit mehreren Reihenfolgen, Statistiken
|
||||
und Benachrichtigungen, wenn es weitergeht.
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
**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.
|
||||
|
||||
## 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.
|
||||
- **REST-API und PWA** — dokumentierte Schnittstelle mit eigenen API-Schlüsseln,
|
||||
installierbar auf dem Startbildschirm.
|
||||
|
||||
## 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 <http://localhost:3000>. 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 run icons` | Favicon und PWA-Icons aus dem SVG-Logo neu erzeugen |
|
||||
|
||||
Aufbau des Projekts:
|
||||
|
||||
```
|
||||
src/
|
||||
app/ Routen (App Router), API-Endpunkte
|
||||
components/ Wiederverwendbare Bausteine
|
||||
lib/ Serverseitige Logik: DB, Auth, TMDB, Benachrichtigungen
|
||||
i18n/ Oberflächentexte
|
||||
prisma/ Schema, Migrationen, Seed
|
||||
public/brand/ Logo in allen Varianten
|
||||
docker/ Entrypoint des Containers
|
||||
docs/ Anleitung, Design-Dokumentation
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user