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

14 KiB
Raw Permalink Blame History

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.


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 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.

Entscheidung 2: Eigene Kombi-Extension KarateMedia statt Drittanbieter-Video-Plugins

Anstatt erneut fremde Video-Plugins zu installieren, haben wir unter 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) für die 87 alten Seiten als auch den MediaHandler (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), 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 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 ü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: 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. Kurzfassung:


6. Aktueller Arbeitsstand & Nächste Schritte (Roadmap)

✅ Bereits erledigt:

  • Rein lesende Bestandsaufnahme des Strato-Produktivsystems (Karate_Wiki_135) und der MySQL-Datenbank (dbs1754262).
  • Auswertung aller 1.028 Wiki-Seiten und Identifikation aller Video-Einbindungen (87× <html5media>, ~71× [[Datei:*.mp4]]).
  • Entwicklung der eigenen Extension KarateMedia (extensions-custom/KarateMedia/) als Ersatz für Html5mediator und EmbedVideo.
  • Bereinigung und Modernisierung der LocalSettings.php (config/LocalSettings.php).
  • Aufbau der Docker-Konfiguration für MediaWiki 1.43 LTS + MariaDB 11.8 (Dockerfile, docker-compose.yml, docker-compose.dev-env.yml).
  • Einrichtung der Gitea-Runner-Workflows (deploy-dev.yml, deploy-prod.yml) inkl. automatischer Datenbank-Initialisierung (scripts/ensure-db-schema.php).
  • 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 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.