Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 21/Free Rohtext.md

# 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 <storage-name>
```

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://<IP-der-VM>: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://<IP-der-VM>: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 <STRONG_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://<IP-des-Proxmox>: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 <NPM-IP>“  
> 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.