ESPHome Device Builder mit Docker einrichten¶
Veröffentlicht am 2. August 2026 · Geschätzte Lesezeit: 5 Minuten
Mit dem ESPHome Device Builder erstellst und verwaltest du Firmware für ESP32- und ESP8266-Geräte über eine Weboberfläche. Die Konfiguration wird in YAML-Dateien gespeichert, daraus wird die Firmware gebaut und später drahtlos aktualisiert. Für Installation und ein erstes Testgerät solltest du etwa 30 bis 45 Minuten einplanen.
Die Anleitung wurde am 2. August 2026 mit der offiziellen ESPHome-Dokumentation und den Sicherheitsempfehlungen abgeglichen. Das Video ESPHome Basics for Beginners zeigt den grundsätzlichen Ablauf zusätzlich.
Voraussetzungen
- Ein Linux-Server mit installiertem Docker und Docker Compose
- Ein unterstütztes ESP32- oder ESP8266-Gerät
- Ein USB-Datenkabel für die erste Installation
- Ein Computer mit Chrome oder Edge für das erste Flashen per WebSerial
1. Arbeitsordner anlegen¶
Erstelle auf dem Docker-Server einen Ordner für ESPHome und seine Konfigurationen:
Wechsle anschließend in diesen Ordner:
Der Unterordner config enthält später Geräte-YAML-Dateien, Schlüssel, WLAN-Zugangsdaten und erzeugte Firmware. Behandle ihn deshalb wie einen Passwortspeicher.
2. Zugangsdaten für die Oberfläche vorbereiten¶
Erstelle eine Umgebungsdatei:
Füge die folgenden Zeilen ein. Ersetze <esphome-benutzer> durch einen eigenen Benutzernamen und <dashboard-passwort> durch ein langes, einzigartiges Passwort.
Speichere mit Strg+O, bestätige mit der Eingabetaste und beende Nano mit Strg+X.
Beschränke danach die Leserechte der Datei auf deinen Linux-Benutzer:
Danger
Trage die echten Zugangsdaten niemals in eine veröffentlichte Anleitung oder ein öffentliches Git-Repository ein. Die Datei .env gehört ebenfalls in jedes Ausschlussmuster deiner Versionsverwaltung.
3. Compose-Datei erstellen¶
Öffne im Ordner ~/esphome eine neue Compose-Datei:
Füge diese Konfiguration ein:
services:
esphome:
image: ghcr.io/esphome/esphome:2026.7
container_name: esphome
restart: unless-stopped
network_mode: host
environment:
USERNAME: ${ESPHOME_USERNAME}
PASSWORD: ${ESPHOME_PASSWORD}
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
Speichere die Datei und beende den Editor.
Der Tag 2026.7 folgt innerhalb dieser geprüften ESPHome-Ausgabereihe den stabilen Korrekturversionen. network_mode: host ermöglicht die Geräteerkennung per mDNS. Diese Anleitung gibt dem Container absichtlich keinen pauschalen privilegierten Zugriff auf alle Geräte des Servers.
4. Device Builder starten¶
Starte den Container im Hintergrund:
Prüfe anschließend seinen Zustand:
Bei einem Fehler zeigen die letzten Protokollzeilen meist die Ursache:
5. Weboberfläche öffnen¶
Rufe auf einem Gerät im selben Netzwerk diese Adresse auf:
Ersetze <server-ip> durch die IP-Adresse deines Docker-Servers, zum Beispiel 192.168.178.50. Melde dich mit dem Benutzernamen und Passwort aus .env an.
Warning
Leite Port 6052 nicht im Router ins Internet weiter. Der Device Builder enthält WLAN-Zugangsdaten und Geräteschlüssel und gehört nur in ein vertrauenswürdiges Heimnetz oder hinter einen abgesicherten VPN-Zugang.
6. Erstes Gerät anlegen¶
Wähle in der Weboberfläche New Device Setup und vergib einen eindeutigen Namen, zum Beispiel test-sensor. Wähle anschließend den passenden Mikrocontroller und gib deine WLAN-Daten nur im Assistenten ein.
ESPHome legt geheime Werte in config/secrets.yaml ab. Prüfe nach dem Assistenten, ob die Konfiguration gültig ist, indem du beim Gerät das Menü und danach Validate auswählst.
Tip
Nutze für jedes Gerät einen eigenen API-Schlüssel und ein eigenes OTA-Passwort. ESPHome erzeugt diese Werte bei einer neuen Konfiguration normalerweise automatisch.
7. Erste Firmware sicher installieren¶
Wähle beim neuen Gerät Install und anschließend den manuellen Download. Lade die erzeugte Firmware auf deinen Computer herunter.
Öffne danach auf diesem Computer die offizielle Installationsseite:
Verbinde den ESP per USB-Datenkabel, klicke auf Connect, wähle den seriellen Anschluss und installiere die heruntergeladene Firmware. Nach dem Neustart sollte sich das Gerät mit deinem WLAN verbinden.
Spätere Änderungen lassen sich über Install drahtlos übertragen, sobald das Gerät im Dashboard als erreichbar angezeigt wird.
8. Home Assistant verbinden¶
Öffne in Home Assistant Einstellungen, danach Geräte & Dienste. Ein neues ESPHome-Gerät wird im selben Netzwerk häufig automatisch erkannt.
Falls nicht, füge die ESPHome-Integration manuell hinzu und trage die IP-Adresse des ESP-Geräts ein. Verwende den API-Verschlüsselungsschlüssel aus der Gerätekonfiguration, wenn Home Assistant danach fragt.
9. Backup und Rückweg vorbereiten¶
Stoppe ESPHome vor der vollständigen Sicherung:
Sichere den kompletten Projektordner einschließlich .env, secrets.yaml und Geräte-YAML-Dateien:
Starte den Dienst danach wieder:
Bewahre das Archiv verschlüsselt auf einem zweiten Datenträger auf. Für den Rückweg stoppst du den Container, stellst den vollständigen Ordner ~/esphome wieder her und startest ihn erneut. Eine bereits funktionierende Gerätefirmware läuft währenddessen weiter.
10. ESPHome kontrolliert aktualisieren¶
Erstelle zuerst ein Backup und lies die ESPHome-Änderungshinweise. Ändere danach in compose.yaml den Image-Tag auf die gewünschte geprüfte Ausgabereihe.
Lade das neue Abbild:
Erstelle den Container anschließend neu:
Validiere zunächst eine Gerätekonfiguration. Aktualisiere die Firmware nicht automatisch auf allen Geräten gleichzeitig, damit du bei einem Problem ein funktionierendes Vergleichsgerät behältst.
11. Typische Fehler beheben¶
Wenn die Weboberfläche nicht erreichbar ist, prüfe, ob Port 6052 bereits verwendet wird:
Wird ein Gerät nicht online angezeigt, kontrolliere Server und ESP-Gerät im selben Netzwerk sowie die mDNS-Erreichbarkeit. Prüfe außerdem die Containerprotokolle:
Schlägt die erste USB-Installation fehl, verwende ein nachweislich datenfähiges Kabel und probiere einen anderen USB-Anschluss am Computer.
Fertig¶
Der ESPHome Device Builder läuft jetzt geschützt auf deinem Docker-Server und speichert alle Gerätekonfigurationen dauerhaft. Die Einrichtung ist erfolgreich, wenn die Konfiguration gültig ist, das Testgerät online erscheint und seine Protokolle in der Weboberfläche abrufbar sind.