From fef6dc253e66abd4eb67aa6bc10cddb221da6a2e Mon Sep 17 00:00:00 2001 From: Thomas Dannenberg Date: Thu, 23 Oct 2025 12:23:41 +0000 Subject: [PATCH] =?UTF-8?q?Kapitel=2021/Free=20Rohtext.md=20hinzugef=C3=BC?= =?UTF-8?q?gt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Kapitel 21/Free Rohtext.md | 964 +++++++++++++++++++++++++++++++++++++ 1 file changed, 964 insertions(+) create mode 100644 Kapitel 21/Free Rohtext.md diff --git a/Kapitel 21/Free Rohtext.md b/Kapitel 21/Free Rohtext.md new file mode 100644 index 0000000..2b60663 --- /dev/null +++ b/Kapitel 21/Free Rohtext.md @@ -0,0 +1,964 @@ +# Kapitel 21 – Home Assistant (Visuelles Kontrollzentrum) + +## Einleitung + +Mit wachsender Zahl an Containern, VMs und Diensten im **UCC** steigt auch der Bedarf nach einer zentralen, leicht bedienbaren Oberfläche. +Eine Stelle, an der Systemzustände, Ressourcen und Automatisierungen nicht mehr nur über Logfiles oder Dashboards sichtbar sind, +sondern intuitiv – mit einem Klick oder Schalter – steuerbar werden. + +**Home Assistant (HA)** bietet genau das: +Eine modulare, moderne Oberfläche zur Visualisierung und Steuerung sämtlicher Komponenten im Homelab. +Ob Systemmonitoring, Server-Status, Container-Abfragen oder einfache Automationen – +alles lässt sich übersichtlich in Dashboards bündeln und interaktiv bedienen. + +Im Gegensatz zu vielen anderen Tools ist Home Assistant kein „Smart-Home-Spielzeug“, +sondern eine **vollwertige Verwaltungsplattform**, die beliebige Systeme einbinden kann – +von Proxmox und Netdata über n8n bis hin zu selbstgebauten API-Schnittstellen. + +In diesem Kapitel richtest du **Home Assistant OS** als eigene **VM in Proxmox** ein, +bindest sie sicher über den bestehenden **Nginx Proxy Manager (NPM)** ein +und erstellst ein erstes Dashboard, das zentrale Kennzahlen deines Homelabs anzeigt. + +Dabei konzentrieren wir uns ausschließlich auf die Funktionen, +die im Rahmen des **UCC-Konzepts** tatsächlich einen Mehrwert bieten – +also auf Visualisierung, Systemüberwachung und Interaktion mit bestehenden Diensten. +Smart-Home-Automationen, Zigbee-Integration oder Sprachsteuerung sind bewusst **nicht Teil** dieses Kapitels. + +> [!NOTE] +> Home Assistant ist das Schaufenster deines UCC – die visuelle Verbindung aller bisher aufgebauten Systeme. +> Es ersetzt keine Spezialtools wie n8n oder Netdata, ergänzt sie aber durch ein klares, interaktives Frontend. + +👉 **Screenshot geeignet:** Übersicht des UCC-Dashboards mit markierter Home-Assistant-VM zwischen Netdata und n8n + +> [!TIP] +> Erweiterte Showcase-Tutorials zu speziellen Home-Assistant-Integrationen, +> wie z. B. Streaming-Anbindungen, Szenensteuerung oder dynamische Dashboards, +> erscheinen künftig separat als eigenständige Kapitel oder Premium-Folgen. + +--- +## Voraussetzungen & Ressourcen + +Home Assistant läuft in dieser Anleitung als eigenständige **VM** innerhalb deines UCC-Systems. +Die Virtualisierung bietet Stabilität, vollständige Supervisor-Funktionalität und flexible Wiederherstellungsoptionen. +Alle Dienste – vom System-Kernel bis zum Add-on-Management – befinden sich innerhalb der VM. +So bleibt der restliche Host entlastet, und du erhältst ein eigenständiges, update-sicheres System. + +### VM-Ressourcen + +* **CPU:** 2 vCPU + Erforderlich für parallele Prozesse wie Sensorabfragen, Dashboard-Rendering und Add-on-Verwaltung. + Bei späterer Erweiterung (z. B. mehrere Dashboards oder Integrationen) kann auf 4 vCPU erhöht werden. + +* **RAM:** 4 GB + Optimaler Wert für Home Assistant OS + Supervisor + Docker-Umgebung. + 2 GB funktionieren grundsätzlich, führen aber zu längeren Ladezeiten beim Start und beim Zugriff auf Add-ons. + +* **Speicherplatz:** 32 GB (virtuelle Disk) + Empfohlen, um Betriebssystem, Docker-Images, Backups und temporäre Logs abzudecken. + Der tatsächliche Verbrauch liegt im Free-Setup bei < 10 GB. + +* **Netzwerk:** Bridge-Mode mit statischer IP oder DHCP-Reservierung + Für die Einbindung über den Nginx Proxy Manager und die Kommunikation mit anderen Diensten. + Eine feste Zuordnung erleichtert Monitoring und Automatisierungen. + +* **Betriebssystem:** Home Assistant OS (x86-64, offizielle Image-Datei) + Enthält Supervisor, Add-on-Verwaltung und automatisches Update-System. + Die Image-Datei wird später direkt in Proxmox importiert. + +👉 **Screenshot geeignet:** Proxmox-Maske „Neue VM“ mit eingetragenen Werten (2 vCPU | 4 GB RAM | 32 GB Disk | Bridge Netzwerk) + +### Technische Voraussetzungen + +Vor der Einrichtung sollte dein UCC folgende Bedingungen erfüllen: + +* **Proxmox VE** ist aktiv und funktionsfähig. + Die VM wird direkt über die Web-Oberfläche angelegt und konfiguriert. + +* **Nginx Proxy Manager (NPM)** läuft als separater LXC-Container und ist erreichbar. + Darüber erfolgt später der HTTPS-Zugriff auf Home Assistant. + +* **DNS- oder DynDNS-Eintrag** für `ha.deinedomain.tld` oder `homeassistant.deinedomain.tld` existiert bereits. + Er wird für Zertifikate und internen Zugriff benötigt. + +* **Interner DNS-Resolver** (z. B. Pi-hole + Unbound) funktioniert zuverlässig, + damit die Subdomain auf die korrekte interne IP verweist. + +* **Internetverbindung** der VM ist aktiv, um Add-ons, Updates und Integrationen laden zu können. + +* **SSH-Zugriff** auf den Proxmox-Host ist vorhanden, falls Images manuell importiert oder verwaltet werden müssen. + +> [!IMPORTANT] +> Home Assistant OS verwendet eigene Docker-Instanzen innerhalb der VM. +> Eine Installation in einem LXC würde diese Funktionalität einschränken und führt zu fehlendem Supervisor-Support. + +👉 **Screenshot geeignet:** Proxmox-Interface mit markierter Home-Assistant-VM in der Liste (Status = running) + +> [!NOTE] +> Für eine performante Nutzung empfiehlt sich SSD-Speicher oder NVMe-Storage. +> Home Assistant führt regelmäßig Schreibvorgänge durch (Logs, Datenbank, Backups). +> Langsame I/O-Systeme können die Weboberfläche spürbar verlangsamen. + +--- + +## Schritt-für-Schritt-Anleitung + +### Schritt 1 – VM erstellen und Home-Assistant-Image importieren + +Home Assistant OS wird als vorgefertigtes **QCOW2-Image** bereitgestellt. +Dieses Image enthält das vollständige Betriebssystem, den Supervisor und alle Basis-Komponenten. +In diesem ersten Schritt richtest du die VM in **Proxmox** ein und importierst anschließend das offizielle Image. + +#### 1. QCOW2-Image herunterladen + +Wechsle zunächst auf deinen **Proxmox-Host** (z. B. per SSH oder über die Web-Shell) +und lade das aktuelle Home-Assistant-Image aus dem offiziellen Repository: + +```bash +cd /tmp +wget https://github.com/home-assistant/operating-system/releases/latest/download/haos_ova-14.2.qcow2.xz +``` + +Entpacke das Archiv: + +```bash +xz -d haos_ova-14.2.qcow2.xz +``` + +👉 **Screenshot geeignet:** Proxmox-Shell mit laufendem `wget`-Download und anschließendem Entpackvorgang + +> [!NOTE] +> Version 14.2 ist zum Zeitpunkt dieses Kapitels die aktuelle stabile Ausgabe. +> Prüfe vor Installation stets die [offizielle Release-Seite](https://github.com/home-assistant/operating-system/releases), +> falls neuere Versionen verfügbar sind. +> Das Vorgehen bleibt dabei identisch, lediglich der Dateiname ändert sich. + +#### 2. Neue VM in Proxmox anlegen + +Öffne das **Proxmox-Webinterface → Create VM** +und wähle folgende Einstellungen: + +| Bereich | Wert | +|----------|------| +| **Node** | dein Host (z. B. `pve01`) | +| **VM ID / Name** | 121 / Home-Assistant | +| **OS** | „Do not use any media“ (Image wird manuell importiert) | +| **System** | UEFI (OVMF) + EFI Disk aktiviert, Maschinentyp Q35 | +| **Hard Disk** | Dummy-Disk (8 MB, wird ersetzt) | +| **CPU** | 2 vCPU (Typ kvm64 oder host) | +| **Memory** | 4096 MB | +| **Network** | Bridge (vmbr0) oder VLAN nach deinem Setup | +| **Start at boot** | aktivieren | + +Klicke **Finish**, aber **starte die VM noch nicht**. + +👉 **Screenshot geeignet:** Proxmox-Wizard mit sichtbarer VM-Konfiguration (ID 121, 4 GB RAM, Bridge vmbr0) + +> [!TIP] +> Der EFI-Bootmodus ist Pflicht – Home Assistant nutzt GPT-Partitionen und startet nicht im Legacy-Modus. +> Verwende als Maschinentyp **Q35**, da dieser modernere Hardware-Features bietet und von HAOS empfohlen wird. + +#### 3. QCOW2-Image in Proxmox-Storage importieren + +Ermittle den Namen deines VM-Storage (z. B. `local-lvm`, `ssd-storage`, `zfs-pool`): + +```bash +pvesm status +``` + +Importiere das entpackte Image in den gewählten Storage und ordne es der VM 121 zu: + +```bash +qm importdisk 121 haos_ova-14.2.qcow2 +``` + +Nach erfolgreichem Import siehst du die neue Disk im Proxmox-GUI unter **Hardware → Unused Disk 0**. +Klicke auf **Edit → Add as SCSI Disk**, wähle als Controller **VirtIO SCSI (single)** +und markiere sie als **Boot Disk #1**. + +👉 **Screenshot geeignet:** Proxmox-Hardware-Tab der HA-VM mit sichtbarer importierter Disk „haos_ova-14.2.qcow2“ + +> [!IMPORTANT] +> Achte darauf, dass die Bootreihenfolge ausschließlich die importierte Disk enthält. +> Entferne Dummy- oder ISO-Einträge, bevor du die VM startest. +> Wenn du ZFS oder Ceph als Storage nutzt, kann das Importieren in ein „raw“-Format +> (`qm importdisk ... --format raw`) bessere Performance bringen. + +> [!TIP] +> Erstelle nach dem Import einen **Snapshot** der VM – +> so kannst du bei Problemen während der Erstkonfiguration jederzeit den Ausgangszustand wiederherstellen. + +#### 4. VM starten und Erst-Boot abwarten + +Starte die VM: + +```bash +qm start 121 +``` + +Wechsle in die **Konsole** und beobachte den Bootvorgang. +Nach etwa 2–3 Minuten erscheint die Meldung: + +``` +[INFO] Home Assistant OS running. +You can access the UI at: http://homeassistant.local:8123 +``` + +👉 **Screenshot geeignet:** Proxmox-Konsole mit erfolgreichem Boot-Log und URL-Hinweis auf Port 8123 + +> [!NOTE] +> Sollte die Konsole leer bleiben oder der Start hängen, überprüfe: +> - Bootmodus = UEFI (OVMF) +> - Controller = VirtIO SCSI (single) +> - Disk korrekt als Bootdisk markiert +> Bei Bedarf VM stoppen, Einstellungen anpassen, erneut starten. + +Nach dem ersten Boot öffne im Browser: + +``` +http://:8123 +``` + +> [!TIP] +> Home Assistant initialisiert im Hintergrund mehrere Docker-Container. +> Während der ersten 10 Minuten kann die Seite mehrfach neu laden oder „Preparing Home Assistant“ anzeigen. +> Warte, bis der Login-Bildschirm erscheint, bevor du fortfährst. + +> [!NOTE] +> Für zuverlässigen Zugriff empfiehlt sich eine **statische IP-Adresse** +> oder eine **DHCP-Reservierung** über deinen Pi-hole bzw. Router. +> So bleibt der Dienst stabil über NPM erreichbar, auch nach Neustarts. + +👉 **Screenshot geeignet:** Browserfenster mit sichtbarer Setup-Seite „Welcome to Home Assistant“ + +Damit ist die VM erfolgreich eingerichtet und Home Assistant OS läuft innerhalb deines UCC. +Im nächsten Schritt folgt die **Grundkonfiguration und Erst-Einrichtung über die Weboberfläche**. + +### Schritt 2 – Grundkonfiguration und Erst-Einrichtung + +Nach dem erfolgreichen Start der VM erreichst du die Weboberfläche von Home Assistant über: + +``` +http://:8123 +``` + +Beim ersten Aufruf erscheint der Setup-Assistent, der dich durch die grundlegende System- und Benutzerkonfiguration führt. +Diese Basiseinrichtung ist notwendig, damit Home Assistant später Add-ons, Integrationen und Updates korrekt verwalten kann. + +#### 1. Erstbenutzer anlegen + +Wähle einen **Benutzernamen**, eine **E-Mail-Adresse** und ein sicheres **Passwort**. +Dieser Account erhält automatisch Administratorrechte und dient als Hauptzugang für alle weiteren Konfigurationen. + +👉 **Screenshot geeignet:** Registrierungsmaske mit ausgefülltem Benutzernamen, E-Mail und Passwort + +> [!TIP] +> Verwende hier eine E-Mail-Adresse aus deiner UCC-Domäne (z. B. `ha@deinedomain.tld`), +> um spätere SMTP-Funktionen und Passwort-Resets konsistent zu halten. + +Nach dem Abschluss wirst du automatisch in das lokale Dashboard weitergeleitet. + +#### 2. Regionale Einstellungen + +Home Assistant fragt anschließend Standort, Zeitzone, Sprache und Maßeinheiten ab. +Diese Informationen werden u. a. für Zeitsteuerungen, Sonnenstands-Berechnungen und Energie-Dashboards genutzt. + +Empfohlene Werte: + +| Einstellung | Wert | +|--------------|------| +| **Standort** | Stadt oder Region deines UCC-Servers | +| **Zeitzone** | Europe/Berlin | +| **Sprache** | Deutsch | +| **Einheiten** | metrisch (°C, km/h, kWh) | + +👉 **Screenshot geeignet:** Dialog „Standort und Zeitzone“ mit ausgefüllten Werten + +> [!NOTE] +> Home Assistant nutzt diese Angaben nicht nur für visuelle Darstellungen, +> sondern auch für System-Trigger (z. B. zeitabhängige Automationen oder Energie-Analysen). + +#### 3. Gerätediscovery überspringen + +Der Assistent bietet an, automatisch Geräte und Smart-Home-Komponenten im Netzwerk zu suchen. +Da der Fokus hier auf der **Homelab-Integration** liegt, überspringe diesen Schritt mit **„Weiter“**. + +👉 **Screenshot geeignet:** Bildschirm „Geräte erkannt“ mit ausgewählter Option *Überspringen* + +> [!IMPORTANT] +> Diese automatische Suche erkennt u. a. Chromecast-, Hue- oder Zigbee-Geräte. +> Für das UCC ist das irrelevant und kann die Übersicht unnötig füllen. +> Wir fügen nur gezielte Integrationen hinzu, die System- oder Monitoring-Bezug haben. + +#### 4. System-Update und Stabilitätsprüfung + +Nach dem Login prüft Home Assistant automatisch, ob Updates verfügbar sind. +Falls eine Meldung **„Update available“** erscheint, installiere sie sofort. + +👉 **Screenshot geeignet:** Update-Hinweis im Home-Assistant-Dashboard mit aktivem Button *Update now* + +> [!TIP] +> Home Assistant OS aktualisiert sowohl das Basissystem als auch den Supervisor. +> Plane bei großen Versionen immer einen **Proxmox-Snapshot** vor dem Update ein, +> um ein funktionsfähiges Rollback zu behalten. + +#### 5. Backup-Option aktivieren + +Unter **Einstellungen → System → Backups** kannst du lokale Snapshots (sogenannte *Backups*) aktivieren. +Damit erstellt Home Assistant automatisch Sicherungen von Konfiguration und Add-ons innerhalb der VM. + +👉 **Screenshot geeignet:** Menü *System → Backups* mit aktivierter Option *Automatische Sicherungen* + +> [!NOTE] +> Diese internen Backups ersetzen nicht dein externes Kopia-Backup. +> Sie dienen nur als kurzfristige Sicherung für Rollbacks innerhalb von Home Assistant. + +#### 6. NPM-Erreichbarkeit testen + +Wenn dein Nginx Proxy Manager bereits läuft, sollte Home Assistant nach dem ersten Start intern erreichbar sein unter: + +``` +https://ha.deinedomain.tld +``` + +> [!TIP] +> Wenn die Seite per HTTP, aber nicht per HTTPS funktioniert, +> überprüfe im NPM-Eintrag, ob **WebSockets** und **Force SSL** aktiviert sind. +> Diese Optionen sind für die Lovelace-UI und Live-Updates zwingend erforderlich. + +👉 **Screenshot geeignet:** Browserfenster mit Home-Assistant-Dashboard unter `https://ha.deinedomain.tld` (Schloss-Symbol sichtbar) + +#### 7. Basis-Integrationen vorbereiten + +Sobald das System stabil läuft, öffne **Einstellungen → Geräte & Dienste**. +Hier siehst du eine Liste möglicher Integrationen. +Für das Free-Setup sind besonders folgende relevant: + +- **Systemmonitor** → CPU-, RAM-, Disk-, Netzwerk-Statistiken +- **Proxmox Sensor** (über API-Token) +- **Netdata** (über JSON-API) +- **Ping** für Container-Verfügbarkeiten + +👉 **Screenshot geeignet:** Menü *Einstellungen → Geräte & Dienste* mit markiertem Eintrag *Systemmonitor* + +> [!NOTE] +> Diese Integrationen sind im Free-Teil vorgesehen. +> Erweiterte oder visuell angepasste Dashboards folgen im Premium-Abschnitt. + +#### 8. Abschluss der Erst-Einrichtung + +Nach der Basiskonfiguration befindet sich dein Home Assistant in einem stabilen, update-fähigen Zustand. +Du hast jetzt Zugriff auf das Haupt-Dashboard (*Lovelace UI*) und kannst mit der Erstellung erster Ansichten beginnen. + +👉 **Screenshot geeignet:** Start-Dashboard nach Erst-Setup mit sichtbarer Navigationsleiste „Übersicht | Einstellungen | Benachrichtigungen“ + +> [!TIP] +> Lege nach der Einrichtung erneut einen **Snapshot in Proxmox** an. +> So kannst du jederzeit zu einem sauberen Ausgangszustand zurückkehren, +> bevor du Integrationen oder Dashboards erweiterst. + +### Schritt 3 – Community Store (HACS) installieren und Grundmodule hinzufügen + +Bevor du mit individuellen Dashboards beginnst, installierst du den **Home Assistant Community Store (HACS)**. +Er dient als zentrale Quelle für Community-Erweiterungen, zusätzliche Karten, Themes und Integrationen, +die im offiziellen Store von Home Assistant nicht enthalten sind. + +Damit kannst du dein System später flexibel erweitern, ohne manuelle YAML-Anpassungen oder Docker-Eingriffe. + +#### 1. Vorbereitung und Entwickler-Modus aktivieren + +Öffne in Home Assistant: + +**Einstellungen → System → Allgemein → Erweitert** +und aktiviere den **Entwickler-Modus**. + +👉 **Screenshot geeignet:** Systemeinstellungen mit aktivierter Option *Entwickler-Modus* + +> [!NOTE] +> Der Entwickler-Modus ermöglicht Zugriff auf Logdateien, YAML-Editoren und erweiterte Integrationsoptionen – +> Voraussetzung für die Installation von HACS. + +#### 2. SSH- oder Terminal-Zugang öffnen + +Wechsle in **Einstellungen → Add-ons → Add-on Store → Terminal & SSH** +und installiere das offizielle **Terminal & SSH Add-on** von Nabu Casa. + +Starte das Add-on und öffne anschließend das Terminal-Fenster in Home Assistant. + +👉 **Screenshot geeignet:** Add-on-Store mit markiertem *Terminal & SSH* Add-on (Status: running) + +> [!TIP] +> Wenn du lieber über Proxmox auf die Konsole zugreifst, ist das ebenfalls möglich. +> Die Befehle sind identisch – HACS wird direkt in der VM installiert. + +#### 3. HACS herunterladen und installieren + +Führe im Terminal folgende Befehle aus: + +```bash +wget -O - https://get.hacs.xyz | bash - +``` + +Nach erfolgreichem Download startet die Installationsroutine automatisch und legt die erforderlichen Verzeichnisse an: + +``` +/config/custom_components/hacs +``` + +Starte anschließend Home Assistant neu: + +```bash +ha core restart +``` + +👉 **Screenshot geeignet:** Terminalausgabe mit sichtbarer Meldung *Installation complete, please restart Home Assistant* + +> [!IMPORTANT] +> Führe den Neustart unbedingt durch – HACS wird erst danach als Integration erkannt. +> Ohne Neustart bleibt die Oberfläche leer und keine HACS-Option erscheint in den Einstellungen. + +#### 4. HACS einbinden und GitHub verbinden + +Nach dem Neustart öffne: + +**Einstellungen → Geräte & Dienste → Integration hinzufügen → HACS** + +Klicke auf **HACS (Community Store)** und folge dem Einrichtungsassistenten: + +1. **GitHub-Authentifizierung starten** + - Melde dich mit deinem GitHub-Account an. + - Gewähre HACS Zugriff auf deine öffentlichen Repositories (privat ist nicht nötig). +2. **Region auswählen:** Europe (empfohlen) +3. **Haken setzen:** „Ich habe die Bedingungen gelesen“ +4. **Fortfahren** klicken + +Nach Abschluss erscheint im Menü ein neuer Eintrag **HACS**. + +👉 **Screenshot geeignet:** Integrationsübersicht mit aktivem *HACS*-Eintrag + +> [!NOTE] +> HACS nutzt GitHub zur Versionsverwaltung. +> Deine Daten bleiben lokal – es werden keine Home-Assistant-Konfigurationen in die Cloud geladen. + +#### 5. Sinnvolle Basiserweiterungen installieren + +Öffne **HACS → Integrationen** und installiere folgende Module, die für das UCC-Konzept relevant sind: + +| Kategorie | Name | Funktion | +|------------|------|----------| +| **Integrationen** | *Mini Graph Card* | Kompakte Verlaufsgrafen für CPU, RAM, Netzaktivität | +| **Integrationen** | *Button Card* | Individuell gestaltbare Steuerbuttons | +| **Integrationen** | *Card Mod* | CSS-Anpassungen und Themes | +| **Integrationen** | *Browser Mod* | Lokale Anzeigeoptimierung, z. B. für Streaming-Setups | +| **Integrationen** | *Simple Weather Card* | Optionale Wetteranzeige für das Dashboard | +| **Frontend-Themes** | *Clear Dark* oder *Minimalist UI* | Grundlage für Bratonien-Farbschema | + +👉 **Screenshot geeignet:** HACS-Integrationsseite mit markierten Einträgen *Mini Graph Card* und *Button Card* + +> [!TIP] +> Diese Basismodule erleichtern dir später den Aufbau eines klar strukturierten Dashboards +> und ermöglichen Branding-Anpassungen ohne tiefen YAML-Code. + +#### 6. Home Assistant erneut neu starten + +Nach der Installation aller Erweiterungen führe erneut einen Neustart durch: + +```bash +ha core restart +``` + +👉 **Screenshot geeignet:** Terminalausgabe mit *Home Assistant Core restarted successfully* + +> [!NOTE] +> Alle über HACS installierten Module werden bei Neustart automatisch in die Oberfläche eingebunden. +> Du findest sie anschließend unter **Einstellungen → Dashboard → Karte hinzufügen**. + +#### 7. Prüfung der Installation + +Nach dem Neustart öffne **Einstellungen → Integrationen**. +HACS sollte mit dem Status *Aktiv* und einer Versionsnummer sichtbar sein. + +👉 **Screenshot geeignet:** Integrationsliste mit aktivem *HACS* (Status: aktiv) + +> [!TIP] +> Wenn HACS nicht erscheint, lösche Browser-Cache oder führe einen Hard-Reload (STRG + F5) durch. +> In seltenen Fällen hilft auch ein zweiter Neustart, bis alle Komponenten initialisiert sind. + +Damit ist der Community Store erfolgreich installiert. +Im nächsten Schritt erstellst du dein erstes Dashboard mit den neu verfügbaren Karten und Sensoren. + +### Schritt 4 – Erstes Dashboard: Dein UCC sichtbar machen + +Bis hierhin läuft Home Assistant als eigene VM im UCC – aber sie zeigt noch nichts an. +Jetzt lernst du, wie du deinem System beibringst, **sichtbare Daten** anzuzeigen: +CPU-Last, RAM-Auslastung und den Status deiner wichtigsten Container wie Nextcloud, Vaultwarden oder Nginx Proxy Manager. + +Home Assistant arbeitet mit sogenannten **Entitäten**. +Eine Entität ist einfach ein Datenpunkt – also z. B. „Container 102 ist online“ oder „CPU hat 43 % Last“. +Diese Werte erscheinen automatisch, sobald du eine passende Integration oder einen Sensor einrichtest. + +Am Ende dieses Schrittes siehst du auf einem Dashboard, **wer arbeitet, wer schläft und wie ausgelastet dein UCC gerade ist.** + +### 1. Welche Daten wir sichtbar machen + +| Quelle | Zweck | Ergebnis | +|---------|--------|-----------| +| **Systemmonitor** | misst die Auslastung der Home-Assistant-VM | CPU-, RAM- und Netzwerknutzung | +| **Proxmox-Integration** | liest Host- und Container-Infos über die API aus | Host-CPU, Speicher, Container-Status | +| **Ping-Sensoren** | prüft, ob LXCs erreichbar sind | einfache Online-/Offline-Anzeige | +| **Netdata (optional)** | liefert detaillierte Live-Werte | CPU-, RAM-, IO- und Disk-Statistiken | + +Du nutzt also ausschließlich Dienste, die du bereits im UCC betreibst – keine neue Software nötig. + +### 2. Systemmonitor aktivieren + +Öffne **Einstellungen → Geräte & Dienste → Integration hinzufügen → Systemmonitor** +und wähle die Sensoren, die dich interessieren: + +- Prozessorlast +- Arbeitsspeicher +- Festplattenspeicher +- Netzwerkverkehr + +Speichere deine Auswahl. +Nach wenigen Sekunden erscheinen diese Sensoren automatisch im System. + +👉 **Screenshot geeignet:** Integrationsseite mit aktivem *Systemmonitor* und den vier angehakten Werten + +> [!NOTE] +> Diese Werte stammen aus der Home-Assistant-VM selbst – du siehst also direkt, wie stark sie belastet ist. + +### 3. Proxmox-Integration hinzufügen + +Damit Home Assistant auch deinen Host und die LXCs anzeigt, nutzt du die **Proxmox VE-Integration**. + +1. Melde dich per SSH am Proxmox-Host an und erstelle einen eigenen API-Benutzer: + ```bash + pveum user add ha@pve --password + pveum aclmod / -user ha@pve -role PVEAuditor + ``` + Damit darf Home Assistant Systemwerte lesen, aber nichts verändern. + +2. Öffne in Home Assistant **Einstellungen → Integrationen → Hinzufügen → Proxmox VE** + und trage ein: + - **Host:** `https://:8006` + - **Benutzer:** `ha@pve` + - **Passwort:** das zuvor gesetzte + - **SSL-Prüfung:** deaktivieren (interne Verbindung) + +Nach kurzer Verbindung erscheint eine Liste deiner Proxmox-Knoten und Container. +Jeder Container wird automatisch als Entität angelegt – z. B. `sensor.vm_102_status`. + +👉 **Screenshot geeignet:** Integrationsliste mit aktivem *Proxmox VE*-Eintrag und mehreren LXCs darunter + +> [!TIP] +> Über diese Integration kannst du sehen, welche LXC-Container gerade laufen, +> wie viel CPU- und RAM-Leistung sie brauchen und ob der Host ausgelastet ist. + +### 4. Container-Erreichbarkeit prüfen + +Für eine einfache Online-Anzeige reicht oft schon ein Ping-Sensor. +Öffne **Einstellungen → Geräte & Dienste → Integration hinzufügen → Ping** +und gib für jeden wichtigen Container dessen IP ein. + +Beispiel: +- Nginx Proxy Manager → 192.168.10.11 +- Nextcloud → 192.168.10.20 +- Vaultwarden → 192.168.10.30 + +Jeder Container erscheint anschließend als Schalter, der anzeigt, ob er erreichbar ist. + +👉 **Screenshot geeignet:** Entitätenliste mit drei Ping-Sensoren (grün = erreichbar) + +> [!NOTE] +> Wenn du den Container stoppst, wird der Schalter rot. +> So erkennst du auf einen Blick, ob ein Dienst ausgefallen ist. + +### 5. Dashboard erstellen + +Gehe zu **Übersicht → Bearbeiten → Karte hinzufügen**. +Wähle zunächst einfache **Anzeigenkarten**, um die Werte sichtbar zu machen: + +1. **Gauge-Karten** + - CPU-Auslastung + - RAM-Belegung + - Festplattennutzung + +2. **Verlaufsdiagramm** + - Netzwerkverkehr oder Netdata-CPU-Last + +3. **Button-Karten** + - Nextcloud erreichbar + - NPM erreichbar + - Vaultwarden erreichbar + +Ordne die Karten so, dass Systemwerte oben und Container unten stehen. +Klicke **Fertig**, um zu speichern. + +👉 **Screenshot geeignet:** Dashboard mit drei Gauge-Karten oben und drei Status-Buttons unten + +> [!TIP] +> Wenn du HACS installiert hast, kannst du statt der Standard-Karten +> die *Mini Graph Card* (für kompakte Diagramme) und *Button Card* (für schönere Status-Kacheln) verwenden. +> Beide findest du unter **Karte hinzufügen → Benutzerdefinierte Karten**. + +### 6. Test und Feinschliff + +Öffne das Dashboard im Browser und beobachte, wie sich die Werte aktualisieren. +Stoppe testweise einen Container in Proxmox – die Statuskarte sollte sich in wenigen Sekunden ändern. + +👉 **Screenshot geeignet:** Dashboard mit einer rot markierten Containerkarte nach Test-Stopp + +> [!TIP] +> Die Aktualisierungsrate kannst du unter **Einstellungen → System → Allgemein → Update-Intervall** anpassen. +> Standard sind 30 Sekunden – für Monitoring reicht das völlig. + +Damit hast du dein erstes funktionierendes Dashboard erstellt. +Es zeigt live, wie aktiv dein Host ist, welche Container laufen und ob alle Dienste erreichbar sind. +Im nächsten Schritt kümmern wir uns darum, wie du Home Assistant wartest, sicherst und bei Problemen wieder stabil bekommst. + +### Schritt 5 – Integration in den Nginx Proxy Manager (NPM) + +Home Assistant läuft – jetzt binden wir ihn sauber über **NPM** ein. +Wichtig: Zuerst Home Assistant für Reverse-Proxy-Header freischalten, sonst blockt HA die Anmeldung. + +### 1. Home Assistant für Reverse Proxy vorbereiten + +Ziel: HA vertraut den X-Forwarded-Headern von NPM und verweigert sie nicht. + +Variante A: per **File Editor Add-on** +Einstellungen → Add-ons → Add-on Store → **File editor** installieren → öffnen → Datei `/config/configuration.yaml` bearbeiten. + +Variante B: per **Terminal & SSH** +Einstellungen → Add-ons → **Terminal & SSH** → öffnen → Datei editieren: +``` +nano /config/configuration.yaml +``` + +Füge (oder ergänze) folgenden Block ein und setze **die IP deines NPM-LXC** ein (Beispiel `192.168.10.11`): + +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 192.168.10.11 # IP deines NPM-Containers + ip_ban_enabled: true + login_attempts_threshold: 5 +``` + +Speichern, dann Home Assistant neu starten: +``` +ha core restart +``` + +👉 **Screenshot geeignet:** File-Editor mit geöffnetem `configuration.yaml` und markiertem `http:`-Block + +> [!IMPORTANT] +> Ohne diesen Eintrag siehst du im Log Meldungen wie +> „Login attempt or request with invalid authentication from “ +> und die Web-UI hinter NPM funktioniert nicht korrekt. + +Optional (empfohlen): externe URL setzen +Einstellungen → System → Netzwerk → **Externe URL**: +``` +https://ha.deinedomain.tld +``` + +👉 **Screenshot geeignet:** HA-Einstellungen → System → Netzwerk → Feld *Externe URL* + +### 2. NPM-Dashboard öffnen + +Rufe dein NPM auf, z. B.: +``` +https://npm.deinedomain.tld +``` +Anmelden → **Hosts → Proxy Hosts → Add Proxy Host**. + +👉 **Screenshot geeignet:** NPM-Startseite mit markiertem *Add Proxy Host* + +### 3. Proxy-Host für Home Assistant anlegen + +| Feld | Eintrag | +|------|--------| +| Domain Names | `ha.deinedomain.tld` | +| Scheme | `http` | +| Forward Hostname / IP | `192.168.10.50` *(IP der HA-VM)* | +| Forward Port | `8123` | +| Block Common Exploits | aktivieren | +| WebSocket Support | aktivieren | + +Speichern. + +👉 **Screenshot geeignet:** Formular *Add Proxy Host* mit ausgefüllten HA-Werten + +> [!TIP] +> IP der HA-VM vorher testen: +> `http://192.168.10.50:8123` muss lokal erreichbar sein. + +### 4. SSL aktivieren (Let’s Encrypt) + +Im Proxy-Eintrag → Tab **SSL**: + +- **Request a new SSL Certificate** +- **Force SSL** +- **HTTP/2 Support** +- **HSTS Enabled** + +Anbieter: **Let’s Encrypt**, dann **Save**. + +👉 **Screenshot geeignet:** NPM-SSL-Tab mit aktivierter Let’s-Encrypt-Anforderung + +> [!NOTE] +> DNS-A-Record `ha.deinedomain.tld` muss auf deinen Server zeigen, sonst schlägt die Zertifikatsanforderung fehl. + +### 5. Verbindung testen + +Aufrufen: +``` +https://ha.deinedomain.tld +``` +Die HA-Anmeldeseite sollte erscheinen, **mit Schloss-Symbol**. + +👉 **Screenshot geeignet:** Browser mit `https://ha.deinedomain.tld` (SSL aktiv) + +> [!TIP] +> Leere Seite oder kein Live-Update? In NPM prüfen, ob **WebSocket Support** aktiviert ist. + +### 6. Zugriff einschränken (intern empfohlen) + +NPM → **Access List** erstellen: +- Name: `HA-internal` +- Allow: `192.168.0.0/16` *(dein internes Netz)* +- Deny all others + +Diese Access List im HA-Proxy-Host zuweisen. + +👉 **Screenshot geeignet:** Access-List mit internem Netz und *Deny all others* + +> [!IMPORTANT] +> HA nicht ungeschützt ins Internet stellen. Für externen Zugriff: VPN (z. B. WireGuard) nutzen. + +### 7. Abschlussprüfung + +Dashboard unter `https://ha.deinedomain.tld` öffnen. +Karten müssen live aktualisieren, Login stabil, keine „invalid authentication“-Logs. + +👉 **Screenshot geeignet:** HA-Dashboard über HTTPS, alle Kacheln aktiv + +> [!NOTE] +> Wenn du später NPM migrierst oder dessen IP änderst, **aktualisiere `trusted_proxies` in HA**. +> Mehrere Proxies? Einfach weitere IPs/Subnetze unter `trusted_proxies` ergänzen. + +--- + +## Troubleshooting & Tipps + +Auch wenn Home Assistant im Normalbetrieb stabil läuft, kann es im UCC-Alltag zu Problemen oder unerwartetem Verhalten kommen. +Dieses Kapitel fasst alle typischen Fehlerbilder, Wartungshinweise und Best Practices zusammen, +damit du dein System schnell stabil bekommst und langfristig sauber betreiben kannst. + +### Home Assistant startet nicht mehr + +**Symptom:** +Weboberfläche bleibt weiß oder meldet „Seite nicht erreichbar“. + +**Ursache:** +Fehler in der `configuration.yaml` oder zu wenig RAM in der VM. + +**Lösung:** +1. Per SSH oder Terminal-Add-on einloggen. +2. Logs prüfen: + ```bash + ha core logs + ``` +3. Bei YAML-Fehlern Datei öffnen: + ```bash + nano /config/configuration.yaml + ``` + und Einzüge korrigieren (zwei Leerzeichen pro Ebene, keine Tabs). +4. Neustart: + ```bash + ha core restart + ``` + +👉 **Screenshot geeignet:** Terminal mit Log-Ausgabe und markierter Fehlerzeile + +> [!TIP] +> YAML ist empfindlich – schon ein fehlendes Leerzeichen kann das System stoppen. +> Nach Änderungen immer `ha core check` ausführen, bevor du neu startest. + +### „Login attempt or request with invalid authentication“ + +**Symptom:** +Nach NPM-Einrichtung kein Login möglich, Log zeigt Authentifizierungsfehler. + +**Ursache:** +`trusted_proxies` fehlt oder enthält falsche IP. + +**Lösung:** +In `/config/configuration.yaml` sicherstellen: +```yaml +http: + use_x_forwarded_for: true + trusted_proxies: + - 192.168.10.11 +``` +Danach: +```bash +ha core restart +``` + +👉 **Screenshot geeignet:** File-Editor mit markiertem trusted_proxies-Block + +> [!NOTE] +> Bei Änderung der NPM-IP muss dieser Wert immer angepasst werden. + +### Dashboard aktualisiert sich nicht + +**Symptom:** +Karten bleiben leer, Sensorwerte ändern sich nicht. + +**Ursachen:** +- WebSocket-Support im NPM deaktiviert +- Sensor nicht verfügbar +- Browsercache blockiert neue Daten + +**Lösungen:** +1. In NPM: *Proxy Host → Edit → Advanced → WebSocket Support aktivieren* +2. In HA prüfen: *Einstellungen → Integrationen → Sensor → Letzte Aktualisierung* +3. Browser-Cache leeren oder Inkognito-Modus testen. + +👉 **Screenshot geeignet:** NPM-Proxy-Dialog mit aktivem WebSocket-Haken + +> [!TIP] +> Wenn nur eine Karte betroffen ist, stimmt meist die Entität im Dashboard nicht – Karte bearbeiten und neu zuweisen. + +### SSL-Zertifikat schlägt fehl + +**Symptom:** +Let’s-Encrypt-Anforderung in NPM bricht ab oder meldet Timeout. + +**Ursachen:** +- DNS zeigt nicht auf deinen Server +- Port 80/443 blockiert +- DynDNS noch nicht aktualisiert + +**Lösung:** +1. DNS-Eintrag `ha.deinedomain.tld` prüfen. +2. Router-Ports 80 und 443 temporär freigeben. +3. Zertifikat in NPM manuell erneut anfordern. + +👉 **Screenshot geeignet:** NPM-SSL-Tab mit sichtbarem Zertifikatsstatus + +> [!NOTE] +> Nach erfolgreicher Ausstellung erneuert NPM das Zertifikat automatisch. + +### Fehlende Integrationen oder Karten + +**Symptom:** +Nach Neustart fehlen HACS-Karten oder es erscheinen Fehlermeldungen. + +**Ursache:** +HACS-Ressourcen nicht geladen oder Pfad in Dashboard-Ressourcen fehlt. + +**Lösung:** +1. Home Assistant → Dashboards → Ressourcen prüfen. + Beispiel: + ``` + /hacsfiles/mini-graph-card/mini-graph-card.js + ``` +2. Falls leer → HACS öffnen → Frontend → Karte neu installieren. +3. Neustart: + ```bash + ha core restart + ``` + +👉 **Screenshot geeignet:** Ressourcenliste mit sichtbaren HACS-Pfaden + +> [!TIP] +> Nach HACS-Updates „Reload resources“ ausführen – das behebt 90 % der Anzeigefehler. + +### Backup & Wiederherstellung + +**Empfehlung:** +Home-Assistant-VM täglich mit Kopia sichern. + +Zu sichernde Pfade: +- `/config/` – Konfiguration, Dashboards, Integrationen +- `/ssl/` – Zertifikate (optional) +- `/media/` – hochgeladene Dateien + +In Kopia: +1. Quelle: `/config` auswählen +2. Name: *Home Assistant Config* +3. Zeitplan: täglich um 03:00 Uhr +4. Kompression und Verschlüsselung aktivieren + +👉 **Screenshot geeignet:** Kopia-Dashboard mit Eintrag *Home Assistant Config* + +> [!NOTE] +> Nach jedem großen Update manuell ein zusätzliches Snapshot-Backup anlegen. +> So kannst du defekte Versionen sofort zurückrollen. + +### Pflege & Wartung + +Ein stabiles Home-Assistant-System im UCC braucht kaum Eingriffe – +aber regelmäßige Kontrolle hält es dauerhaft zuverlässig. + +**Empfohlene Routine:** +- **Einmal pro Woche:** + VM neu starten (`ha host reboot`) – leert Caches und verhindert Speicherlecks. +- **Einmal im Monat:** + Add-ons und HACS-Komponenten aktualisieren. + → Supervisor-Panel → Updates prüfen → Haken setzen → Update. +- **Nach jeder größeren Änderung:** + ```bash + ha core check + ha core restart + ``` +- **Logs prüfen:** + `ha core logs` auf Fehlermeldungen scannen. + Wiederkehrende Warnungen dokumentieren – meist kündigen sie inkompatible Integrationen an. +- **Automatische Updates deaktivieren:** + Lieber manuell prüfen und gezielt installieren. + Neue Versionen können bestehende Dashboards oder Integrationen brechen. +- **Nicht benötigte Add-ons entfernen:** + Weniger aktive Dienste = geringere Fehlerwahrscheinlichkeit. + +👉 **Screenshot geeignet:** Supervisor-Panel mit sichtbaren Update-Optionen + +> [!TIP] +> Home Assistant ist modular – je schlanker das Setup, desto stabiler läuft das System. + +### Allgemeine Hinweise + +- Home Assistant nie ohne SSL und Proxy betreiben. +- Keine Ports direkt aus dem Internet öffnen. +- Backups regelmäßig testen – Wiederherstellung ist wichtiger als Sicherung. +- Bei unklaren Fehlern zuerst Logs prüfen, nicht neu installieren. + +Damit hast du alle Werkzeuge, um dein Home-Assistant-System im UCC stabil zu halten, +Fehler schnell zu erkennen und Wartung planbar durchzuführen. + +--- + +## Abschluss + +Mit der Einrichtung von Home Assistant hast du im UCC ein zentrales Werkzeug geschaffen, das alle Systeme sichtbar und steuerbar macht. +Du kannst jetzt auf einem Blick sehen, welche Container aktiv sind, wie stark dein Host ausgelastet ist +und ob wichtige Dienste wie Nextcloud, Vaultwarden oder NPM erreichbar sind. + +Durch die Integration über den Nginx Proxy Manager läuft alles sicher per HTTPS, +und dank der Dashboard-Struktur kannst du dein UCC flexibel erweitern – +egal ob um neue Sensoren, Automatisierungen oder eigene Ansichten. + +Home Assistant bildet damit den logischen Abschluss der Free-Reihe: +Ein vollständiges, lokal betriebenes Kontrollzentrum, das dein Homelab nicht nur organisiert, +sondern es *sichtbar, messbar und bedienbar* macht – ohne Cloud, ohne externe Abhängigkeiten. + +> [!TIP] +> Wenn du Lust auf mehr hast, folgen in den Premium-Kapitel spätere Erweiterungen: +> automatisierte Steuerung, Benachrichtigungen, API-Verknüpfungen mit n8n, +> sowie visuelle Dashboards im Bratonien-Design. + +Damit ist die Basis vollständig abgeschlossen. +Dein UCC kann jetzt wachsen – kontrolliert, sicher und unter deiner eigenen Verwaltung. \ No newline at end of file