168 lines
14 KiB
Markdown
168 lines
14 KiB
Markdown
# 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.
|