From e74b2418ca8e1427309e24000f999cc9c68a9642 Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Sat, 3 Oct 2026 13:06:33 +0200 Subject: [PATCH 1/2] Docker: recommend host networking, document device suggestions --- .../docs/de/installation/configuration.mdx | 9 + .../docs/de/installation/considerations.mdx | 7 +- src/content/docs/de/installation/docker.mdx | 376 ++++++++---------- .../docs/en/installation/configuration.mdx | 9 + .../docs/en/installation/considerations.mdx | 7 +- src/content/docs/en/installation/docker.mdx | 337 ++++++++-------- 6 files changed, 372 insertions(+), 373 deletions(-) diff --git a/src/content/docs/de/installation/configuration.mdx b/src/content/docs/de/installation/configuration.mdx index dab65ea78..0bf607928 100644 --- a/src/content/docs/de/installation/configuration.mdx +++ b/src/content/docs/de/installation/configuration.mdx @@ -39,6 +39,15 @@ Im Konfigurationsbereich kannst du folgende Komponenten einrichten: Mindestens ein Zähler oder Ladepunkt muss konfiguriert sein, damit das System läuft. +Die meisten Geräte werden über ihre IP-Adresse oder ihren Hostnamen angesprochen. +Das Feld **IP Adresse oder Hostname** schlägt die in deinem Netzwerk gefundenen Geräte mit Adresse, Hostname und Hersteller vor. +Geräte, die zum gewählten Gerätetyp passen, stehen unter **Passend**, alle anderen unter **Weitere**. +Einträge, die von einem anderen Gerät **bereits verwendet** werden, sind markiert. +Passt genau ein Gerät, wird es automatisch eingetragen. +Du kannst eine Adresse jederzeit selbst eintippen. +Die Suche läuft nur lokal und nur, während du ein Gerät einrichtest. +In einem Docker-Container setzen die Vorschläge das [Host-Netzwerk](/de/installation/docker#network) voraus. + ### Integrationen Zusätzlich kannst du verschiedene Dienste und Protokolle einbinden: diff --git a/src/content/docs/de/installation/considerations.mdx b/src/content/docs/de/installation/considerations.mdx index acd312939..2efd4988e 100644 --- a/src/content/docs/de/installation/considerations.mdx +++ b/src/content/docs/de/installation/considerations.mdx @@ -61,9 +61,10 @@ Dies könnte z.B. ein Netzwerkspeicher (NAS) oder ein bestehendes System wie Hom Hier ist die Installation anspruchsvoller, da evcc dann auf eine virtuelle Maschine oder als Container laufen muss. Um hohe Stabilität zu gewährleisten, empfehlen wir sowohl evcc als auch die verwendeten Geräte (Wallbox, Solaranlage, Batterie, etc.) wo immer möglich mit Netzwerkkabel anzubinden. -Vor dem Start der Installation von evcc unter Debian oder Ubuntu gemäß der [Anleitung](/de/installation/linux) sollten alle benötigten IP-Adressen von Zählern, Solaranlagen, Speichern und Wallboxen bereitliegen. -Meist finden sich die IP-Adressen aller Geräte im Webinterface der DSL- oder Kabel-Router (z.B. Fritz!Box) aufgelistet. -Hilfreich ist es, diese Adressen dauerhaft zuzuweisen, damit sie sich auch über lange Zeit nicht verändern. +Zähler, Solaranlagen, Speicher und Wallboxen werden über ihre IP-Adresse angesprochen. +Bei der [Einrichtung](/de/installation/configuration) werden die in deinem Netzwerk gefundenen Geräte vorgeschlagen, du musst die Adressen also meist nicht nachschlagen. +Wird ein Gerät nicht gefunden, steht seine IP-Adresse meist im Webinterface des DSL- oder Kabel-Routers (z. B. Fritz!Box). +Hilfreich ist es, diese Adressen im Router dauerhaft zuzuweisen, damit sie sich auch über lange Zeit nicht verändern. ## Wallboxen diff --git a/src/content/docs/de/installation/docker.mdx b/src/content/docs/de/installation/docker.mdx index 3720fdc25..cb3f7fd0e 100644 --- a/src/content/docs/de/installation/docker.mdx +++ b/src/content/docs/de/installation/docker.mdx @@ -1,285 +1,235 @@ --- title: "Docker" -description: "Betreibe evcc als Docker-Container, z. B. auf einem NAS von Synology, QNAP, Unraid oder TrueNAS, mit einem docker-compose-Beispiel und Hinweisen zum Testen." +description: "Betreibe evcc als Docker-Container auf einem NAS oder Linux-Server mit Docker Compose und erfahre, warum das Host-Netzwerk empfohlen wird und welche Ports der Bridge-Modus braucht." sidebar: order: 4 --- import { Tabs, TabItem } from "@astrojs/starlight/components"; -Diese Anleitung beschreibt die Installation von evcc als Docker Image. -Aktuell stellen wir Docker Images für AMD64, armv6 und arm64 zur Verfügung. +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. :::caution[Wichtig] Diese Anleitung setzt grundlegende Erfahrung mit Docker voraus. -Solltest du noch nicht mit Docker gearbeitet haben, empfehlen wir eine direkte Installation wie in der [Linux](/de/installation/linux) oder [macOS](/de/installation/macos) Anleitung beschrieben -Sind deine Geräte nicht über Netzwerk erreichbar (bspw. RS485 Adapter) solltest du auch die direkte Installation wählen. +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](/de/installation/linux-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](/de/installation/linux). Es gibt technische Lösungen, dies mit Docker umzusetzen. Diese werden hier allerdings nicht behandelt. ::: -## Vorbereitung - -### Konfiguration - -evcc kann auf zwei Arten konfiguriert werden: - -1. **Weboberfläche** (empfohlen): Starte den Container ohne `evcc.yaml`. Nach dem Start richtest du evcc direkt im Browser ein. Die Konfiguration wird automatisch in der Datenbank gespeichert. - -2. **Konfigurationsdatei** (traditionelle Methode): Erstelle eine `evcc.yaml` Datei mit deinen Einstellungen. Eine Anleitung findest du unter [Einrichtung](/de/installation/configuration). +## Netzwerkmodus \{#network\} -### Volumes +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: -Der evcc Docker Container benötigt mindestens ein Volume: +- 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. -- `/root/.evcc/` Verzeichnis für die interne SQLite Datenbank (erforderlich). Die Datenbank wird automatisch in diesem Verzeichnis abgelegt. -- `/etc/evcc.yaml` für die Konfigurationsdatei (optional - nur bei dateibasierter Konfiguration) +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](#ports) musst du dann selbst freigeben. +Geräte in deinem Netzwerk werden nicht vorgeschlagen, ihre Adressen trägst du von Hand ein. -Erstelle das Datenbank-Verzeichnis auf deinem Host-System. -In dieser Anleitung verwenden wir exemplarisch den Pfad `/home/user/.evcc/`. -Falls du die dateibasierte Konfiguration nutzt, verwende zusätzlich `/home/user/evcc.yaml` +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](/de/installation/macos) oder [Windows](/de/installation/windows). ## Installation -In diesem Abschnitt werden drei Möglichkeiten zur Installation von evcc über Docker beschrieben. -Über eine Docker GUI, über die Docker CLI und über Docker Compose. +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. -### via Docker UI +Es gibt zwei Image-Tags: `evcc/evcc:latest` (empfohlen) und `evcc/evcc:nightly` (Entwickler-Build). -Hast du ein System mit einer Docker GUI (z. B. Synology, QNAP, Portainer, Unraid, ...) kannst du die Installation auch über diese Oberfläche vornehmen. -Hier sind die relevanten Angaben, die du eintragen musst: +### Volumes \{#volumes\} -#### Verfügbare Docker Images +| 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 | -- `evcc/evcc:latest` (empfohlen) -- `evcc/evcc:nightly` (Entwickler-Build) +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`. -#### Volume Mounts +Das Volume für die `evcc.yaml` wird nur benötigt, wenn du deine Instanz über eine [Konfigurationsdatei](/de/installation/configuration) statt über die Weboberfläche einrichtest. +Entferne die Zeile aus den folgenden Beispielen, wenn du keine verwendest. -| Host Pfad | Container Pfad | Beschreibung | Erfordert | -| ---------------------- | ---------------- | ---------------------------------------------------------- | --------- | -| `/home/user/evcc.yaml` | `/etc/evcc.yaml` | Konfigurationsdatei (nur bei dateibasierter Konfiguration) | nein | -| `/home/user/.evcc/` | `/root/.evcc` | Verzeichnis für interne Datenbank | ja | +### Docker Compose \{#compose\} -#### Ports - -| Host Port | Container Port | Beschreibung | Erfordert | -| --------- | -------------- | ---------------------- | --------- | -| 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 Chargers | nein | -| 5353 | 5353/udp | mDNS | nein | -| 4712 | 4712/tcp | EEBus | nein | -| 8899 | 8899/udp | Modbus UDP | nein | - -Öffne die Docker UI deines Systems und erstelle einen neuen Container mit den obigen Angaben und starte ihn. - -Die genauen Feldbezeichnungen sind von System zu System unterschiedlich. -Die Konzepte Ports und Volumes findest du aber in allen Systemen wieder. - -Springe zum Abschnitt [Testen](#test) und überprüfe die Installation. - -#### Aktualisierung - -Der Aktualisierungsprozess hängt von der jeweiligen Docker UI ab. -Schaue dafür in die Dokumentation deines Systems. - -:::note[Hinweis] -Sollten nach einer Aktualisierung bspw. deine Ladevorgänge nicht mehr angezeigt werden ist das `/root/.evcc` Verzeichnis nicht korrekt gemountet. -::: +[Docker Compose](https://docs.docker.com/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: -### via Docker CLI - -Installiere und starte den Docker Container mit einem der folgenden Befehle. -Ob du `sudo` benötigst, hängt von deinem System ab. - - - - -```sh -sudo docker run -d --name evcc \ --v /home/user/evcc.yaml:/etc/evcc.yaml \ # optional --v /home/user/.evcc:/root/.evcc \ --p 7070:7070 \ --p 8887:8887 \ -evcc/evcc:latest -``` - - - - -```sh -sudo docker run -d --name evcc \ --v /home/user/evcc.yaml:/etc/evcc.yaml \ --v /home/user/.evcc:/root/.evcc \ --p 7070:7070 \ --p 8887:8887 \ --p 9522:9522/udp \ --p 5353:5353/udp \ --p 4712:4712 \ ---network host \ --v /etc/machine-id:/etc/machine-id \ -# highlight-end -evcc/evcc:latest -``` - -Setze den Netzwerkmodus auf `host`. -Der SMA Sunny Home Manager benötigt eine eindeutige Geräte-ID. -Unter Linux kannst du `machine-id` in den Container mounten. -Alternativ kannst du in der `evcc.yaml` auch eine ID im `plant` Parameter hinterlegen. - ---- - - - - -:::note[Hinweis] -Die obige Konfiguration nutzt nur die grundlegenden Ports. -Füge bei Bedarf weitere Ports hinzu. -Details findest du im Abschnitt [Ports](#ports). -::: - -#### Aktualisierung - -Um auf eine neue Version von evcc zu aktualisieren, führe folgende Schritte durch. -Aktualisiere auf das neuste evcc Image: - -```sh -sudo docker pull evcc/evcc:latest -``` - -Stoppe den evcc Container: - -```sh -sudo docker stop evcc -``` - -Lösche den evcc Container: - -```sh -sudo docker rm evcc -``` - -Starte den evcc Container mit den gleichen Parametern wie beim ersten Start. - -```sh -sudo docker run [...] evcc/evcc:latest -``` - -Springe zum Abschnitt [Testen](#test) um zu prüfen, ob die Installation erfolgreich war. - -### via Docker Compose - -[docker-compose](https://docs.docker.com/compose) hat einige Vorteile gegenüber der direkten Ausführung in der Kommandozeile -Alle Parameter werden in einer Datei hinterlegt. -Zudem kannst du weitere Programme wie Traefik in Verbindung mit evcc konfigurieren und gemeinsam starten. -Im aktiven Verzeichnis legt man dazu einfach eine Konfigurationsdatei mit dem Namen `compose.yml` an. -Entsprechend der passenden Komponenten-Konstellation kopiert man eine der folgenden Konfigurationen in die `compose.yml` und speichert diese ab: - - - + + ```yaml -version: "3" services: evcc: - command: - - evcc container_name: evcc image: evcc/evcc:latest - ports: - - 7070:7070/tcp - - 8887:8887/tcp + network_mode: host volumes: - /home/user/.evcc:/root/.evcc - /home/user/evcc.yaml:/etc/evcc.yaml # optional restart: unless-stopped - # optional: - #user: : ``` - + ```yaml -version: "3" services: evcc: - command: - - evcc container_name: evcc image: evcc/evcc:latest ports: - 7070:7070/tcp - 8887:8887/tcp - - 9522:9522/udp - - 5353:5353/udp - - 4712:4712/tcp volumes: - - /home/user/evcc.yaml:/etc/evcc.yaml - /home/user/.evcc:/root/.evcc - - /etc/machine-id:/etc/machine-id - - /var/lib/dbus/machine-id:/var/lib/dbus/machine-id - network_mode: host + - /home/user/evcc.yaml:/etc/evcc.yaml # optional restart: unless-stopped - # optional: - #user: : ``` +Dieses Beispiel gibt nur die Weboberfläche und den OCPP-Server frei. +Füge bei Bedarf weitere [Ports](#ports) hinzu. + -:::note[Hinweis] -Die obige Konfiguration nutzt nur die grundlegenden Ports. -Füge bei Bedarf weitere Ports hinzu. -Details findest du im Abschnitt [Ports](#ports). -::: - Starte den Container mit: ```sh sudo docker compose up -d ``` -#### Aktualisierung +Ob du `sudo` benötigst, hängt von deinem System ab. -Navigiere in das Verzeichnis, das die `compose.yml` Datei von evcc enthält. +### Docker CLI \{#cli\} -Aktualisiere auf das neuste evcc Image: +Alternativ erstellst und startest du den Container mit einem einzelnen Befehl: + + + + +```sh +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 +``` + + + + +```sh +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](#ports) hinzu. + + + + +### Docker UI \{#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](#volumes) von oben ein und setze den Netzwerkmodus auf `host`. +Wenn du stattdessen das Bridge-Netzwerk wählst, füge die benötigten [Ports](#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\} + +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 \{#test\} + +Nach dem Start des Containers erreichst du die Weboberfläche unter `http://:7070`. +`` 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](/de/installation/configuration) beschrieben. + +Solltest du keine Verbindung herstellen können, überprüfe die [Logs deines Containers](/de/report-a-problem#system-logs). +Weitere Hilfe findest du in den [GitHub Diskussionen](https://github.com/evcc-io/evcc/discussions). + +## Aktualisierung \{#update\} + + + + +Navigiere in das Verzeichnis mit der `compose.yml` und lade das neueste Image: ```sh sudo docker compose pull ``` -Falls ein neues Image vorhanden ist, startet das folgende Kommando den Container neu - ansonsten läuft der Alte einfach weiter: +Falls ein neues Image vorhanden ist, erstellt der folgende Befehl den Container neu. +Ansonsten läuft der bestehende einfach weiter. ```sh sudo docker compose up -d ``` -## Testen \{#test\} + + -Hast du deinen Container erfolgreich erstellt und gestartet, kannst du die evcc Web UI unter `http://:7070` aufrufen. -`` ist hier die IP-Adresse oder der Hostname des Computers, auf dem der Container läuft. +Lade das neueste Image, stoppe und lösche dann den bestehenden Container: -**Bei der ersten Verwendung:** +```sh +sudo docker pull evcc/evcc:latest +sudo docker stop evcc +sudo docker rm evcc +``` -- Wirst du aufgefordert ein Administrations-Passwort zu setzen -- Kannst du anschließend deine Geräte über die Weboberfläche einrichten (bei UI-Konfiguration) -- Oder siehst direkt deine konfigurierten Geräte (bei dateibasierter Konfiguration) +Starte den Container anschließend mit demselben `docker run` Befehl wie bei der [Installation](#cli). -Solltest du keine Verbindung herstellen können, überprüfe die [Logs deines Containers](/de/report-a-problem#system-logs). -Wenn du die Oberfläche siehst, aber eine Fehlermeldung angezeigt wird, überprüfe: + + -- Bei dateibasierter Konfiguration: die Einstellungen in der `evcc.yaml` Datei -- Bei UI-Konfiguration: die Geräteeinstellungen auf der Konfigurationsseite +Der Aktualisierungsprozess hängt von der jeweiligen Docker UI ab. +Schaue dafür in die Dokumentation deines Systems. + + + -Weitere Details findest du in [Einrichtung](/de/installation/configuration) oder in den [GitHub Diskussionen](https://github.com/evcc-io/evcc/discussions). +:::note[Hinweis] +Sollten nach einer Aktualisierung deine Ladevorgänge nicht mehr angezeigt werden, ist das Verzeichnis `/root/.evcc` nicht korrekt gemountet. +::: -## Community Anleitungen +## 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. @@ -292,15 +242,39 @@ Erstelle gerne einen Pull Request im [Doku Repository](https://github.com/evcc-i ### Synology NAS -Die Einrichtung von evcc über Docker auf einem Synology NAS-System ist über dessen grafische Benutzeroberfläche ohne Verwendung der Kommandozeile möglich. -Hierbei sind zwei Netzwerkmodi wählbar: Host oder Bridge. Ob der Bridge-Modus anwendbar ist, hängt von den verwendeten Komponenten ab. -Im Zweifelsfall ist immer der Host-Mode zu wählen. Hier die Anleitung dazu: +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](#network): [Anleitung: Synology Docker (PDF)](https://github.com/evcc-io/docs/files/10365841/Anleitung.EVCC.Synology.Docker.Elli.Charger.Connect-Pro.pdf) -Für den Bridge-Mode ist nach dieser Anleitung zu verfahren: [Anleitung: Synology Docker 2 (PDF)](https://github.com/evcc-io/docs/files/10365845/EVCC_Synology_Docker-2.pdf) (erstellt von at4hawo1) +Eine Anleitung für den Bridge-Modus findest du hier: +[Anleitung: Synology Docker 2 (PDF)](https://github.com/evcc-io/docs/files/10365845/EVCC_Synology_Docker-2.pdf) von [at4hawo1](https://github.com/at4hawo1) ### QNAP NAS -Auch auf der QNAP NAS kann man über die Container Station evcc in einem Container laufen lassen. Ganz ohne Kommandozeile habe ich hier nicht gearbeitet. Wie auch bei der Synology ist es die Nutzung des Netzwerkmodus abhängig von den verwendeten Komponenten. Insbesondere beim SMA Sunny Home Manager 2.0 ist der "Host-Modus" zu wählen, um den Multicast zu joinen. -Hier die Anleitung für das Erstellen des Containers mit der QNAP NAS und der Container Station 2/3: +Die Einrichtung auf einem QNAP NAS über die Container Station ähnelt der obigen Synology-Anleitung. +QNAP-spezifische Hinweise findest du hier: [Anleitung: QNAP (PDF)](https://github.com/evcc-io/docs/files/11241693/EVCC_auf_QNAP_Container_Station.pdf) + +## Statische Gerätevorschläge \{#discovery\} + +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. + +```yaml +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. diff --git a/src/content/docs/en/installation/configuration.mdx b/src/content/docs/en/installation/configuration.mdx index da4d3e26e..8c9f7263f 100644 --- a/src/content/docs/en/installation/configuration.mdx +++ b/src/content/docs/en/installation/configuration.mdx @@ -39,6 +39,15 @@ In the configuration area, you can set up the following components: At least one meter or charging point must be configured for the system to run. +Most devices are addressed via their IP address or hostname. +The **IP address or hostname** field suggests the devices found in your network with their address, hostname and vendor. +Devices that fit the selected device type are listed under **Matching**, all others under **Other**. +Entries that are **already used** by another device are marked. +If exactly one device matches, it is filled in automatically. +You can always type an address yourself. +The search only runs locally while you configure a device. +In a Docker container the suggestions require [host networking](/en/installation/docker#network). + ### Integrations Additionally, you can integrate various services and protocols: diff --git a/src/content/docs/en/installation/considerations.mdx b/src/content/docs/en/installation/considerations.mdx index 2e9c2cb2d..6e995520b 100644 --- a/src/content/docs/en/installation/considerations.mdx +++ b/src/content/docs/en/installation/considerations.mdx @@ -61,9 +61,10 @@ This could be, for example, a network storage (NAS) or an existing system like H The installation is more demanding here, as evcc then has to run on a virtual machine or as a container. To ensure high stability, we recommend connecting both evcc and the devices used (charger, solar system, battery, etc.) with a network cable wherever possible. -Before starting the installation of evcc under Debian or Ubuntu according to the [instructions](/en/installation/linux), all required IP addresses of meters, solar systems, storage systems, and chargers should be available. -The IP addresses of all devices are usually listed in the web interface of the DSL or cable routers (e.g., Fritz!Box). -It is helpful to assign these addresses permanently so that they do not change over a long period of time. +Meters, solar systems, storage systems and chargers are addressed via their IP address. +During [setup](/en/installation/configuration) the devices found in your network are suggested, so you usually don't have to look the addresses up. +If a device is not found, its IP address is usually listed in the web interface of the DSL or cable router (e.g. Fritz!Box). +It is helpful to assign these addresses permanently in the router so that they do not change over time. ## EV Chargers diff --git a/src/content/docs/en/installation/docker.mdx b/src/content/docs/en/installation/docker.mdx index ad99e08b5..a8e5405c1 100644 --- a/src/content/docs/en/installation/docker.mdx +++ b/src/content/docs/en/installation/docker.mdx @@ -1,6 +1,6 @@ --- title: "Docker" -description: "Run evcc as a Docker container, e.g. on a Synology, QNAP, Unraid or TrueNAS NAS, with a docker compose example and notes on configuration and testing." +description: "Run evcc as a Docker container on a NAS or Linux server with Docker Compose, and see why host networking is recommended and which ports bridge mode needs." sidebar: order: 4 --- @@ -8,249 +8,231 @@ sidebar: import { Tabs, TabItem } from "@astrojs/starlight/components"; evcc can be installed as a Docker image. -Currently, we provide Docker images for AMD64, armv6 and arm64. +Images are available for AMD64, armv6 and arm64. Common use cases include NAS systems like Synology, QNAP, Unraid and TrueNAS. :::caution This guide assumes basic experience with Docker. -If you haven't worked with Docker before, we recommend a direct installation as described in the [Linux](/en/installation/linux) or [macOS](/en/installation/macos) guide. +If you haven't worked with Docker before and are looking for an easy way, we recommend a dedicated device instead, e.g. a Raspberry Pi with the [ready-made image](/en/installation/linux-image). -If your devices are not accessible via network (e.g. RS485 adapters) you should also choose the direct installation. +If your devices are not accessible via network (e.g. RS485 adapters) you should choose a direct installation without Docker, e.g. under [Linux](/en/installation/linux). There are technical solutions to implement this with Docker. However, these are not covered here. ::: -## Preparation +## Network Mode \{#network\} -### Configuration +Before you create the container you have to decide how it is connected to your network. +We recommend **host networking**. +The container then shares the network of the host and behaves like a directly installed program. +This has several benefits: -evcc can be configured in two ways: +- When you add a device, the **IP address or hostname** field suggests the devices found in your network. +- Features based on mDNS work, e.g. EEBus, the SMA Sunny Home Manager and automatic discovery by the evcc app. +- Devices that communicate via UDP, e.g. KEBA chargers and SMA devices, are reachable without further setup. +- There is no port list to maintain. Inbound connections like OCPP chargers work right away. -1. **Web interface** (recommended): Start the container without `evcc.yaml`. After starting, configure evcc directly in the browser. The configuration is automatically saved in the database. +With **bridge networking** the container runs in a separate Docker network. +This is fine if you don't need the features above or prefer to isolate the container. +You then have to publish every required [port](#ports) yourself. +Devices in your network are not suggested, so you enter their addresses manually. -2. **Configuration file** (traditional method): Create an `evcc.yaml` file with your settings. Instructions can be found under [Configuration](/en/installation/configuration). - -### Volumes - -The evcc Docker container needs at least one volume: - -- `/root/.evcc/` directory for the internal SQLite database (required). The database is automatically stored in this directory. -- `/etc/evcc.yaml` for the configuration file (optional - only for file-based configuration) - -Create the database directory on your host system. -In this guide we use the path `/home/user/.evcc/` as an example. -If you're using file-based configuration, also use `/home/user/evcc.yaml` +Host networking requires a Linux host, which includes the common NAS systems. +With Docker Desktop on macOS and Windows the container runs in a virtual machine without direct access to your network. +Use the [macOS](/en/installation/macos) or [Windows](/en/installation/windows) installation there instead. ## Installation -This section describes three ways to install evcc using Docker: -Via Docker UI, Docker CLI, and Docker Compose. - -### via a Docker UI - -If you have a system with a Docker UI (e.g. Synology, QNAP, Portainer, Unraid, ...), you can also perform the installation through this interface. -Here are the relevant details you need to enter: - -#### Available Docker Images - -- `evcc/evcc:latest` (recommended) -- `evcc/evcc:nightly` (development build) - -#### Volume Mounts - -| Host Path | Container Path | Description | Required | -| ---------------------- | ---------------- | ------------------------------------------------------ | -------- | -| `/home/user/evcc.yaml` | `/etc/evcc.yaml` | Configuration file (only for file-based configuration) | no | -| `/home/user/.evcc/` | `/root/.evcc` | Directory for internal database | yes | - -#### Ports - -| Host Port | Container Port | Description | Required | -| --------- | -------------- | ---------------------- | -------- | -| 7070 | 7070/tcp | Web UI, API | Yes | -| 8887 | 8887/tcp | OCPP Server | No | -| 9522 | 9522/udp | SMA Sunny Home Manager | No | -| 7090 | 7090/udp | KEBA Chargers | No | -| 5353 | 5353/udp | mDNS | No | -| 4712 | 4712/tcp | EEBus | No | -| 8899 | 8899/udp | Modbus UDP | No | - -Open your system's Docker UI and create a new container with the above settings and start it. - -The exact field labels vary from system to system. -However, you'll find the concepts of ports and volumes in all systems. +The container can be set up via Docker Compose, the Docker CLI or the Docker UI of your system. +All three use the same image and volumes. -Skip to the [Testing](#test) section to verify the installation. +Two image tags are available: `evcc/evcc:latest` (recommended) and `evcc/evcc:nightly` (development build). -#### Updates +### Volumes \{#volumes\} -The update process depends on your specific Docker UI. -Please refer to your system's documentation for this. - -:::note -If after an update your charging sessions are no longer displayed, the `/root/.evcc` directory is not mounted correctly. -::: +| Host Path | Container Path | Description | Required | +| ---------------------- | ---------------- | ---------------------------------------- | -------- | +| `/home/user/.evcc` | `/root/.evcc` | Directory for the database | yes | +| `/home/user/evcc.yaml` | `/etc/evcc.yaml` | Configuration file (only if you use one) | no | -### via Docker CLI +The database contains your charging sessions and everything you set up in the web interface. +Create the directory on your host system before the first start. +This guide uses `/home/user/.evcc` as an example. -Install and start the Docker container using one of the following commands. -Whether you need `sudo` depends on your system. +The `evcc.yaml` volume is only needed if you configure your instance via a [configuration file](/en/installation/configuration) instead of the web interface. +Remove the line from the examples below if you don't use one. - - +### Docker Compose \{#compose\} -```sh -sudo docker run -d --name evcc \ --v /home/user/evcc.yaml:/etc/evcc.yaml \ # optional --v /home/user/.evcc:/root/.evcc \ --p 7070:7070 \ --p 8887:8887 \ -evcc/evcc:latest -``` +[Docker Compose](https://docs.docker.com/compose) is the recommended way, because all parameters are stored in one file. +Create a file named `compose.yml` with one of the following configurations: - - - -```sh -sudo docker run -d --name evcc \ --v /home/user/evcc.yaml:/etc/evcc.yaml \ --v /home/user/.evcc:/root/.evcc \ --p 7070:7070 \ --p 8887:8887 \ --p 9522:9522/udp \ --p 5353:5353/udp \ --p 4712:4712 \ ---network host \ --v /etc/machine-id:/etc/machine-id \ -# highlight-end -evcc/evcc:latest -``` - -Set the network mode to `host`. -The SMA Sunny Home Manager requires a unique device ID. -On Linux, you can mount `machine-id` into the container. -Alternatively, you can specify an ID in the `plant` parameter in `evcc.yaml`. - ---- - - - - -:::note[NOTE] -The above example only uses basic ports. -Please refer to the [Ports](#ports) section and add additional ports as needed. -::: - -### via Docker Compose - -[docker-compose](https://docs.docker.com/compose) has several advantages over direct command line execution. -All parameters are stored in a file. -Additionally, you can configure and start other programs like Traefik in conjunction with evcc. -Simply create a configuration file named `compose.yml` in your active directory. -Copy one of the following configurations matching your component setup into `compose.yml` and save it: - - - + + ```yaml services: evcc: - command: - - evcc container_name: evcc image: evcc/evcc:latest - ports: - - 7070:7070/tcp - - 8887:8887/tcp + network_mode: host volumes: - /home/user/.evcc:/root/.evcc - /home/user/evcc.yaml:/etc/evcc.yaml # optional restart: unless-stopped - # optional: - #user: : ``` - + ```yaml services: evcc: - command: - - evcc container_name: evcc image: evcc/evcc:latest ports: - 7070:7070/tcp - 8887:8887/tcp - - 9522:9522/udp - - 5353:5353/udp - - 4712:4712/tcp volumes: - - /home/user/evcc.yaml:/etc/evcc.yaml - /home/user/.evcc:/root/.evcc - - /etc/machine-id:/etc/machine-id - - /var/lib/dbus/machine-id:/var/lib/dbus/machine-id - network_mode: host + - /home/user/evcc.yaml:/etc/evcc.yaml # optional restart: unless-stopped - # optional: - #user: : ``` +This example only publishes the web interface and the OCPP server. +Add further [ports](#ports) as needed. + -:::note[NOTE] -The above example only uses basic ports. -Please refer to the [Ports](#ports) section and add additional ports as needed. -::: - Start the container with: ```sh sudo docker compose up -d ``` -#### Updates +Whether you need `sudo` depends on your system. + +### Docker CLI \{#cli\} -Navigate to the directory containing the evcc `compose.yml` file. +Alternatively, create and start the container with a single command: -Update to the latest evcc image: + + ```sh -sudo docker compose pull +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 ``` -If a new image is available, the following command will restart the container - otherwise, the existing one will continue running: + + ```sh -sudo docker compose up -d +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 ``` +This example only publishes the web interface and the OCPP server. +Add further [ports](#ports) as needed. + + + + +### Docker UI \{#ui\} + +If your system has a Docker UI (e.g. Synology, QNAP, Portainer, Unraid), you can create the container there. +Enter the image and the [volumes](#volumes) from above and set the network mode to `host`. +If you choose bridge networking instead, add the [ports](#ports) you need. + +The exact field labels vary from system to system. +However, you'll find the concepts of network mode, ports and volumes in all of them. + +## Ports \{#ports\} + +Publishing ports is only necessary with bridge networking. +With host networking these ports are available on the host directly. + +| Host Port | Container Port | Description | Required | +| --------- | -------------- | ---------------------- | -------- | +| 7070 | 7070/tcp | Web UI, API | yes | +| 8887 | 8887/tcp | OCPP server | no | +| 9522 | 9522/udp | SMA Sunny Home Manager | no | +| 7090 | 7090/udp | KEBA chargers | no | +| 28376 | 28376/udp | EVSE Master chargers | no | +| 5353 | 5353/udp | mDNS | no | +| 4712 | 4712/tcp | EEBus | no | +| 8899 | 8899/udp | Modbus UDP | no | + ## Testing \{#test\} -After successfully creating and starting your container, you can access the evcc Web UI at `http://:7070`. +After starting the container, you can access the web interface at `http://:7070`. `` is the IP address or hostname of the computer running the container. -**On first use:** - -- You will be prompted to set an administration password -- You can then configure your devices via the web interface (for UI configuration) -- Or see your configured devices directly (for file-based configuration) +On first use you are prompted to set an administration password. +After that you can set up your devices as described in [Configuration](/en/installation/configuration). If you cannot establish a connection, check your [container logs](/en/report-a-problem#system-logs). -If you see the interface but an error message is displayed, check: +You can find further help in the [GitHub Discussions](https://github.com/evcc-io/evcc/discussions). + +## Updates \{#update\} + + + + +Navigate to the directory containing the `compose.yml` file and pull the latest image: + +```sh +sudo docker compose pull +``` + +If a new image is available, the following command recreates the container. +Otherwise, the existing one continues running. + +```sh +sudo docker compose up -d +``` + + + + +Pull the latest image, then stop and remove the existing container: + +```sh +sudo docker pull evcc/evcc:latest +sudo docker stop evcc +sudo docker rm evcc +``` -- For file-based configuration: the settings in your `evcc.yaml` file -- For UI configuration: the device settings on the configuration page +Start the container again with the same `docker run` command as during [installation](#cli). -You can find more details in [Configuration](/en/installation/configuration) or in the [GitHub Discussions](https://github.com/evcc-io/evcc/discussions). + + + +The update process depends on your specific Docker UI. +Please refer to your system's documentation for this. + + + + +:::note +If your charging sessions are no longer displayed after an update, the `/root/.evcc` directory is not mounted correctly. +::: ## Community Guides Here you'll find user-created guides for specific systems. -We cannot guarantee their accuracy or currentness. +We cannot guarantee that they are accurate or up to date. :::tip[Contributions welcome] Updates or guides for additional systems are always welcome. @@ -261,15 +243,38 @@ Feel free to create a pull request in the [Documentation Repository](https://git ### Synology NAS You can install evcc via Docker on Synology NAS systems using its graphical interface, without using the command line. -You'll be given the choice of two network modes: bridge, or host. Whether the Bridge mode can be used depends on what components you're using, and how they communicate with your equipment. -In case of doubt, use host mode. Further information can be found in this instruction: +This guide uses the recommended [host mode](#network): [Anleitung: Synology Docker (PDF / DE)](https://github.com/evcc-io/docs/files/10365841/Anleitung.EVCC.Synology.Docker.Elli.Charger.Connect-Pro.pdf) -More information on Bridge Mode can be found here: +A guide for bridge mode can be found here: [Anleitung: Synology Docker 2 (PDF / DE)](https://github.com/evcc-io/docs/files/10365845/EVCC_Synology_Docker-2.pdf) by [at4hawo1](https://github.com/at4hawo1) ### QNAP NAS -Installing evcc on QNAP systems via Docker is very similar to the above Synology instructions. -Further QNAP specific instructions can be found here: +Installing evcc on QNAP systems via Container Station is very similar to the Synology instructions above. +QNAP specific instructions can be found here: [Anleitung: QNAP (PDF / DE)](https://github.com/evcc-io/docs/files/11241693/EVCC_auf_QNAP_Container_Station.pdf) + +## Static Device Suggestions \{#discovery\} + +This is an advanced option for controlled Docker environments where bridge networking is intended and the devices are fixed. +The environment variable `EVCC_DISCOVERY_HOSTS` provides a static list of devices. +This list is then used for the suggestions in the **IP address or hostname** field instead of searching the network. + +The value is a JSON list. +Each entry needs an `ip`. +`hostname` and `mac` are optional. +They are used to show the vendor and to list devices that fit the selected device type under **Matching**. + +```yaml +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"} + ] +``` + +An empty list `[]` turns the suggestions off. From 6b4f2c76f68b9e274bc284de06d7875fef11583e Mon Sep 17 00:00:00 2001 From: Michael Geers Date: Sat, 3 Oct 2026 15:20:47 +0200 Subject: [PATCH 2/2] Device suggestions: limited to own network segment --- src/content/docs/de/installation/configuration.mdx | 4 +++- src/content/docs/en/installation/configuration.mdx | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/docs/de/installation/configuration.mdx b/src/content/docs/de/installation/configuration.mdx index 0bf607928..00e93533a 100644 --- a/src/content/docs/de/installation/configuration.mdx +++ b/src/content/docs/de/installation/configuration.mdx @@ -46,7 +46,9 @@ Einträge, die von einem anderen Gerät **bereits verwendet** werden, sind marki Passt genau ein Gerät, wird es automatisch eingetragen. Du kannst eine Adresse jederzeit selbst eintippen. Die Suche läuft nur lokal und nur, während du ein Gerät einrichtest. -In einem Docker-Container setzen die Vorschläge das [Host-Netzwerk](/de/installation/docker#network) voraus. +Sie findet nur Geräte im selben Netzwerksegment wie deine evcc Instanz. +Geräte in anderen VLANs oder Subnetzen werden nicht gefunden. +In einem Docker-Container ist dafür das [Host-Netzwerk](/de/installation/docker#network) (alternativ macvlan) nötig, im Bridge-Modus sieht der Container das lokale Netzwerk nicht. ### Integrationen diff --git a/src/content/docs/en/installation/configuration.mdx b/src/content/docs/en/installation/configuration.mdx index 8c9f7263f..96183a06b 100644 --- a/src/content/docs/en/installation/configuration.mdx +++ b/src/content/docs/en/installation/configuration.mdx @@ -46,7 +46,9 @@ Entries that are **already used** by another device are marked. If exactly one device matches, it is filled in automatically. You can always type an address yourself. The search only runs locally while you configure a device. -In a Docker container the suggestions require [host networking](/en/installation/docker#network). +It only finds devices in the same network segment as your evcc instance. +Devices in other VLANs or subnets are not found. +In a Docker container this requires [host networking](/en/installation/docker#network) (alternatively macvlan), because in bridge mode the container doesn't see the local network. ### Integrations