MkDocs – Migrations- und Setup-Skripte

Diese Seite fasst die während der Umstellung von DokuWiki auf MkDocs verwendeten Skripte zusammen. Sie dient als Betriebs- und Wiederherstellungsanleitung für den Webserver-LXC 150.

Überblick

Dieser Bereich dokumentiert die Migration von DokuWiki nach MkDocs, inklusive Backups, Build-Prozess, Wartung und Wiederherstellung. Die Seite dient als Referenz, wenn Inhalte, Konfigurationen oder Veröffentlichungen neu aufgebaut werden müssen.

Schnellablauf

Backup sichern
Export / Migration nachvollziehen
MkDocs builden und prüfen
lokale Tests und Links kontrollieren
Release / Veröffentlichung validieren

1. Aktuelle Umgebung

Komponente	Wert
Proxmox LXC	`150`
Hostname	`web`
LAN-IP	`192.168.178.150`
CPU	`2 Kerne`
RAM	`2 GB`
Swap laut Proxmox	`1 GB`
MkDocs-Projekt	`/opt/mkdocs/site`
Markdown-Quellen	`/opt/mkdocs/site/docs`
erzeugte Website	`/opt/mkdocs/site/site`
MkDocs-Webserver	`127.0.0.1:8080`
code-server	`127.0.0.1:8443`
Leseseite	`https://docs.epping-haus.de`
Editor	`https://edit.docs.epping-haus.de`

2. Skripte im Überblick

Skript	Aufgabe	Einsatz
`export-dokuwiki-content.sh`	DokuWiki-Seiten, Medien und Metadaten exportieren	Migration
`backup-mkdocs.sh`	aktuellen MkDocs-Stand sichern	vor Austausch
`exchange-mkdocs-content.sh`	migrierte Markdown-Dateien übernehmen	Migration
`build-mkdocs-migration.sh`	MkDocs nach dem Austausch bauen	Migration
`fix-mkdocs-root.sh`	Root-Startseite `/index.html` aus `start.md` herstellen	Migration
`test-mkdocs-local.sh`	lokalen Port 8080 testen	Diagnose
`test-mkdocs-migration.sh`	öffentliche Seiten und Medien prüfen	Abschluss
`setup-mkdocs-autobuild.sh`	Auto-Build mit `inotifywait` einrichten	laufender Betrieb
`fix-mkdocs-permissions.sh`	Besitzer und Schreibrechte korrigieren	Fehlerbehebung
`fix-mkdocs-build-user.sh`	Build als `berthold` ausführen	Fehlerbehebung
`setup-edit-docs.sh`	Caddy-Route für code-server	Editor
`check-edit-docs.sh`	DNS/HTTP/HTTPS/Caddy prüfen	Diagnose
`check-codeserver.sh`	code-server und OOM prüfen	Diagnose
`secure-mkdocs.sh`	Leseseite mit Caddy Basic Auth schützen	Zugriffsschutz

3. Empfohlener Migrationsablauf

DokuWiki
   │
   ├─ 1. Export
   ▼
Backup des bestehenden MkDocs-Projekts
   │
   ├─ 2. Auto-Build stoppen
   ▼
Markdown-Inhalte austauschen
   │
   ├─ 3. Build als berthold
   ▼
Root-Startseite prüfen
   │
   ├─ 4. lokale Tests
   ▼
Öffentliche Website testen
   │
   ├─ 5. Links korrigieren
   ▼
Auto-Build wieder aktivieren

4. DokuWiki exportieren

Das Export-Skript liest den vorhandenen DokuWiki-Bestand unter:

/var/www/dokuwiki/data/pages/
/var/www/dokuwiki/data/media/
/var/www/dokuwiki/data/meta/

Ausführung:

sudo /tmp/export-dokuwiki-content.sh

Beim erfolgreichen Export am 17.09.2026 wurden gefunden:

16 Seiten
3 Media-Dateien
205 Meta-Dateien

Das Exportarchiv wird unter /tmp/ erzeugt.

5. MkDocs sichern

Vor jedem Austausch:

sudo /tmp/backup-mkdocs.sh

Gesichert werden das MkDocs-Projekt sowie die zugehörigen Service- und Caddy-Dateien.

Zusätzliche Migrations-Backups werden unter einem Verzeichnis wie diesem angelegt:

/opt/mkdocs/site/backup-before-dokuwiki-YYYYMMDD-HHMMSS

Das Wiederherstellungs-Backup vom 17.09.2026 wurde unter /root/mkdocs-backup-20260917-190801 angelegt.

6. Auto-Build stoppen

Vor dem Austausch:

sudo systemctl stop mkdocs-autobuild.service

Kontrolle:

systemctl status mkdocs-autobuild.service --no-pager

Erwartet:

Active: inactive (dead)

7. Inhalte austauschen

Nach erfolgreichem Backup:

sudo /tmp/exchange-mkdocs-content.sh

Das Skript übernimmt den neuen docs/-Bestand und erstellt ein zusätzliches Backup.

Wichtig: Nach diesem Schritt ist der neue Quellbestand vorhanden, aber erst ein nachfolgender Build verändert die ausgelieferte Website.

8. MkDocs bauen

Der Build darf nicht als root laufen, weil sonst Dateien im erzeugten site/ als root:root angelegt werden können.

Verwendet wird:

sudo /tmp/build-mkdocs-migration.sh

Der eigentliche MkDocs-Aufruf muss als berthold erfolgen:

sudo -u berthold /opt/mkdocs/venv/bin/mkdocs build --clean -f /opt/mkdocs/site/mkdocs.yml

9. Root-Startseite reparieren

Bei der Migration lag die Hauptseite zunächst nur als:

/start/index.html

vor. Dadurch zeigte / eine Python-Verzeichnisliste.

Korrektur:

sudo /tmp/fix-mkdocs-root.sh

Das Skript übernimmt docs/start.md als docs/index.md und erzeugt dadurch:

/opt/mkdocs/site/site/index.html

Damit öffnet

https://docs.epping-haus.de/

direkt die MkDocs-Material-Startseite.

10. Lokalen Webserver testen

sudo /tmp/test-mkdocs-local.sh

Wichtige Prüfungen:

curl -I http://127.0.0.1:8080/
curl -I http://127.0.0.1:8080/start/

Erwartet wird jeweils HTTP 200.

11. Öffentliche Migration testen

sudo /tmp/test-mkdocs-migration.sh

Beispielpfade:

https://docs.epping-haus.de/
https://docs.epping-haus.de/start/
https://docs.epping-haus.de/allgemein/start/
https://docs.epping-haus.de/hardware/proxmox/
https://docs.epping-haus.de/internet/caddy/
https://docs.epping-haus.de/iot/start/
https://docs.epping-haus.de/wiki/dokuwiki/

Bei aktiviertem Basic Auth ist bei einem Test ohne Zugangsdaten HTTP 401 korrekt. Nach Anmeldung müssen die Seiten HTTP 200 liefern.

12. Berechtigungsfehler beheben

Wenn MkDocs meldet:

PermissionError: [Errno 13] Permission denied

zunächst prüfen:

ls -l /opt/mkdocs/site/site/assets/images/favicon.png

Korrektur:

sudo /tmp/fix-mkdocs-permissions.sh

Danach den Build ausdrücklich als berthold durchführen:

sudo /tmp/fix-mkdocs-build-user.sh

Zielzustand:

berthold berthold

für die erzeugten Dateien.

13. Auto-Build aktivieren

Nach Abschluss der Migration:

sudo /tmp/setup-mkdocs-autobuild.sh

Der Dienst überwacht:

/opt/mkdocs/site/docs

und startet nach einer Änderung automatisch einen MkDocs-Build.

Prüfen:

systemctl status mkdocs-autobuild.service --no-pager

Log:

journalctl -u mkdocs-autobuild.service -n 30 --no-pager

Erfolgreich ist beispielsweise:

MkDocs Build erfolgreich.

14. code-server und Editor

Der Editor läuft separat unter:

https://edit.docs.epping-haus.de

Backend:

127.0.0.1:8443

Caddy-Konfiguration:

sudo /tmp/setup-edit-docs.sh

Diagnose:

sudo /tmp/check-edit-docs.sh

code-server-Diagnose:

sudo /tmp/check-codeserver.sh

15. Speicherproblem beim code-server

Der ursprüngliche LXC hatte nur 512 MB RAM. code-server wurde deshalb mehrfach vom OOM-Killer beendet.

Aktuelle Proxmox-Konfiguration:

2 CPU-Kerne
2 GB RAM
1 GB Swap (Proxmox-Konfiguration)

Änderung auf dem Proxmox-Host:

pct set 150 -cores 2 -memory 2048 -swap 1024
pct reboot 150

Nur die Leseseite wird über Caddy geschützt:

https://docs.epping-haus.de
→ Caddy Basic Auth
→ MkDocs

Der Editor bleibt separat:

https://edit.docs.epping-haus.de
→ code-server Login

Einrichtung:

caddy hash-password

Danach kann das Caddy-Setup mit:

sudo /tmp/secure-mkdocs.sh

ausgeführt werden.

Das eigentliche Passwort gehört nicht in diese Dokumentation.

17. Typische Fehler und Lösungen

Python-Verzeichnisliste auf `/`

Ursache: keine Root-index.html vorhanden.

Lösung:

sudo /tmp/fix-mkdocs-root.sh

`HTTP 401` beim Test

Bei aktiviertem Login ist das für einen nicht authentifizierten Zugriff korrekt. Nach Anmeldung muss die Seite HTTP 200 liefern.

`PermissionError` bei `favicon.png`

Ursache: erzeugte Dateien gehören root.

Lösung: Besitzer korrigieren und den Build als berthold ausführen.

`Cannot reconnect` in code-server

Ursache in der Einrichtung: code-server wurde wegen des zu kleinen LXC-Speicherlimits vom OOM-Killer beendet.

Lösung: mindestens die aktuelle Konfiguration des LXC mit 2 GB RAM verwenden.

DokuWiki-Links zeigen auf alte Pfade

Die Migration kann Links wie diese melden:

internet/start.md
hardware/start.md
anleitungen/netzwerk/smgw.md
wiki/syntax.md

Ein erfolgreicher Build bedeutet nicht automatisch, dass alle internen Links korrekt migriert wurden.

18. Rollback

Vor Änderungen das vorhandene Backup prüfen:

sudo ls -lh /root/mkdocs-backup-20260917-190801

Zusätzlich existiert im Projekt ein Migrations-Backup unter:

/opt/mkdocs/site/backup-before-dokuwiki-YYYYMMDD-HHMMSS

Bei einem Rollback müssen docs/, site/ und gegebenenfalls mkdocs.yml aus dem entsprechenden Backup wiederhergestellt werden.

19. Kurzreferenz

# Backup
sudo /tmp/backup-mkdocs.sh

# Auto-Build stoppen
sudo systemctl stop mkdocs-autobuild.service

# Inhalte austauschen
sudo /tmp/exchange-mkdocs-content.sh

# Build
sudo /tmp/build-mkdocs-migration.sh

# Root reparieren
sudo /tmp/fix-mkdocs-root.sh

# Lokal testen
sudo /tmp/test-mkdocs-local.sh

# Öffentlich testen
sudo /tmp/test-mkdocs-migration.sh

# Auto-Build aktivieren
sudo /tmp/setup-mkdocs-autobuild.sh