Bearbeiten von „Zbrain aufsetzen probleme“

<div style="margin-bottom: 15px; padding: 8px 12px; background-color: #f8f9fa; border: 1px solid #a2a9b1; border-radius: 4px; display: inline-block;">
    [[Meine Server & Infrastruktur | ⬅️ Zurück zur Server-Übersicht]]
</div>

{| style="float:right; width:280px; margin-left:15px; margin-bottom:10px; border:1px solid #a2a9b1; background:#f8f9fa; font-size:0.9em;"
|-
! style="background:#cedff2; padding:8px; text-align:center; font-size:1.1em;" colspan="2" | 🔧 Z-Brain: Aufbau-Probleme
|-
| colspan="2" style="text-align:center; padding:10px; background:#ffffff;" |
[[Datei:Symbol_support_vote.svg|80px]]<br>
<small>''4 gelöste Probleme''</small>
|-
! style="background:#e8e8e8; padding:5px; text-align:left;" colspan="2" | Übersicht
|-
| style="padding:5px; width:55%;" | [[#docker-volumes|Docker-Volumes neu erzeugt]]
| style="padding:5px;" | Docker
|-
| style="padding:5px;" | [[#mediawiki-logo|Logo nicht sichtbar]]
| style="padding:5px;" | MediaWiki
|-
| style="padding:5px;" | [[#npm-502|502 Bad Gateway]]
| style="padding:5px;" | NPM
|-
| style="padding:5px;" | [[#localsettings|LocalSettings.php verloren]]
| style="padding:5px;" | MediaWiki
|-
| colspan="2" style="padding:5px; text-align:right; font-size:0.85em; color:#54595d;" | Stand: Juni 2026
|}

Hier dokumentiere ich, welche Probleme beim Aufsetzen von '''Z-Brain''' (diesem Wiki) aufgetaucht sind und wie ich sie gelöst habe — gut zum Nachschlagen, falls der gleiche Mist später wieder auftaucht.

<span id="docker-volumes"></span>
'''Docker Compose erzeugt neue, leere Volumes statt alte wiederzuverwenden'''
<br><small>Komponente: '''Docker'''</small>

Beim Verschieben/Umbenennen eines Compose-Projekt-Ordners (z.B. <code>mediawiki-test</code> → <code>zbrain</code>) leitet Docker Compose den Volume-Namen standardmäßig vom Ordnernamen ab. Folge: beim nächsten <code>docker compose up</code> legt Docker '''neue, leere''' Volumes mit dem neuen Präfix an, statt die alten (mit den echten Daten) weiterzuverwenden — die App startet dann scheinbar normal, aber komplett leer bzw. zeigt den Erstinstallations-Assistenten erneut.

'''Lösung:''' In der <code>docker-compose.yml</code> die betroffenen Volumes explizit auf ihren festen, alten Namen fixieren, damit Docker sie wiederfindet statt neue anzulegen:
<pre>
volumes:
  mediawiki-db-data:
    name: mediawiki-test_mediawiki-db-data
    external: true
</pre>
Vorher prüfen mit <code>docker volume ls | grep &lt;projektname&gt;</code> — wenn zwei Sätze ähnlich benannter Volumes auftauchen (altes + neues Präfix), ist das die Bestätigung für dieses Problem.

----

<span id="mediawiki-logo"></span>
'''MediaWiki Vector-2022 zeigt das Logo nicht, ohne icon-Key in $wgLogos'''
<br><small>Komponente: '''MediaWiki'''</small>

<code>$wgLogos</code> mit nur <code>1x</code>/<code>2x</code>-Einträgen reicht bei der Skin '''Vector-2022''' nicht aus — ohne zusätzlichen <code>icon</code>-Schlüssel fällt die Skin auf den reinen Text-Wortmark zurück, das Logo-Bild bleibt unsichtbar (auch wenn die Bilddatei selbst korrekt liegt und per <code>curl</code> erreichbar ist).

'''Lösung:''' Den <code>icon</code>-Eintrag ergänzen:
<pre>
$wgLogos = [
    '1x' => "$wgResourceBasePath/resources/assets/zbrain/logo.png",
    '2x' => "$wgResourceBasePath/resources/assets/zbrain/logo-2x.png",
    'icon' => "$wgResourceBasePath/resources/assets/zbrain/logo.png",
];
</pre>
Änderung greift sofort nach <code>docker cp</code> der angepassten <code>LocalSettings.php</code> in den Container, kein Neustart nötig.

----

<span id="npm-502"></span>
'''NPM 502 Bad Gateway durch fehlende Docker-Netzwerk-Verbindung'''
<br><small>Komponente: '''Nginx Proxy Manager'''</small>

Läuft Nginx Proxy Manager selbst containerisiert (z.B. als <code>npm-app-1</code>), bedeutet <code>localhost</code> im Forward-Host-Feld '''den NPM-Container selbst''', nicht den Host-Server. Trägt man dort die Host-IP oder <code>localhost</code> ein, während das Ziel in einem anderen, isolierten Docker-Netzwerk läuft, kommt openresty mit <code>502 Bad Gateway</code> zurück.

'''Diagnose:''' Netzwerke beider Container vergleichen:
<pre>
docker inspect npm-app-1 --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}'
docker inspect &lt;zielcontainer&gt; --format '{{range $k, $v := .NetworkSettings.Networks}}{{$k}}{{end}}'
</pre>

'''Lösung:''' Zielcontainer zusätzlich ins NPM-Netzwerk hängen (rein additiv, bestehende Netzwerk-Zugehörigkeit bleibt erhalten):
<pre>
docker network connect npm_default &lt;zielcontainer&gt;
</pre>
In NPM dann als Forward-Host den '''Container-Namen''' eintragen (z.B. <code>mediawiki</code>) statt einer IP, und als Port den ''internen'' Container-Port (z.B. <code>80</code>), nicht den extern weitergeleiteten Host-Port (z.B. <code>8081</code>).

''Hinweis:'' Diese Netzwerk-Verbindung ist nicht in der <code>docker-compose.yml</code> hinterlegt — bei einem künftigen <code>docker compose down</code>/<code>up</code> des Zielcontainers muss der <code>connect</code>-Befehl ggf. erneut ausgeführt werden, sofern er nicht dauerhaft in die Compose-Datei aufgenommen wird.

----

<span id="localsettings"></span>
'''MediaWiki-Container verliert LocalSettings.php bei falschem Volume-Mount'''
<br><small>Komponente: '''MediaWiki'''</small>

Im offiziellen <code>mediawiki</code>-Docker-Image landet die vom Setup-Assistenten erzeugte <code>LocalSettings.php</code> direkt unter <code>/var/www/html/LocalSettings.php</code> — '''nicht''' unter <code>/var/www/html/config/</code>. Wird nur Letzteres als Volume gemountet, geht die Konfigurationsdatei beim nächsten Container-Neuaufbau verloren (während Datenbank- und Bilder-Volumes unberührt bleiben, da diese korrekt gemountet sind).

'''Lösung für zukünftige Setups:''' Entweder direkt <code>/var/www/html/LocalSettings.php</code> als einzelne Datei mounten, oder nach jedem Setup-Lauf eine Sicherungskopie außerhalb des Containers aufbewahren:
<pre>
docker cp mediawiki:/var/www/html/LocalSettings.php ~/mediawiki-LocalSettings-backup.php
</pre>

'''Falls schon verloren:''' Nicht in Panik geraten — die Wiki-'''Inhalte''' liegen in der Datenbank, nicht in dieser Datei. Datenbank-Zugangsdaten (Host, Name, Nutzer, Passwort) lassen sich aus der <code>docker-compose.yml</code> rekonstruieren und die Datei von Hand neu schreiben, ohne den Setup-Assistenten erneut durchlaufen zu müssen.

----

<div style="clear:both;"></div>
<div style="font-size:0.9em; color:#54595d; text-align:right; margin-top:20px;">Stand: Juni 2026</div>