Docker

evcc can be installed as a Docker image. 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 and are looking for an easy way, we recommend a dedicated device instead, e.g. a Raspberry Pi with the ready-made image.

If your devices are not accessible via network (e.g. RS485 adapters) you should choose a direct installation without Docker, e.g. under Linux. There are technical solutions to implement this with Docker. However, these are not covered here.

Network Mode

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:

• 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.

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 yourself. Devices in your network are not suggested, so you enter their addresses manually.

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 or Windows installation there instead.

Mount the directory, not the database file

Always mount the /root/.evcc directory — never a single evcc.db file. evcc keeps the SQLite database together with its sidecar files (evcc.db-wal and evcc.db-shm) in this directory, and all of them have to persist together.

A named volume (docker volume create evcc, then mount evcc:/root/.evcc) is the most robust choice: it keeps the files together and lives on the host’s native filesystem, which provides the file locking SQLite needs. Avoid placing the database on a network share (NFS/SMB) or — on Docker Desktop for macOS/Windows — on a bind mount, as these can break SQLite locking.

Installation

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.

Two image tags are available: evcc/evcc:latest (recommended) and evcc/evcc:nightly (development build).

Volumes

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

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.

The evcc.yaml volume is only needed if you configure your instance via a configuration file instead of the web interface. Remove the line from the examples below if you don’t use one.

Docker Compose

Docker 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:

Host network (recommended)

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 network

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

This example only publishes the web interface and the OCPP server. Add further ports as needed.

Start the container with:

sudo docker compose up -d

Whether you need sudo depends on your system.

Docker CLI

Alternatively, create and start the container with a single command:

Host network (recommended)

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 network

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 as needed.

Docker 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 from above and set the network mode to host. If you choose bridge networking instead, add the 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

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

After starting the container, you can access the web interface at http://<host>:7070. <host> is the IP address or hostname of the computer running the container.

On first use you are prompted to set an administration password. After that you can set up your devices as described in Configuration.

If you cannot establish a connection, check your container logs. You can find further help in the GitHub Discussions.

Updates

Docker Compose

Navigate to the directory containing the compose.yml file and pull the latest image:

sudo docker compose pull

If a new image is available, the following command recreates the container. Otherwise, the existing one continues running.

sudo docker compose up -d

Docker CLI

Pull the latest image, then stop and remove the existing container:

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

Start the container again with the same docker run command as during installation.

Docker UI

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 that they are accurate or up to date.

Contributions welcome

Updates or guides for additional systems are always welcome. Whether as PDF, personal blog article, or YouTube video. Feel free to create a pull request in the Documentation Repository.

Synology NAS

You can install evcc via Docker on Synology NAS systems using its graphical interface, without using the command line. This guide uses the recommended host mode: Anleitung: Synology Docker (PDF / DE)

A guide for bridge mode can be found here: Anleitung: Synology Docker 2 (PDF / DE) by at4hawo1

QNAP NAS

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)

Static Device Suggestions

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.

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.