d4rk_media/README.md

# d4rk_media

Eigener Medien-Dienst für alle FiveM-Ressourcen: Dateien annehmen, ablegen,
ausliefern, in einem Dashboard verwalten. **Ein Container**, SQLite, Dateien auf
einer Platte.

Läuft unter **https://media.d4rkst3r.de** — Dashboard und API an der
Wurzel, Dateien unter `/f/`.

```
vehicles/adder.webp   →   https://media.d4rkst3r.de/f/vehicles/adder.webp
```

**Der Pfad ist der Schlüssel.** `vehicles/adder.webp` bleibt
`vehicles/adder.webp`, damit die Vorlage in einem Skript schlicht
`{model}.webp` lauten kann. Die Adressen stehen nirgends in der Datenbank — sie
werden bei jeder Antwort aus `PUBLIC_URL` gebaut. Ein Umzug auf einen anderen
Namen ist eine geänderte Variable, kein Datenbankeingriff.

| | |
|---|---|
| **Anleitung für Skripte** | [Wiki](https://git.d4rkst3r.de/D4rkst3r/d4rk_media/wiki) — Quelle ist `docs/` |
| **Stand und Reihenfolge** | `ROADMAP.md` |
| **Arbeitsweise** | `CLAUDE.md` — prüfen statt raten |

---

## Starten

```bash
cp .env.example .env      # PUBLIC_URL und ADMIN_PASSWORD ausfüllen
docker compose up -d --build
```

Das war es. Ein Container, ein Volume, kein zweiter Dienst.

**In Portainer:** Stacks → Add stack → Repository, `Compose path:
docker-compose.yml`. Die Werte kommen als Stack-Variablen.

> **`Compose path` nimmt genau EINE Datei.** Ergänzungen werden stillschweigend
> übergangen — alle Container gesund, alles 502. Das hat beim Vorgänger einen
> Nachmittag gekostet.

### An der Oberfläche arbeiten

```bash
npm --prefix server/ui install
npm --prefix server/ui run dev
```

Läuft auf `localhost:5173` und leitet `/api` und `/f` an den Container weiter.
Dass das Sitzungs-Cookie dabei ankommt, liegt an einer Ausnahme: es trägt
`Secure`, und ein Browser nimmt so eines über `http` **nur auf localhost** an.

---

## Was der Dienst kann

**Hochladen** — über die Skript-API mit Token (drei Rumpfformen: multipart,
Base64, rohe Bytes) oder aus dem Dashboard per Ziehen und Ablegen. Bilder,
Videos, Ton, PDF. Ein **ZIP wird ausgepackt** statt abgelegt, und die Ordner
darin bleiben erhalten — 3670 Bilder einzeln ins Fenster zu ziehen ist keine
Bedienung.

**Ausliefern** — mit ETag, `304`, Bereichsanfragen und `nosniff`. Vorschaubilder
werden beim Upload erzeugt (320 px WebP): aus 7,5 MB je Galerieseite werden
766 KB. Bei **Video** ist es ein Standbild aus dem Clip (ein Zehntel hinein, weil
viele mit Schwarz beginnen), bei **Ton** das eingebettete Titelbild; die Kachel
trägt zusätzlich die Laufzeit.

**Sparen, ohne Adressen zu ändern** — neben jedem PNG und JPEG liegt eine
WebP-Fassung, ausgeliefert unter *derselben* Adresse je nach `Accept` des
Aufrufers. Nachgemessen über den ganzen Bestand: **199 MB → 33 MB**, das sind
83 %. Für Lua ändert sich nichts — es schickt kein `Accept: image/webp` und
bekommt weiterhin das Original.

**Zurückholen** — Gelöschtes liegt 30 Tage im Papierkorb, danach räumt der
Dienst selbst auf. Die Datei ist dann nur nicht mehr öffentlich, nicht weg.

**Zählen** — wie oft eine Datei geholt wurde und wann zuletzt. Beantwortet die
Frage, die ein Aufbewahrungsbericht sonst nicht beantworten kann: *braucht das
noch jemand?*

**Verwalten** — Galerie mit Ordnerbaum, Suche, Filter nach Medienart,
Sortierung, Mehrfachauswahl, Verschieben, Löschen.

**Ansehen ohne neuen Tab** — Bild, Video, Ton, PDF und alles Lesbare:
Markdown wird gesetzt, `.lua` und `.json` eingefärbt, CSV als Tabelle,
alles andere mit Zeilennummern. Video und Ton mit gemerkter Lautstärke und
„weiter zum nächsten Stück"; Leertaste hält an, die Pfeile springen fünf
Sekunden, mit Umschalt wechseln sie die Datei.

Markdown wird **ohne Bibliothek** dargestellt, und das ist kein Geiz: der
übliche Weg endet bei `dangerouslySetInnerHTML`, und die Sicherheit hängt dann
an einer Filterliste. Hier entsteht nie eine HTML-Zeichenkette — der Text wird
zu React-Knoten, ein `<script>` in einer hochgeladenen `.md` erscheint als die
acht Zeichen, die es ist.

**Umbenennen** — Datei und Ordner, mit der Warnung, die dazugehört: die Adresse
ändert sich, und der Dialog sagt vorher, wie oft die Datei geholt wurde bzw.
wie viele Dateien im Ordner betroffen sind.

**Nachvollziehen** — ein Verlauf: wer hat wann was abgelegt, ersetzt,
verschoben oder gelöscht. Dazu: nach Abrufen sortieren, und je Token sehen, was
damit abgelegt wurde.

**Umziehen von Fivemanage** — der Dienst spricht deren Sprache
(`/api/image`, `/api/video`, `/api/audio`, `/api/v3/file`, Schlüssel nackt im
`Authorization`-Kopf). Fremde Skripte ziehen um, indem eine Zeile getauscht
wird. Siehe `docs/API.md`.

**Freigeben** — `/s/<schlüssel>` zeigt einen Ordner ohne Anmeldung, etwa einen
Fahrzeugkatalog. Freigegeben wird die **Liste**, nicht der Inhalt: die Dateien
sind ohnehin öffentlich, ein zurückgezogener Link nimmt nur die Übersicht weg.

**Anmelden** — über Discord (eine Rolle auf dem Server genügt) oder mit
Passwort. Das Passwort bleibt als Notausgang.

**Sichern** — täglich, geprüft, in die Nextcloud. Und der Dienst meldet nach
Discord, wenn die Sicherung ausbleibt. Zurückspielen lässt sich das Ganze mit
`tools\zurueckspielen.ps1` — und **üben** lässt es sich auch, in einem
Wegwerf-Volume neben dem laufenden Dienst.

**Beobachten** — `/health` für den Container-Healthcheck (billig, beweist nur,
dass der Prozess antwortet) und `/status` für eine Statusseite: das prüft
Datenbank, Platte, Ausliefern, Bestand, Platz und Sicherung und antwortet mit
**503**, wenn der Dienst sein Geschäft nicht mehr tun kann.

---

## Die eine Regel

**Jeder Knopf gibt Rückmeldung, auch der erfolgreiche.**

Das ist der Fehler, an dem der Fivemanage-Anlauf gescheitert ist: dessen
`http-util.ts` warf jeden Fehlschlag als `new Error(…)`, die Hooks prüften auf
`instanceof ApiError` — und damit verschwand **jeder** Fehler lautlos. `Create
organization` gab weder Erfolg noch Misserfolg zurück; das Ergebnis waren
neunzehn gleichnamige Organisationen.

Deshalb hier:

- In `server/ui/src/api.ts` steht der **einzige** `fetch` und **genau eine**
  Fehlerklasse.
- In `store.ts` steht `run()`: Aktion rein, Erfolgstext rein — es meldet bei
  Erfolg diesen und bei Fehlschlag den Text **des Dienstes**. Wer darüber geht,
  kann keinen stillen Knopf bauen.
- Jeder wartende Knopf ist gesperrt und zeigt einen Kreisel.
- Fehlermeldungen bleiben stehen, bis jemand sie wegklickt.
- Der Dienst hat eine Auffanglinie (`app.onError`): auch ein unerwarteter
  Fehler bekommt einen Satz statt eines nackten `Internal Server Error`.

---

## Betrieb

### Sicherung

`tools/sichern.ps1`, täglich 04:30 als geplante Aufgabe.

Die Datenbank wird **nicht kopiert**, sondern über SQLites eigene
Sicherungsschnittstelle herausgeholt — im WAL-Modus liegt das Zuletzte noch
nicht in `media.db`. Die Bilder kommen aus einem **nur lesend** eingehängten
Volume dazu, alles in ein `tar.gz`.

**Und sie prüft sich selbst:** auspacken, Datenbank öffnen, Medien, Token und
Benutzer zählen, mit dem laufenden Dienst vergleichen. Danach geht sie per
WebDAV in die Nextcloud und wird **von dort zurückgeholt und die Prüfsumme
verglichen** — ein `PUT`, der 201 sagt, hat nichts bewiesen.

Zugangsdaten und Aufbewahrung stehen im Panel unter *Einstellungen*.

### Wiki

```bash
pwsh -File tools\wiki.ps1
```

Trägt `docs/*.md` ins Gitea-Wiki. **Einseitig** — `docs/` ist die Quelle, das
Wiki die Kopie. Wer dort tippt, verliert es beim nächsten Lauf.

### Zurückspielen

```powershell
pwsh -File tools\zurueckspielen.ps1          # ÜBUNG (Standard)
pwsh -File tools\zurueckspielen.ps1 -Echt    # der Ernstfall
```

**Die Übung ist der eigentliche Gewinn.** Sie legt ein Wegwerf-Volume an,
spielt das Archiv hinein, startet einen *zweiten* Dienst davor, lässt ihn drei
zufällige Dateien ausliefern und vergleicht deren SHA-256 mit dem, was in der
Datenbank steht — dann räumt sie alles wieder ab. Der laufende Dienst wird
nicht angefasst.

Das beantwortet die Frage, die `sichern.ps1` **nicht** beantwortet: nicht „ist
das Archiv heil", sondern „wird daraus wieder ein laufender Dienst". Ein
Backup, das man nie zurückgespielt hat, ist kein Backup, sondern eine Datei.

Zuletzt gelaufen und bestanden:

```
4452 Medieneinträge, 316,3 MB, 2 Token, 2 Benutzer, 0 im Papierkorb
4452 Dateien -- gleich viele wie Einträge
ok  items/velum2.png                  113567 B
ok  items/flesh-dolphin-2star.png       3623 B
ok  items/burgermeat.png                4269 B
```

Von Hand ginge es auch:

```bash
tar xzf d4rk_media-JJJJ-MM-TT-HHMM.tar.gz
```

Ergibt `media.db`, `files/` und `papierkorb/`. Alles drei ins Volume legen,
während der Container steht. Vorschaubilder und WebP-Fassungen sind **nicht** im
Archiv — beides ist abgeleitet und wird mit zwei Knöpfen unter
*Speicher → Wartung* neu gerechnet.

> Der Papierkorb war anfangs **nicht** dabei, und das war ein Fehler: seine
> Einträge stehen in `media.db` und waren damit gesichert, die Dateien lagen
> daneben und waren es nicht. Nach einem Zurückspielen hätte der Papierkorb
> Zeilen gezeigt, deren „zurückholen" ins Leere greift. Er kostet fast nichts —
> was darin liegt, ist höchstens 30 Tage alt.

---

## Was hier bewusst fehlt

**Logging.** Genau dafür schleppt Fivemanage ClickHouse mit, und genau da ist
der Wartungsaufwand echt. Der Verlauf im Dashboard beantwortet „wer war das" —
mehr braucht es hier nicht.

**Mandanten, Rollen, Teams.** Ein Dienst, den eine Person betreibt.

**Automatisches Löschen.** Vorbereitet ist der Bericht davor: wie viel ist
älter als 7/30/90/365 Tage, was liegt doppelt. Eine Regel zu bauen, bevor man
weiß, was da liegt, ist der Weg, wie man Daten verliert.

**Spielerportal.** Setzt voraus, dass Spieler hochladen. Der richtige Weg wäre
dann `presigned URLs` — kurzlebige signierte Adressen, mit denen ein Client
hochlädt, ohne je einen Token zu sehen.

---

## Zwei Dinge, die Zeit gekostet haben

**Der Proxy hielt Bilder fest.** NPMs `assets.conf` greift über eine Regex auf
*jede* URL, die auf `.webp`, `.png`, `.js`, `.css` endet, legt die Antwort 30
Minuten weg und ignoriert dabei unsere Kopfzeilen. Ein überschriebenes Bild
blieb damit eine halbe Stunde alt — und `/api/exists/…webp` wurde
zwischengespeichert und danach **auch ohne Token** ausgeliefert.

Behoben mit drei Blöcken in der *Custom Nginx Configuration* des Proxy-Hosts:

```nginx
location ^~ /api/ { proxy_cache off; include conf.d/include/proxy.conf; }
location ^~ /f/   { proxy_cache off; include conf.d/include/proxy.conf; }
location ^~ /t/   { proxy_cache off; include conf.d/include/proxy.conf; }
```

Das `^~` ist der ganze Trick: eine gewöhnliche Präfix-Regel **verliert** gegen
die Regex. In einem Wegwerf-Nginx nachgemessen.

**Node 22 ist festgenagelt.** `better-sqlite3` 11.10.0 liefert fertige
Binärdateien für ABI 115 (Node 20) und 127 (Node 22) — **Node 24 hat ABI 137
und fehlt**. Der Griff zur neuesten Version fällt auf `node-gyp` zurück und
braucht python3, make und g++ im Abbild.

---

## Herkunft

Der Vorgänger war **Fivemanage Lite** mit PostgreSQL, MinIO und ClickHouse. Der
Stack lief; woran er gescheitert ist, steht oben unter *Die eine Regel* und
ausführlich in `ROADMAP.md`. Von dem, was er über eine Dateiablage hinaus kann,
haben wir nichts gebraucht und alles mitgeschleppt.

Seine Compose-Dateien liegen in `legacy/`, als Beleg und wegen der Kommentare —
nichts davon wird noch gestartet.