Dokumentations-Server

Der Dokumentations-Server stellt diese technische Dokumentation über eine benutzerfreundliche Weboberfläche zur Verfügung.

Technologie-Stack

• Framework: MkDocs - Statischer Site-Generator für technische Dokumentation
• Theme: Material for MkDocs - Modernes, responsives Design
• Container: Docker-Container für einfache Bereitstellung
• Auto-Reload: Automatisches Neuladen bei Änderungen im Entwicklungsmodus

Konfiguration

Container-Konfiguration

docs:
  image: squidfunk/mkdocs-material
  ports:
    - "7999:8000" # Externer Port : Interner Port
  volumes:
    - ../docs:/docs # Mount des docs-Verzeichnisses
  networks:
    - app-network

MkDocs-Konfiguration

Die Dokumentation wird über docs/mkdocs.yml konfiguriert:

• Site-Name: Titel der Dokumentation
• Theme: Material-Design mit Dark/Light-Mode
• Plugins: Suche, Mermaid-Diagramme
• Navigation: Struktur der Dokumentationsseiten

Zugriff

• Lokale Entwicklung: http://localhost:7999
• Produktion: https://docs.ihre-domain.de
• Internes Netzwerk: http://docs:8000 (Docker-Netzwerk)

Dokumentation bearbeiten

Lokale Entwicklung

1. MkDocs installieren:

pip install mkdocs mkdocs-material

1. Server starten:

cd docs
mkdocs serve

1. Änderungen vornehmen:
2. Markdown-Dateien in docs/docs/ bearbeiten
3. Navigation in docs/mkdocs.yml aktualisieren
4. Änderungen werden automatisch neu geladen

Dateistruktur

docs/
├── mkdocs.yml          # Hauptkonfiguration
├── docs/               # Dokumentationsinhalt
│   ├── index.md        # Startseite
│   ├── erste-schritte.md
│   ├── aufgaben.md
│   └── ...
└── javascripts/        # Zusätzliche Skripte
    └── mermaid-init.js

Bereitstellung

Docker-Container

Der Docs-Container läuft kontinuierlich und stellt die Dokumentation bereit:

• Image: squidfunk/mkdocs-material
• Volume-Mount: Lokales docs-Verzeichnis
• Port-Mapping: 7999 (extern) → 8000 (intern)

Nginx-Proxy (Produktion)

In der Produktion wird der Docs-Server über Nginx Proxy Manager weitergeleitet:

• Proxy-Host: docs.ihre-domain.de
• Target: http://docs:8000
• SSL: Automatische Let's Encrypt Zertifikate

Funktionen

Suche

• Volltextsuche durch alle Dokumentationsseiten
• Sofortige Ergebnisse während der Eingabe

Navigation

• Responsive Seitenleiste
• Breadcrumb-Navigation
• Inhaltsverzeichnis mit Anker-Links

Diagramme

• Mermaid-Diagramm-Unterstützung
• Automatische Rendering von Flowcharts und Sequenzdiagrammen

Dark/Light-Mode

• Automatische Erkennung der Systemeinstellungen
• Manuelle Umschaltung möglich

Wartung

Updates

# Container neu bauen
docker compose build docs

# Container neu starten
docker compose restart docs

Backups

Die Dokumentation ist im Git-Repository versioniert. Regelmäßige Commits sichern alle Änderungen.

Monitoring

• Logs: docker compose logs docs
• Status: docker compose ps docs
• Ressourcen: Über Portainer überwachen

Sicherheit

• Zugriffsbeschränkung: Über Nginx Proxy Manager konfigurierbar
• HTTPS: SSL-Verschlüsselung in Produktion
• Authentifizierung: Optional über Proxy-Ebene

Fehlerbehebung

Häufige Probleme

Seite lädt nicht:

• Container-Status prüfen: docker compose ps
• Logs einsehen: docker compose logs docs

Änderungen nicht sichtbar:

• Cache leeren (Strg+F5)
• Container neu starten

Suchfunktion funktioniert nicht:

• JavaScript-Fehler in Browser-Konsole prüfen
• MkDocs-Plugins überprüfen

Entwicklung

Für lokale Entwicklung verwenden Sie mkdocs serve statt des Docker-Containers für schnellere Iterationen.