Files
karatewiki/docs/ARCHITECTURE_AND_STATUS.md
2026-10-24 18:14:09 +02:00

168 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Karate-Wiki (Goju-Kai Dojo) – Gesamtdokumentation: Analyse, Entscheidungen, Einstellungen & Arbeitsstand
**Letzte Aktualisierung:** 2026-10-24
**Repository:** `https://gitea.stommer.de/Lars/karatewiki.git` (intern: `http://192.168.2.144:3000/Lars/karatewiki.git`)
**Produktiv-Domain:** `https://www.gojukai-dojo.de`
> **Hinweis für Entwickler & Coding Agents auf anderen Rechnern:**
> Dieses Dokument enthält den vollständigen Kontext aus der initialen Systemanalyse und Architekturplanung. Wenn du eine neue Session auf einem anderen Computer startest, lies zuerst dieses Dokument sowie [`docs/DEPLOYMENT.md`](DEPLOYMENT.md).
---
## 1. Ausgangslage & Zielsetzung
Das Goju-Kai Dojo betreibt seit vielen Jahren ein geschlossenes Vereins-MediaWiki (`https://www.gojukai-dojo.de`) mit umfangreichen Karate-Lernmaterialien, Kata- und Bunkai-Beschreibungen sowie **über 150 direkt im Wiki hochgeladenen Trainingsvideos (`.mp4`)**.
### Bisherige Hauptprobleme im Betrieb:
1. **PHP-Updates legen die Webseite lahm:** Jedes PHP-Upgrade beim Hoster (Strato) führt zu Ausfällen oder Inkompatibilitäten, weil das installierte MediaWiki (1.35.1 von 2020) und alte Drittanbieter-Plugins nicht für PHP 8.3 / 8.4 gebaut wurden.
2. **Wackelige Video-Plugins:** Für die Anzeige von Videos mussten immer wieder Drittanbieter-Extensions (`Html5mediator`, `EmbedVideo`, etc.) ausgetauscht und getestet werden.
3. **Fehlende Test-/Staging-Umgebung & Versionsverwaltung:** Änderungen konnten bisher kaum gefahrlos vorab getestet werden.
### Zielarchitektur:
* **Schlankes Git-Repository in Gitea:** Nur unsere eigene Konfiguration, das Docker-Setup und selbst entwickelte Extensions liegen im Git – **kein** MediaWiki-Core (~20.000 Dateien) und **keine** Mediendateien (`images/`, 8,3 GB).
* **Automatisiertes Staging & Failover auf dem eigenen Server (Raspberry Pi 5):** Über Gitea Actions wird bei jedem Push auf `develop` automatisch eine Testumgebung und bei Merge auf `main` eine Standby-/Produktionsumgebung auf dem Raspberry Pi 5 (`192.168.2.49`) als Docker-Stack gebaut.
* **Wartungsfreie Eigenbau-Extension (`KarateMedia`):** Ersetzt alle fremden Video-Plugins durch 100 % eigenen, schlanken PHP-8-Code ohne externe Abhängigkeiten.
---
## 2. Technische Ist-Analyse des Strato-Produktivsystems (Stand 24.10.2026)
> **WICHTIG:** Das System auf Strato ist das laufende Produktivsystem des Vereins. Alle Zugriffe im Rahmen der Analyse erfolgten strikt **lesend (`read-only`)**.
### 2.1 Server- & Umgebungsdaten (Strato)
* **SSH-Host:** `51539426.ssh.w1.strato.hosting`
* **SSH-Benutzer:** `stu100093250` (SSH-Key: `~/.ssh/strato_fewo`)
* **Pfad zum Produktiv-Wiki:** `~/Karate_Wiki_135`
* **PHP-Version (Web):** PHP 8.3.36
* **PHP-CLI auf Server:** `/opt/RZphp84/bin/php-cli`
* **MediaWiki-Version (Live):** `1.35.1` (ursprünglich installiert mit `1.25.1`, nie im Core gepatcht; im Ordner liegt bereits ein ungenutztes `mediawiki-1.39.3.tar.gz` vom März 2023)
* **Datenbank-Server:** `rdbms.strato.de` (MySQL `5.7.42-log`)
* **Datenbank-Name:** `dbs1754262`
* **Datenbank-Benutzer:** `dbu1061679`
* **Tabellen-Präfix:** `Karate_` (`ENGINE=InnoDB, DEFAULT CHARSET=binary`)
* **Größe des `images/`-Ordners:** **8,3 GB** (enthält `.htaccess` und alle hochgeladenen Videos/Bilder)
* **Vereins-Logo:** `resources/assets/logo_goju-kai_Bleistift.png` (im Repo unter [`assets/logo_goju-kai_Bleistift.png`](../assets/logo_goju-kai_Bleistift.png) gesichert)
### 2.2 Datenbank-Auswertung der Wiki-Inhalte & Video-Syntax
Eine lesende SQL-Auswertung über die aktuellen Seitenrevisionen (`Karate_page` → `Karate_revision` → `Karate_slots` → `Karate_content` → `Karate_text`) ergab folgendes exaktes Bild:
| Metrik | Anzahl Seiten | Details / Beispiele aus dem Wiki |
| :--- | :---: | :--- |
| **Gesamtanzahl Wiki-Seiten** | **1.028** | Aktive Seiten im Wiki |
| **Seiten mit `.mp4`-Videos** | **158** | Alle Videos liegen lokal im `images/`-Ordner |
| davon mit `<html5media>`-Tag | **87** | z.B. `<html5media height="200">File:SeienchinOsaeUke.mp4</html5media>` |
| davon mit `[[Datei:...]]` / `[[File:...]]` | **~71** | z.B. `[[Datei:Seienchin2.mp4\|mini]]`, `[[File:Shisoshin_Funsako_Sensei.mp4\|300x169px]]` |
| davon mit `{{#ev:...}}` (EmbedVideo-Parserfunktion) | **0** | Wird im gesamten Wiki **nicht** verwendet! |
| **Seiten mit `.mp3`-Dateien** | **0** | Keine MP3-Einbindungen |
| **Seiten mit `.ogg`-Dateien** | **1** | 1 Seite mit OGG |
| **Seiten mit `.webm`-Dateien** | **0** | Keine WebM-Einbindungen |
### 2.3 Analyse der bisherigen Video-Plugins (Ursache der Probleme)
In der bisherigen `LocalSettings.php` auf Strato waren **zwei** veraltete Video-Extensions gleichzeitig aktiv:
1. **`Html5mediator` (`extensions/Html5mediator/Html5mediator.php`):**
* Stammt aus ca. 2012 (ca. 100 Zeilen Code) und stellt das `<html5media>`-Tag bereit.
* **Kritischer Fehler 1 (Mixed Content):** Bindet bei jedem Video `<script src="http://api.html5media.info/1.1.5/html5media.min.js"></script>` unverschlüsselt per `http://` von einer fremden, verwaisten Domain ein. Moderne Browser blockieren dies auf `https://www.gojukai-dojo.de`.
* **Kritischer Fehler 2 (Veraltete MediaWiki-APIs):** Nutzt `wfFindFile()` und `Xml::encodeJsVar()`, die in neueren MediaWiki-Versionen entfernt wurden.
* **Kritischer Fehler 3 (Namespace-Bug):** Prüft `substr($data, 0, 5)` auf `datei:`, was wegen 6 Zeichen Länge niemals greift (funktionierte nur mit `File:`).
2. **`EmbedVideo` (v2.9.0 von 2020):**
* War mit `$wgEmbedVideoEnableVideoHandler = true;` aktiviert, um normale Datei-Links (`[[Datei:Kata.mp4|mini]]`) als Video-Player darzustellen.
* Version 2.9.0 ist für MediaWiki 1.35 / PHP 7.4 geschrieben und unter PHP 8.3/8.4 sowie neuen MediaWiki-Versionen nicht mehr lauffähig.
### 2.4 Übersicht aller weiteren Extensions auf dem Strato-Server
#### A. Standard-Extensions (im offiziellen MediaWiki-Image bereits enthalten)
* `Cite`, `Gadgets`, `ImageMap`, `InputBox`, `Interwiki`, `Nuke`, `ParserFunctions`, `PdfHandler`, `SpamBlacklist`, `SyntaxHighlight_GeSHi`, `TitleBlacklist`, `WikiEditor`
* *(Hinweis: `LocalisationUpdate` und `Renameuser` waren in 1.35 noch eigene Extensions; `Renameuser` ist ab MW 1.40 fest im MediaWiki-Core integriert, `LocalisationUpdate` wurde ab MW 1.38 obsolet.)*
#### B. Drittanbieter-Extensions (in `LocalSettings.php` aktiv)
1. **`EmbedVideo`** → **Ersetzt durch unsere eigene Extension `KarateMedia`**
2. **`Html5mediator`** → **Ersetzt durch unsere eigene Extension `KarateMedia`**
3. **`UploadWizard`** (Mehrstufiger Datei-Upload)
4. **`MsUpload`** (Drag & Drop Mehrfach-Upload direkt im Editor)
5. **`MobileFrontend`** (Mobile Ansicht + Skin `MinervaNeue`)
6. **`LinkTitles`** (Automatisches Verlinken von Seitentiteln)
7. **`CookieWarning`** (Cookie-Hinweisbanner)
8. **`EditUser`** (Benutzerprofile durch Bürokraten/Admins bearbeiten)
9. **`EmailPage`** (Seiten per E-Mail versenden)
#### C. Im Ordner vorhandene, aber in `LocalSettings.php` bereits auskommentierte Extensions (Altlasten)
* `ConfirmAccount` (Zeile `### require_once "$IP/extensions/ConfirmAccount/ConfirmAccount.php";` war auskommentiert)
* `Collection` (Zeile `#+ wfLoadExtension( 'Collection' );` war auskommentiert)
* `BlueSpiceInsertFile`, `EditAccount`, `UserExport`, `ReplaceText`, `MultimediaViewer` (nicht aktiv geladen)
---
## 3. Architektur- & Design-Entscheidungen
### Entscheidung 1: Kein MediaWiki-Core im Git-Repository
Da am MediaWiki-Core niemals manuell herumgepatcht wurde, wird der MediaWiki-Core **nicht** in Gitea eingecheckt. Stattdessen kommt der Core im Docker-Betrieb direkt aus dem offiziellen Multi-Arch-Image `mediawiki:1.43` (LTS). Das hält das Git-Repository winzig (< 100 KB) und erlaubt zukünftige MediaWiki- oder PHP-Versionssprünge durch Ändern einer einzigen Versionsnummer im [`Dockerfile`](../Dockerfile).
### Entscheidung 2: Eigene Kombi-Extension `KarateMedia` statt Drittanbieter-Video-Plugins
Anstatt erneut fremde Video-Plugins zu installieren, haben wir unter [`extensions-custom/KarateMedia/`](../extensions-custom/KarateMedia/) eine eigene, exakt auf das Karate-Wiki zugeschnittene MediaWiki-Extension entwickelt:
* **100 % Abwärtskompatibel:** Sie implementiert sowohl den Parser-Hook `<html5media>` ([`KarateMediaHooks.php`](../extensions-custom/KarateMedia/src/KarateMediaHooks.php)) für die 87 alten Seiten als auch den `MediaHandler` ([`KarateVideoHandler.php`](../extensions-custom/KarateMedia/src/KarateVideoHandler.php)) für die ~71 Seiten mit `[[Datei:*.mp4|mini|...]]`. Es muss **keine einzige Wiki-Seite** umgeschrieben werden!
* **Mehrwert fürs Karate-Training:** Unter jedem Video rendert `KarateMedia` automatisch kompakte Steuerbuttons für **`1x` | `0.5x` | `0.25x` | `Loop`** ([`karatemedia.js`](../extensions-custom/KarateMedia/resources/karatemedia.js)), damit Kata- und Bunkai-Techniken direkt in Zeitlupe und Endlosschleife studiert werden können.
### Entscheidung 3: Fehlertolerante `LocalSettings.php` für Docker UND Strato
Die neue [`config/LocalSettings.php`](../config/LocalSettings.php) ist so aufgebaut, dass sie:
1. Zugangsdaten und Keys primär aus Umgebungsvariablen (`getenv('MW_...')` aus `.env`) liest und als Fallback eine lokale `LocalSettings.secrets.php` unterstützt.
2. Alle Extensions vor dem Laden per `file_exists("$IP/extensions/$extName/extension.json")` prüft. Fehlt eine optionale Drittanbieter-Extension, stürzt das Wiki **niemals** mit einem `Fatal Error` ab.
---
## 4. Wichtige Einstellungen & Berechtigungen im Detail
Alle spezifischen Einstellungen des Vereins-Wikis wurden 1:1 in [`config/LocalSettings.php`](../config/LocalSettings.php) übernommen:
* **Geschlossenes Vereins-Wiki:**
* Unangemeldete Besucher (`*`) haben weder Lese- noch Schreib- noch Registrierungsrechte (`createaccount = false`, `edit = false`, `read = false`).
* **Öffentliche Ausnahmen (`$wgWhitelistRead`):**
* `Spezial:Userlogin` / `Spezial:Anmelden`
* `Karate:Datenschutz`
* `Karate:Impressum`
* `Spezial:Benutzerkonto_beantragen`
* `Karate:Nutzungsbedingungen`
* **Eigene Benutzergruppe `Trustworthy`:**
* Erbt alle Rechte von `user` und erhält zusätzlich: `delete`, `protect`, `patrol`, `purge`, `createaccount`, `block`.
* **iOS / Safari Video-Streaming-Fix (`Phabricator T235554`):**
* `$wgDisableOutputCompression = true;` ist zwingend aktiv, damit iPhones und iPads MP4-Videos über `HTTP Byte-Range Requests` abspielen können.
* **Upload-Limits für Videos:**
* In [`config/php-uploads.ini`](../config/php-uploads.ini): `upload_max_filesize = 500M`, `post_max_size = 500M`, `max_execution_time = 600`.
* Erlaubte Dateiendungen (`$wgFileExtensions`): u.a. `png`, `gif`, `jpg`, `jpeg`, `webp`, `svg`, `pdf`, `doc/docx`, `xls/xlsx`, `ppt/pptx`, `odt/ods/odp`, `ogg`, `mp3`, `mp4`, `webm`, `mov`.
---
## 5. CI/CD & Server-Umgebung (Raspberry Pi 5 & Gitea Runner)
Details zum Deployment stehen in [`docs/DEPLOYMENT.md`](DEPLOYMENT.md). Kurzfassung:
* **Docker-Host:** Raspberry Pi 5 (`192.168.2.49`, ARM64)
* **Development (`develop`-Branch):**
* Pfad auf Pi: `/home/lars/docker/karatewiki-dev`
* Compose-Datei: [`docker-compose.dev-env.yml`](../docker-compose.dev-env.yml)
* Port: **`3093`** (`http://192.168.2.49:3093`)
* Workflow: [`.gitea/workflows/deploy-dev.yml`](../.gitea/workflows/deploy-dev.yml)
* **Production / Pi-Standby (`main`-Branch):**
* Pfad auf Pi: `/home/lars/docker/karatewiki`
* Compose-Datei: [`docker-compose.yml`](../docker-compose.yml)
* Port: **`3008`** (`http://192.168.2.49:3008`)
* Workflow: [`.gitea/workflows/deploy-prod.yml`](../.gitea/workflows/deploy-prod.yml)
---
## 6. Aktueller Arbeitsstand & Nächste Schritte (Roadmap)
### ✅ Bereits erledigt:
- [x] Rein lesende Bestandsaufnahme des Strato-Produktivsystems (`Karate_Wiki_135`) und der MySQL-Datenbank (`dbs1754262`).
- [x] Auswertung aller 1.028 Wiki-Seiten und Identifikation aller Video-Einbindungen (87× `<html5media>`, ~71× `[[Datei:*.mp4]]`).
- [x] Entwicklung der eigenen Extension **`KarateMedia`** (`extensions-custom/KarateMedia/`) als Ersatz für `Html5mediator` und `EmbedVideo`.
- [x] Bereinigung und Modernisierung der `LocalSettings.php` (`config/LocalSettings.php`).
- [x] Aufbau der Docker-Konfiguration für MediaWiki 1.43 LTS + MariaDB 11.8 (`Dockerfile`, `docker-compose.yml`, `docker-compose.dev-env.yml`).
- [x] Einrichtung der Gitea-Runner-Workflows (`deploy-dev.yml`, `deploy-prod.yml`) inkl. automatischer Datenbank-Initialisierung (`scripts/ensure-db-schema.php`).
- [x] Push von `main` und `develop` nach `https://gitea.stommer.de/Lars/karatewiki.git`.
### 🔜 Offene Punkte / Nächste Schritte:
- [ ] **1. Gitea-Runner-Lauf prüfen:** Kontrollieren, ob `deploy-dev.yml` auf dem Raspberry Pi 5 (`http://192.168.2.49:3093`) erfolgreich durchläuft (ggf. Runner-Konfiguration mit aktuellem Repo abgleichen).
- [ ] **2. Live-Datenbank & Beispiel-Videos in `karatewiki-dev` einspielen:** Mit [`scripts/sync-from-strato.sh`](../scripts/sync-from-strato.sh) einen aktuellen DB-Abzug und ausgewählte (oder alle) Videos von Strato nach `/home/lars/docker/karatewiki-dev` holen und das Upgrade-Skript (`php maintenance/run.php update --quick`) gegen die echten Vereinsdaten testen.
- [ ] **3. Drittanbieter-Extensions im `Dockerfile` ergänzen (nach Bedarf):** Prüfen, welche der optionalen Extensions (`MsUpload`, `UploadWizard`, `MobileFrontend`, `LinkTitles`, `EditUser`) in MediaWiki 1.43 weiterhin gewünscht sind, und diese im `Dockerfile` automatisch in das Image einbauen.
- [ ] **4. Gewünschte Vereins-Modifikationen umsetzen:** Neue Features und Anpassungen auf dem `develop`-Branch entwickeln und unter `http://192.168.2.49:3093` testen.
- [ ] **5. Strato-Deployment / Cutover planen:** Entscheiden, ob Strato beim Merge auf `main` ebenfalls automatisiert aktualisiert wird oder ob das Wiki langfristig über den Reverse-Proxy komplett auf der eigenen Infrastruktur läuft.