MkDocs Betrieb¶

Stand: 2026-05-25

Zweck¶

MkDocs/Material ist die empfohlene primäre Wiki-Plattform für die Lanstyle-Infrastrukturdokumentation.

Die Inhalte liegen als Markdown im Repository und können dadurch direkt von Codex, Claude Code und OpenCode gepflegt werden.

Lokale Struktur¶

mkdocs.yml
docs/
site/

docs/: kanonische Markdown-Quelle
mkdocs.yml: Navigation, Theme, Suche und Markdown-Erweiterungen
site/: generierte statische HTML-Ausgabe

Build¶

python3 -m venv /tmp/lanstyle-mkdocs-build
/tmp/lanstyle-mkdocs-build/bin/pip install -r wiki-requirements.txt
/tmp/lanstyle-mkdocs-build/bin/mkdocs build --strict

Testlauf am 2026-05-25:

Build erfolgreich
Ausgabe: site/
Keine MkDocs-2.0-/Material-Warnung mit gepinnter Toolchain

Gepinnte Toolchain¶

Die Wiki-Build-Abhaengigkeiten sind im Repository gepinnt:

wiki-requirements.txt

Aktiver Pin:

mkdocs==1.6.1
mkdocs-material==9.6.14

Grund: mkdocs-material 9.7.x zeigt einen produktiv stoerenden Warnbanner zu einem zukuenftigen MkDocs-2.0-Bruch an. Fuer das statische Lanstyle-Wiki wird daher eine getestete 9.6er-Version verwendet.

Produktivstand¶

Aktiv seit 2026-05-20:

Proxmox LXC: 253
Hostname: docs-build01
IP: 10.222.40.32/20
Webroot: /var/www/wiki
Webserver: Nginx
Port: 80
Produktive URL: https://wiki.lanstyle.de
NPM Proxy Host ID: 43
NPM Forward: http://10.222.40.32:80
SSL/TLS: aktiv
Force SSL: aktiv
Login: aktiv über NPM Access List Max (id=1)

Backup vor Cutover:

docs-build01: /root/wiki-mkdocs-backups/20260520-080232-before-mkdocs-cutover
NPM DB: /data/database.sqlite.bak-*-wiki-mkdocs-cutover
NPM DB vor Force SSL: /data/database.sqlite.bak-*-wiki-force-ssl

MkDocs Material ist ein statisches Wiki und bringt bewusst keine eigene Benutzerverwaltung mit. Der Login wird deshalb am Reverse Proxy umgesetzt.

Aktive NPM-Konfiguration für wiki.lanstyle.de:

Access List: Max
Access List ID: 1
Proxy Host ID: 43
Proxy Host wiki.lanstyle.de: Access List Max zugewiesen
SSL/TLS: aktiv lassen
Force SSL: aktiv lassen
Block Common Exploits: aktiv lassen

Best Practice für diese Umgebung:

Internes LAN/WLAN darf über NPM erreichbar sein.
Externe IPs nur gezielt freigeben.
Pro Person eigener Benutzer statt gemeinsamem Passwort.
Passwort nicht in Git oder Markdown dokumentieren.
Vor Änderung an NPM /data/database.sqlite sichern.

Backup vor Aktivierung der Access List:

NPM DB: /data/database.sqlite.bak-*-wiki-access-list-max
NPM DB Retry-Backup: /data/database.sqlite.bak-*-wiki-access-list-max-retry

Deploy¶

Der Deploy ist automatisiert:

Repository: https://git.lanstyle.de/vinc32/infrastruktur-wiki
Wiki-LXC: 253
Script: /usr/local/sbin/wiki-auto-deploy
Script-Quelle im Repository: scripts/wiki-auto-deploy
Env-Datei mit Read-Token: /root/.config/lanstyle-wiki-deploy.env
systemd Service: wiki-auto-deploy.service
systemd Timer: wiki-auto-deploy.timer
Intervall: alle 5 Minuten
Build: mkdocs build --strict
Toolchain: Installation aus wiki-requirements.txt, nur bei geaendertem Hash
Webroot: /var/www/wiki
Vor jedem Deploy wird /var/www/wiki unter /root/wiki-mkdocs-backups/ gesichert.

Der Read-Token liegt nur root-lesbar auf dem Wiki-LXC und wird nicht in Git oder Markdown gespeichert.

Frontend¶

Das menschliche Frontend ist MkDocs Material. Es ist kein reiner Datei-Browser, sondern ein statisches Wiki mit:

Navigation
Suche
responsivem Layout
Dark Mode
Code-Copy
sauberer Markdown-Darstellung

Die Pflege bleibt trotzdem agentenfreundlich: Codex, Claude Code und OpenCode bearbeiten direkt docs/*.md.

Warum nicht direkt Docmost löschen?¶

Docmost ist aktuell funktionsfähig und enthält importierte Seiten. Es sollte erst abgeschaltet werden, wenn:

MkDocs-Deploy produktiv erreichbar ist
Gitea-Repo vorhanden ist
Backup/Restore getestet wurde
alle Seiten im statischen Wiki verifiziert wurden

Agenten-Workflow¶

Änderungen immer in docs/*.md.
Keine Secrets in Markdown.
Vor größeren Änderungen Branch nutzen.
Nach Änderungen mkdocs build --strict ausführen.
Danach committen und deployen.