Docker

Diese Anleitung beschreibt die Installation von evcc als Docker-Image. Images gibt es für AMD64, armv6 und arm64. Oft kommen hier NAS-Systeme wie Synology, QNAP, Unraid und TrueNAS zum Einsatz.

Wichtig

Diese Anleitung setzt grundlegende Erfahrung mit Docker voraus.

Solltest du noch nicht mit Docker gearbeitet haben und einen einfachen Weg suchen, empfehlen wir stattdessen ein eigenes Gerät, z. B. einen Raspberry Pi mit dem fertigen Image.

Sind deine Geräte nicht über Netzwerk erreichbar (z. B. RS485-Adapter), solltest du eine direkte Installation ohne Docker wählen, z. B. unter Linux. Es gibt technische Lösungen, dies mit Docker umzusetzen. Diese werden hier allerdings nicht behandelt.

Netzwerkmodus

Bevor du den Container erstellst, musst du entscheiden, wie er mit deinem Netzwerk verbunden wird. Wir empfehlen das Host-Netzwerk. Der Container teilt sich dann das Netzwerk mit dem Host und verhält sich wie ein direkt installiertes Programm. Das hat mehrere Vorteile:

• Beim Hinzufügen eines Geräts schlägt das Feld IP Adresse oder Hostname die in deinem Netzwerk gefundenen Geräte vor.
• Funktionen auf Basis von mDNS funktionieren, z. B. EEBus, der SMA Sunny Home Manager und die automatische Erkennung durch die evcc App.
• Geräte, die über UDP kommunizieren, z. B. KEBA Wallboxen und SMA Geräte, sind ohne weitere Einrichtung erreichbar.
• Es muss keine Portliste gepflegt werden. Eingehende Verbindungen wie OCPP-Wallboxen funktionieren sofort.

Im Bridge-Netzwerk läuft der Container in einem separaten Docker-Netzwerk. Das ist in Ordnung, wenn du die oben genannten Funktionen nicht brauchst oder den Container bewusst isolieren möchtest. Alle benötigten Ports musst du dann selbst freigeben. Geräte in deinem Netzwerk werden nicht vorgeschlagen, ihre Adressen trägst du von Hand ein.

Das Host-Netzwerk setzt einen Linux-Host voraus, dazu zählen auch die gängigen NAS-Systeme. Mit Docker Desktop unter macOS und Windows läuft der Container in einer virtuellen Maschine ohne direkten Zugriff auf dein Netzwerk. Nutze dort stattdessen die Installation für macOS oder Windows.

Das Verzeichnis einbinden, nicht die Datenbankdatei

Binde immer das Verzeichnis /root/.evcc ein — niemals eine einzelne evcc.db Datei. evcc legt die SQLite Datenbank zusammen mit ihren Begleitdateien (evcc.db-wal und evcc.db-shm) in diesem Verzeichnis ab, und alle müssen gemeinsam erhalten bleiben.

Ein Named Volume (docker volume create evcc, dann evcc:/root/.evcc einbinden) ist die robusteste Wahl: Es hält die Dateien zusammen und liegt auf dem nativen Dateisystem des Hosts, das die von SQLite benötigte Dateisperrung bereitstellt. Lege die Datenbank nicht auf einer Netzwerkfreigabe (NFS/SMB) ab und — bei Docker Desktop für macOS/Windows — nicht auf einem Bind Mount, da dies die SQLite-Sperrung beeinträchtigen kann.

Installation

Der Container lässt sich über Docker Compose, die Docker CLI oder die Docker UI deines Systems einrichten. Alle drei Wege verwenden dasselbe Image und dieselben Volumes.

Es gibt zwei Image-Tags: evcc/evcc:latest (empfohlen) und evcc/evcc:nightly (Entwickler-Build).

Volumes

Host-Pfad	Container-Pfad	Beschreibung	Erforderlich
/home/user/.evcc	/root/.evcc	Verzeichnis für die Datenbank	ja
/home/user/evcc.yaml	/etc/evcc.yaml	Konfigurationsdatei (nur wenn du eine verwendest)	nein

Die Datenbank enthält deine Ladevorgänge und alles, was du in der Weboberfläche einrichtest. Lege das Verzeichnis vor dem ersten Start auf deinem Host-System an. Diese Anleitung verwendet exemplarisch /home/user/.evcc.

Das Volume für die evcc.yaml wird nur benötigt, wenn du deine Instanz über eine Konfigurationsdatei statt über die Weboberfläche einrichtest. Entferne die Zeile aus den folgenden Beispielen, wenn du keine verwendest.

Docker Compose

Docker Compose ist der empfohlene Weg, da alle Parameter in einer Datei hinterlegt sind. Lege eine Datei mit dem Namen compose.yml und einer der folgenden Konfigurationen an:

Host-Netzwerk (empfohlen)

services:
  evcc:
    container_name: evcc
    image: evcc/evcc:latest
    network_mode: host
    volumes:
      - /home/user/.evcc:/root/.evcc
      - /home/user/evcc.yaml:/etc/evcc.yaml # optional
    restart: unless-stopped

Bridge-Netzwerk

services:
  evcc:
    container_name: evcc
    image: evcc/evcc:latest
    ports:
      - 7070:7070/tcp
      - 8887:8887/tcp
    volumes:
      - /home/user/.evcc:/root/.evcc
      - /home/user/evcc.yaml:/etc/evcc.yaml # optional
    restart: unless-stopped

Dieses Beispiel gibt nur die Weboberfläche und den OCPP-Server frei. Füge bei Bedarf weitere Ports hinzu.

Starte den Container mit:

sudo docker compose up -d

Ob du sudo benötigst, hängt von deinem System ab.

Docker CLI

Alternativ erstellst und startest du den Container mit einem einzelnen Befehl:

Host-Netzwerk (empfohlen)

sudo docker run -d --name evcc \
  --network host \
  -v /home/user/.evcc:/root/.evcc \
  -v /home/user/evcc.yaml:/etc/evcc.yaml \
  --restart unless-stopped \
  evcc/evcc:latest

Bridge-Netzwerk

sudo docker run -d --name evcc \
  -p 7070:7070 \
  -p 8887:8887 \
  -v /home/user/.evcc:/root/.evcc \
  -v /home/user/evcc.yaml:/etc/evcc.yaml \
  --restart unless-stopped \
  evcc/evcc:latest

Dieses Beispiel gibt nur die Weboberfläche und den OCPP-Server frei. Füge bei Bedarf weitere Ports hinzu.

Docker UI

Hat dein System eine Docker UI (z. B. Synology, QNAP, Portainer, Unraid), kannst du den Container dort erstellen. Trage das Image und die Volumes von oben ein und setze den Netzwerkmodus auf host. Wenn du stattdessen das Bridge-Netzwerk wählst, füge die benötigten Ports hinzu.

Die genauen Feldbezeichnungen sind von System zu System unterschiedlich. Die Konzepte Netzwerkmodus, Ports und Volumes findest du aber in allen Systemen wieder.

Ports

Ports müssen nur im Bridge-Netzwerk freigegeben werden. Im Host-Netzwerk sind diese Ports direkt auf dem Host verfügbar.

Host-Port	Container-Port	Beschreibung	Erforderlich
7070	7070/tcp	Web UI, API	ja
8887	8887/tcp	OCPP-Server	nein
9522	9522/udp	SMA Sunny Home Manager	nein
7090	7090/udp	KEBA Wallboxen	nein
28376	28376/udp	EVSE Master Wallboxen	nein
5353	5353/udp	mDNS	nein
4712	4712/tcp	EEBus	nein
8899	8899/udp	Modbus UDP	nein

Testen

Nach dem Start des Containers erreichst du die Weboberfläche unter http://<host>:7070. <host> ist die IP-Adresse oder der Hostname des Computers, auf dem der Container läuft.

Bei der ersten Verwendung wirst du aufgefordert, ein Administrations-Passwort zu setzen. Danach kannst du deine Geräte einrichten, wie unter Einrichtung beschrieben.

Solltest du keine Verbindung herstellen können, überprüfe die Logs deines Containers. Weitere Hilfe findest du in den GitHub Diskussionen.

Aktualisierung

Docker Compose

Navigiere in das Verzeichnis mit der compose.yml und lade das neueste Image:

sudo docker compose pull

Falls ein neues Image vorhanden ist, erstellt der folgende Befehl den Container neu. Ansonsten läuft der bestehende einfach weiter.

sudo docker compose up -d

Docker CLI

Lade das neueste Image, stoppe und lösche dann den bestehenden Container:

sudo docker pull evcc/evcc:latest
sudo docker stop evcc
sudo docker rm evcc

Starte den Container anschließend mit demselben docker run Befehl wie bei der Installation.

Docker UI

Der Aktualisierungsprozess hängt von der jeweiligen Docker UI ab. Schaue dafür in die Dokumentation deines Systems.

Hinweis

Sollten nach einer Aktualisierung deine Ladevorgänge nicht mehr angezeigt werden, ist das Verzeichnis /root/.evcc nicht korrekt gemountet.

Community-Anleitungen

Hier findest du von Nutzern erstellte Anleitungen für konkrete Systeme. Für die Richtigkeit und Aktualität können wir nicht garantieren.

Beiträge sind willkommen

Aktualisierungen oder Anleitungen für weitere Systeme sind jederzeit willkommen. Egal ob als PDF, eigener Blog-Artikel oder YouTube Video. Erstelle gerne einen Pull Request im Doku Repository.

Synology NAS

Die Einrichtung über Docker auf einem Synology NAS ist über dessen grafische Benutzeroberfläche ohne Verwendung der Kommandozeile möglich. Diese Anleitung verwendet den empfohlenen Host-Modus: Anleitung: Synology Docker (PDF)

Eine Anleitung für den Bridge-Modus findest du hier: Anleitung: Synology Docker 2 (PDF) von at4hawo1

QNAP NAS

Die Einrichtung auf einem QNAP NAS über die Container Station ähnelt der obigen Synology-Anleitung. QNAP-spezifische Hinweise findest du hier: Anleitung: QNAP (PDF)

Statische Gerätevorschläge

Dies ist eine Option für Fortgeschrittene in kontrollierten Docker-Umgebungen, in denen das Bridge-Netzwerk gewollt ist und die Geräte feststehen. Die Umgebungsvariable EVCC_DISCOVERY_HOSTS stellt eine statische Liste von Geräten bereit. Diese Liste wird dann für die Vorschläge im Feld IP Adresse oder Hostname verwendet, statt das Netzwerk zu durchsuchen.

Der Wert ist eine JSON-Liste. Jeder Eintrag benötigt eine ip. hostname und mac sind optional. Sie werden verwendet, um den Hersteller anzuzeigen und Geräte, die zum gewählten Gerätetyp passen, unter Passend aufzuführen.

services:
  evcc:
    environment:
      EVCC_DISCOVERY_HOSTS: >-
        [
          {"ip": "192.168.1.10", "hostname": "sma3009876543", "mac": "00:15:BB:12:34:56"},
          {"ip": "192.168.1.20", "hostname": "go-echarger_123456"}
        ]

Eine leere Liste [] schaltet die Vorschläge ab.