Files
karatewiki/docs/ARCHITECTURE_AND_STATUS.md
T
2026-10-24 19:48:46 +02:00

168 lines
14 KiB
Markdown
Raw 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] Auswertung des Medienbestands: Von 8,3 GB `images/` auf Strato sind **566 Dateien (4,79 GB)** tatsächlich auf Seiten eingebunden (Rest: 1,8 GB `temp/`, 514 MB `archive/`, 648 MB verwaiste Uploads).
- [x] Entwicklung der eigenen Extension **`KarateMedia`** (`extensions-custom/KarateMedia/`) als Ersatz für `Html5mediator` und `EmbedVideo` (inkl. Zeitlupe `0.5x`/`0.25x` und `Loop`).
- [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] Gemeinsames Medien-Volume (`karatewiki-dev_dev-karatewiki-images`) konfiguriert, damit die 4,79 GB Mediendateien auf dem Raspberry Pi nicht doppelt für Dev und Prod abgelegt werden.
- [x] Erfolgreicher Erst-Import aller 1.028 Seiten, Datenbank-Upgrade von MediaWiki 1.35.1 auf **1.43.11 LTS** und Sync aller **566 verdrahteten Mediendateien (4,79 GB)** auf den Raspberry Pi 5 (`http://192.168.2.49:3093`).
- [x] Erfolgreicher Funktionstest von `<html5media>` (z.B. *Tensho*) und `[[Datei:*.mp4]]` (z.B. *Seienchin*) inklusive Zeitlupen-Steuerung auf `http://192.168.2.49:3093`.
### 🔜 Offene Punkte / Nächste Schritte:
- [ ] **1. Optionale Drittanbieter-Extensions prüfen:** Entscheiden, welche der früheren Zusatz-Extensions (`MsUpload`, `UploadWizard`, `MobileFrontend`, `LinkTitles`, `EditUser`) in MediaWiki 1.43 weiterhin benötigt werden, und diese im `Dockerfile` ergänzen.
- [ ] **2. Gewünschte Vereins-Modifikationen umsetzen:** Neue Features und Anpassungen auf dem `develop`-Branch entwickeln und unter `http://192.168.2.49:3093` testen.
- [ ] **3. Langfristige Betriebsentscheidung (Pi vs. Strato):** Entscheiden, ob das Wiki künftig komplett über die eigene Infrastruktur (deutlich schnellere Performance!) betrieben oder zurück nach Strato ausgerollt werden soll.