Umfassende Projektdokumentation (Analyse, Entscheidungen, Einstellungen & Status) fuer Rechnerwechsel
Deploy Development / deploy (push) Failing after 0s

This commit is contained in:
Lars committed 2026-10-24 18:14:09 +02:00
1 parent 5f212e7338
commit f4e6417be7
8 files changed
+203 -33

No files matched your search

+167
View File
@@ -0,0 +1,167 @@
# 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.
+1
View File
@@ -49,3 +49,4 @@ docker compose -f docker-compose.dev-env.yml exec -T db \
docker compose -f docker-compose.dev-env.yml exec -T mediawiki \
php maintenance/run.php update --quick
```