Projektdokumentation – MayIT Docker KI & Monitoring Platform

Projektdokumentation

KI • Monitoring • Operations • Autor: MayIT

Ziel: Vollständige Dokumentation der MayIT Docker KI & Monitoring Platform

Navigation

Scope & Zielbild
System- und Monitoring-Architektur
Dashboards & Zugriffe
Betriebs- und Monitoring-Logik
Dashboard-Kacheln
Health-Scores & Bewertungslogik
Security Monitoring
Alerts & Eskalation
Betrieb & Aufgabenmodell
Troubleshooting
Backup & Recovery
Anhang

MayIT Docker KI & Monitoring Platform – Projektdokumentation

Diese Projektdokumentation beschreibt den Aufbau einer lokal betriebenen Docker-basierten KI- und Monitoring-Plattform auf einem Mac Mini M4. Dokumentiert werden Architektur, Dashboard-Konzept, Container-Management, Monitoring-Integration, externer Zugriff via Tailscale, operative Betriebslogik, Troubleshooting, Backup und Wiederherstellung.

Autor: MayIT Homarr + OpenWebUI Portainer Management Netdata extern Tailscale / MagicDNS

Scope & Zielbild

Zielbild: Eine kompakte, professionelle und von überall sicher erreichbare Betriebsplattform, die KI-Nutzung, Container-Management und Monitoring in einer zentralen Bedienoberfläche zusammenführt.

Usability: Ein zentrales Dashboard für alle wichtigen Dienste.
Stabilität: Saubere Stack-Struktur ohne Altlasten oder Testreste.
Observability: Statussichtbarkeit direkt in Homarr plus externes Monitoring.
Security: Kein unnötiger Public Exposure, Remote-Zugriff über Tailscale.

Projektziel: Das System soll nicht nur technisch funktionieren, sondern im Betrieb schnell diagnostizierbar, erweiterbar und sauber dokumentierbar sein.

Leitprinzip: Produktive Umstellungen erfolgen nur nach Backup, Paralleltest und Validierung über LAN und Tailscale. Erst danach werden Altzustände entfernt.

System- und Monitoring-Architektur

Architekturprinzip: Docker UI + KI Frontend + Management + externes Monitoring

Layer	Komponente	Funktion
Hardware	Mac Mini M4	Hostsystem für Docker und Ollama
Dashboard	Homarr	Zentrale Start- und Kontrolloberfläche
KI Frontend	OpenWebUI	Browserbasierter Zugriff auf lokale KI
Management	Portainer	Stacks, Container, Volumes und Betriebszustände
Monitoring	Netdata (extern)	Ergänzende System- und Infrastrukturüberwachung
VPN	Tailscale	Geschützter Zugriff lokal und remote per MagicDNS
LLM Backend	Ollama nativ	Lokale Modellverarbeitung außerhalb von Docker

Kernidee: Die eigentliche KI-Laufzeit verbleibt bewusst nativ auf dem Mac, während die Bedien-, Management- und Monitoring-Schicht in klar voneinander getrennten Containern betrieben wird. Dieses Modell vereinfacht Wartung, Ressourcensteuerung und spätere Erweiterungen erheblich.

Benutzer
  │
  ├── Homarr         → Dashboard & Reachability
  ├── OpenWebUI      → KI Interaktion
  ├── Portainer      → Docker Management
  └── Netdata        → externes Monitoring

Mac Mini M4
  ├── Docker / frontend-stack
  │    ├── homarr
  │    └── openwebui
  ├── portainer (separat)
  └── Ollama (nativ)

Zugriffspfade
  ├── LAN      → 192.168.x.x oder Hostname
  └── Tailscale → 100.x.x.x oder MagicDNS-Hostname

Dashboards & Zugriffe

Homarr Dashboard

http://m4macmachine:7575

Zweck: Zentrale Bedienoberfläche mit Kacheln, Health-Indikatoren und Schnellzugriff.

OpenWebUI

http://m4macmachine:3000

Zweck: Browserbasierte Nutzung der lokal betriebenen KI über das Ollama-Backend.

Portainer

https://m4macmachine:9443

Zweck: Sichere Container- und Stack-Verwaltung. Zugriff ausschließlich per HTTPS.

Netdata (extern)

Externer Monitoring-Server / separate Netdata-Instanz

Zweck: Ergänzende Überwachung außerhalb des Mac-Hosts und jenseits der Homarr-Reachability-Checks.

Zugriffsschutz: Der produktive Remote-Zugriff erfolgt nicht öffentlich, sondern geschützt über Tailscale. Dadurch bleiben Management- und KI-Oberflächen ohne unnötige Internet-Exposition.

Betriebs- und Monitoring-Logik

Produktive Containerstruktur

Finaler Stack: frontend-stack
Service 1: homarr
Service 2: openwebui
Separat: portainer

Status-Pfade

curl -I http://m4macmachine:7575
curl -I http://m4macmachine:3000
curl -k -I https://m4macmachine:9443
tailscale status
tailscale ip -4

Wert / Ebene	Bedeutung	Quelle
Homarr Status	Erreichbarkeit der produktiven Services	Homarr Healthcheck / Kachelstatus
OpenWebUI Health	Service erreichbar, Container healthy	Docker + Homarr
Portainer Reachability	Management-Layer erreichbar	HTTPS-Check
Tailscale Reachability	Remote-Zugriff über 100.x.x.x oder Hostname	Tailscale
Hostname Resolution	MagicDNS-Auflösung auf Tailscale-IP	Tailscale / Hostname-Zugriff
Netdata	Externe Infrastruktur- und Systemmetriken	Separater Monitoring-Server
Backup-Artefakte	Tar-Archive der produktiven Volumes	BusyBox tar / lokaler Backup-Pfad

Dashboard-Kacheln

🧠 KI

Kachel	Inhalt
OpenWebUI	Primärer Einstiegspunkt für KI-Nutzung
Statuspunkt	Direkte Reachability-Kontrolle unten rechts
Öffnungsverhalten	Neuer Tab / Hostname-basierter Zugriff

🖥️ Infrastruktur

Kachel	Inhalt
Portainer	Container-/Stack-Management
Homarr	Dashboard / Control Center
Statuspunkte	Sofortige optische Erreichbarkeitsanzeige

Monitoring-Erweiterung

Netdata als separate Monitoring-Kachel integrierbar
Externer Monitoring-Server kann über Hostname/Tailscale eingebunden werden
Dashboard ist damit auf spätere NOC-/Monitoring-Erweiterung vorbereitet

UX-Prinzip

Wichtigste App oben: OpenWebUI
Management darunter: Portainer und Homarr
Kurze Klickwege, Status mit einem Blick erfassbar

Health-Scores & Bewertungslogik

Homarr Reachability Score

Praktisch umgesetzter, visueller Basis-Healthcheck über Kachelstatusfarben.

Status	Bedeutung
Grün	Dienst erreichbar und funktional
Rot	Dienst nicht erreichbar / gestoppt / gestört
Blau (Pause/Test)	Temporärer Betriebszustand im manuellen Test

Betriebslogik

Das Projekt nutzt bewusst eine schlanke, aber belastbare Bewertungslogik.

Einfluss	Bewertung
Service erreichbar	betriebsbereit
Service nicht erreichbar	Incident / Eingriffsbedarf
Tailscale Zugriff erfolgreich	Remote-Betrieb funktionsfähig
Backup erfolgreich	Rollback-Punkt gesichert

Bewertung: Dieses Projekt nutzt bewusst keine künstlich überladene Health-Metrik, sondern verbindet Homarr-Status, Container-Health, Tailscale-Tests und externe Netdata-Metriken zu einer praxisnahen operativen Bewertungslogik.

Security Monitoring

Tailscale Remote Security

Remote-Zugriff erfolgt ausschließlich über Tailscale
MagicDNS-Hostname m4macmachine ersetzt schwer merkbare IPs
Auch Hostname-Zugriffe laufen im Fremdnetz über Tailscale
Kein unnötiges Public Exposure der Management-Oberflächen

Portainer Zugriff

Port 9443 nur per HTTPS nutzen
Fehlerbild HTTP request to HTTPS server wurde identifiziert und sauber eingeordnet
Hostname- und Tailscale-Zugriffe wurden erfolgreich validiert

Container-Hygiene

Alte Test- und Prod-Reste wurden vollständig bereinigt
Nur produktive Container und Volumes verbleiben im Endzustand
Parallele Migration wurde kontrolliert über Alternativports abgewickelt

Monitoring-Security

Netdata verbleibt absichtlich auf separatem Server
Dadurch entsteht zusätzliche Sicht auf das Gesamtsystem
Monitoring und KI-Host bleiben logisch getrennt

Alerts & Eskalation

Aktive Alert-Logik

Alert	Trigger	Level
OpenWebUI down	Kachelstatus rot / HTTP-Check fehlschlägt	High
Homarr down	Dashboard nicht erreichbar	High
Portainer down	9443 via HTTPS nicht erreichbar	High
Tailscale remote failed	Hostname und 100.x.x.x nicht erreichbar	High
Netdata extern kritisch	CPU/RAM/Disk Alarm auf externer Instanz	Critical
Backup missing	Finale Tar-Artefakte fehlen / Backup-Cut nicht vorhanden	Critical

Alert-Panel Verhalten

Alle Homarr-Kacheln grün = betriebsbereit
Pause-/Stop-Test löst Farbwechsel reproduzierbar aus
Netdata ergänzt die reine Reachability um Systemzustand
Portainer dient bei Alarmen als operative Eingriffsoberfläche

Beispiel:
HIGH: OpenWebUI not reachable
HIGH: Portainer HTTPS path failed
CRITICAL: External Netdata reports host overload
CRITICAL: Final backup artifacts missing

Betrieb & Aufgabenmodell

Daily
• Homarr prüfen
• OpenWebUI testen
• Portainer Status prüfen
• Remote-Zugriff validieren

Weekly
• Netdata extern sichten
• Backup-Artefakte prüfen
• Container-/Stack-Zustände prüfen
• Kachel- und Healthchecks validieren

Change
• Backup vor Änderung
• Paralleltest
• LAN + Tailscale validieren
• Altzustände konsequent entfernen

Betriebsprinzip: Das Projekt setzt auf kleine, kontrollierte Änderungen statt großer Komplettumbauten. Jede produktive Verbesserung wurde parallel getestet, validiert und erst danach übernommen.

Troubleshooting

Homarr

500 Fehler durch ungültigen SECRET_ENCRYPTION_KEY
unhealthy Altzustand durch alte Struktur und Altvolumes
UI-Zittern im Edit Mode als Homarr-/Browser-Bug erkannt

OpenWebUI / Zugriff

Kachelproblem durch localhost/iframe/Öffnungsverhalten
Hostname-Zugriff als stabile Lösung implementiert
Frischer Datenzustand bewusst akzeptiert und dokumentiert

docker ps -a
docker logs --tail 100 homarr
docker logs --tail 100 openwebui
curl -I http://m4macmachine:7575
curl -I http://m4macmachine:3000
curl -k -I https://m4macmachine:9443
tailscale status
tailscale ip -4

Backup & Recovery

Backup

mkdir -p ~/docker-backup-final

docker run --rm -v frontend-stack_homarr-stack-v1_homarr_v1_appdata:/source -v ~/docker-backup-final:/backup busybox tar czf /backup/homarr_final.tar.gz -C /source .

docker run --rm -v frontend-stack_openwebui-stack-v1_openwebui_v1_data:/source -v ~/docker-backup-final:/backup busybox tar czf /backup/openwebui_final.tar.gz -C /source .

docker run --rm -v portainer_data:/source -v ~/docker-backup-final:/backup busybox tar czf /backup/portainer_final.tar.gz -C /source .

Recovery

docker run --rm -v frontend-stack_homarr-stack-v1_homarr_v1_appdata:/target -v ~/docker-backup-final:/backup busybox sh -c "cd /target && tar xzf /backup/homarr_final.tar.gz"

docker run --rm -v frontend-stack_openwebui-stack-v1_openwebui_v1_data:/target -v ~/docker-backup-final:/backup busybox sh -c "cd /target && tar xzf /backup/openwebui_final.tar.gz"

docker restart homarr
docker restart openwebui

Prinzip: Vor jedem größeren Ausbau einen sauberen Cut erzeugen und exakt diesen Zustand als belastbaren Wiederherstellungspunkt dokumentieren.

Anhang

Element	Pfad / Zweck
Finaler Stack	frontend-stack
Homarr Volume	frontend-stack_homarr-stack-v1_homarr_v1_appdata
OpenWebUI Volume	frontend-stack_openwebui-stack-v1_openwebui_v1_data
Portainer Volume	portainer_data
Homarr URL	http://m4macmachine:7575
OpenWebUI URL	http://m4macmachine:3000
Portainer URL	https://m4macmachine:9443
Tailscale IP	100.x.x.x
Backup-Pfad	~/docker-backup-final
Monitoring-Erweiterung	Externe Netdata-Instanz

Autor: MayIT – Projektdokumentation MayIT Docker KI & Monitoring Platform