homeESS installieren – Schritt für Schritt für Einsteiger

Bastelecke > Smarthome > homeESS > Installation & erste Schritte

In dieser Anleitung wird homeESS auf einem Debian-basierten System installiert. Geeignet sind zum Beispiel ein Raspberry Pi, ein Mini-PC, eine virtuelle Maschine oder ein LXC-Container unter Proxmox.

homeESS läuft als kleiner Server im Heimnetz. Nach der Installation ist die Oberfläche über den Browser erreichbar. Von dort aus können später MQTT, Photovoltaik, Batterie, Verbraucher, Prognose, Wallbox, Poolsteuerung und weitere Module eingerichtet werden.

1. Was wird benötigt?

Für den Einstieg reicht einfache Hardware aus:

• Raspberry Pi 4 oder 5
• Mini-PC, zum Beispiel Intel N100
• kleine VM oder LXC-Container
• Debian, Ubuntu oder Raspberry Pi OS
• Netzwerkverbindung, am besten per LAN-Kabel
• Zugriff auf die Konsole per Tastatur, Bildschirm oder SSH

Empfohlen sind mindestens 2 CPU-Kerne, 1 GB RAM und 8 GB Speicher. homeESS selbst ist schlank und verwendet Node.js, SQLite und MQTT.

2. Betriebssystem vorbereiten

Am einfachsten ist eine frische Debian-Installation ohne Desktop-Oberfläche. Eine minimale Serverinstallation reicht völlig aus. Eine Anleitung, wie man auf Proxmox einen virtuellen Container mit frischem Debian System anlegt, findest du im meiner Anleitung: Vituellen Container in Proxmox erstellen

Nach dem Start am System anmelden.

Falls du direkt als root angemeldet bist, kannst du die Befehle direkt ausführen. Falls du als normaler Benutzer angemeldet bist, wird bei einigen Befehlen sudo benötigt.

Zuerst wird das System aktualisiert:

sudo apt update
sudo apt upgrade -y

Falls sudo nicht vorhanden ist und du als root angemeldet bist, verwende stattdessen:

apt update
apt upgrade -y

3. curl und sudo installieren

Für die automatische Installation benötigt das System curl. Auf Minimalinstallationen ist das oft noch nicht installiert.

sudo apt install -y curl sudo

Als root ohne sudo:

apt install -y curl sudo

4. homeESS automatisch installieren

Jetzt wird homeESS mit einem einzigen Befehl installiert:

curl -fsSL https://raw.githubusercontent.com/mykaefer/home-ess/main/install.sh | sudo bash

Wenn du bereits als root angemeldet bist, kannst du sudo weglassen:

curl -fsSL https://raw.githubusercontent.com/mykaefer/home-ess/main/install.sh | bash

Das Installationsskript erledigt automatisch die wichtigsten Schritte:

• benötigte Systempakete installieren
• Node.js bereitstellen, falls nötig
• homeESS nach /opt/home-ess klonen
• Datenbank unter /var/lib/home-ess/app.db anlegen
• systemd-Service einrichten
• homeESS automatisch starten
• Autostart beim Systemboot aktivieren

Eine vorhandene Installation oder Datenbank wird aus Sicherheitsgründen nicht einfach überschrieben.

5. Prüfen, ob homeESS läuft

Nach der Installation kann der Dienst geprüft werden:

systemctl status home-ess

Wenn alles funktioniert, sollte der Dienst als aktiv angezeigt werden.

Mit q verlässt du die Statusansicht wieder.

Falls du die Live-Ausgabe sehen möchtest:

journalctl -u home-ess -f

Abbrechen kannst du diese Ansicht mit:

STRG + C

6. IP-Adresse des Systems herausfinden

Damit du die Weboberfläche öffnen kannst, brauchst du die IP-Adresse des Geräts.

hostname -I

Die Ausgabe sieht zum Beispiel so aus:

192.168.178.50

Die genaue Adresse ist bei dir natürlich anders.

7. homeESS im Browser öffnen

Öffne jetzt auf einem PC, Tablet oder Smartphone im gleichen Netzwerk den Browser und gib ein:

http://<IP-Adresse>:3000

Beispiel:

http://192.168.178.50:3000

Der Standard-Port von homeESS ist 3000.

8. Erster Login

Beim ersten Start lautet das Standard-Passwort:

admin

Nach dem Login sollte das Passwort direkt geändert werden.

Dazu in homeESS öffnen:

Einstellungen → Neues Passwort

Ein dauerhaft verwendetes Standardpasswort ist keine gute Idee, besonders wenn später Schaltfunktionen, MQTT oder externe Adapter genutzt werden.

9. MQTT-Broker einrichten

homeESS arbeitet zentral mit MQTT. Es kann zum Beispiel ein ioBroker-MQTT-Broker verwendet werden.

Die MQTT-Einstellungen findest du unter:

Einstellungen → MQTT-Broker

Dort werden typischerweise eingetragen:

• Host oder IP-Adresse des MQTT-Brokers
• Port
• Benutzername, falls vorhanden
• Passwort, falls vorhanden

Beispiel:

Host: 192.168.178.20
Port: 1883

Nach dem Speichern sollte die Verbindung getestet werden.

Ohne MQTT kann homeESS zwar starten, aber die eigentliche Funktion entsteht erst durch echte Messwerte und Steuer-Topics.

10. Erste sinnvolle Einrichtung

Nach der Grundinstallation sollte nicht direkt alles auf einmal eingerichtet werden. Sinnvoll ist diese Reihenfolge:

Schritt 1: Standort und Zeit setzen

Unter:

Einstellungen → Standort & Zeit

werden Breiten- und Längengrad, Zeitzone und automatische Zeitumstellung eingetragen.

Das ist wichtig für das PV-Clear-Sky-Modell. homeESS berechnet damit, welcher PV-Ertrag bei klarem Himmel theoretisch zu erwarten wäre.

Schritt 2: Stromverbrauch einrichten

Unter Stromverbrauch werden die MQTT-Topics für Netzbezug, Einspeisung und Verbrauch eingetragen.

Je nach vorhandener Hardware kommen diese Werte zum Beispiel aus:

• Smart Meter
• Wechselrichter
• ioBroker
• Modbus
• MQTT-Geräten

Schritt 3: Photovoltaik-Anlagen anlegen

Danach werden die PV-Anlagen eingerichtet.

Pro Anlage werden unter anderem hinterlegt:

• Name der Anlage
• Leistung
• MQTT-Topic für aktuelle Leistung
• Zelltyp
• Regler- oder Konvertertyp
• Ausrichtung und weitere Metadaten, soweit vorhanden

homeESS kann daraus aktuelle Leistung, Idealwert, Sonnenintensität und Prognosewerte ableiten. Die PV-Prognose nutzt Open-Meteo und benötigt keinen API-Key.

Schritt 4: Batterie konfigurieren

Unter Batterie werden die MQTT-Topics und Eckdaten des Hausakkus eingetragen.

Typische Werte sind:

• SoC
• Lade-/Entladeleistung
• Spannung
• Temperatur
• Kapazität
• Lade- und Entladewirkungsgrad
• Mindest-SoC

Die Batterie ist das zentrale Element von homeESS. Aus PV-Prognose, Verbrauch und Batteriestand entsteht später die eigentliche Energieplanung.

Schritt 5: Verbraucher unter „Messen + Schalten“ anlegen

Unter:

Messen + Schalten

werden schaltbare oder messbare Geräte angelegt.

Beispiele:

• Spülmaschine
• Waschmaschine
• Heizstab
• Poolpumpe
• Luftentfeuchter
• Ladegerät
• sonstige flexible Verbraucher

Pro Gerät können MQTT-Topics für Schalten, Status, Leistung, Zähler und Remote hinterlegt werden. Geräte können Gruppen und Prioritäten bekommen. Dadurch kann homeESS später entscheiden, welche Verbraucher bei welchem Betriebslevel laufen dürfen.

11. Optionale Module aktivieren

Über die Modulverwaltung können zusätzliche Bereiche aktiviert werden.

Mögliche Module sind zum Beispiel:

• Grid-Control
• Poolsteuerung
• Wallbox
• Adapter
• Modbus-TCP

Aktive Module erscheinen automatisch in der Sidebar. Nicht benötigte Bereiche bleiben ausgeblendet.

12. homeESS neu starten

Nach größeren Änderungen oder Updates kann der Dienst neu gestartet werden:

sudo systemctl restart home-ess

Als root:

systemctl restart home-ess

Den Status danach prüfen:

systemctl status home-ess

13. Logs ansehen, wenn etwas nicht funktioniert

Wenn die Oberfläche nicht erreichbar ist oder Werte nicht korrekt erscheinen, zuerst das Log prüfen:

journalctl -u home-ess -f

Häufige Ursachen sind:

• falsche MQTT-Adresse
• falscher MQTT-Port
• nicht erreichbarer Broker
• falsche Zugangsdaten
• Tippfehler in MQTT-Topics
• Gerät sendet keine Werte
• Firewall blockiert Port 3000
• Dienst läuft nicht

14. Manuelle Installation für Entwickler

Wer homeESS nicht über das Installationsskript installieren möchte, kann es auch manuell starten.

Im Projektverzeichnis:

npm ci
npm start

Für Entwicklung mit automatischem Neustart:

npm run dev

Dann läuft homeESS lokal unter:

http://localhost:3000

Diese Variante ist eher für Entwicklung und Tests gedacht. Für den normalen Dauerbetrieb ist die automatische Installation mit systemd-Service sinnvoller.

15. Wichtige Service-Befehle

Status prüfen:

systemctl status home-ess

Dienst neu starten:

systemctl restart home-ess

Live-Log anzeigen:

journalctl -u home-ess -f

Dienst stoppen:

systemctl stop home-ess

Dienst starten:

systemctl start home-ess

16. Zusammenfassung

Die Installation von homeESS ist bewusst einfach gehalten. Auf einem frischen Debian-System reicht im Normalfall ein einziger Installationsbefehl. Danach ist die Weboberfläche unter Port 3000 erreichbar.

Die eigentliche Arbeit beginnt anschließend in der Konfiguration: MQTT verbinden, PV-Anlagen anlegen, Batterie einrichten, Verbraucher erfassen und bei Bedarf Module wie Wallbox, Poolsteuerung, Grid-Control oder Modbus aktivieren.

homeESS ist damit keine starre Fertiglösung, sondern eine offene Plattform für individuelles Energiemanagement im eigenen Smarthome.