Docker

evcc can be installed as a Docker image. Currently, we provide Docker images for AMD64, armv6 and arm64. Common use cases include NAS systems like Synology, QNAP, Unraid and TrueNAS.

important

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 or macOS guide.

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

Preparation

Configuration

evcc can be configured in two ways:

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.

2. Configuration file (traditional method): Create an evcc.yaml file with your settings. Instructions can be found under 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

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.

Skip to the Testing section to verify the installation.

Updates

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.

via Docker CLI

Install and start the Docker container using one of the following commands. Whether you need sudo depends on your system.

Standard

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

SMA Devices and EEBus

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 4712:4712 \
--network host \
-v /etc/machine-id:/etc/machine-id \
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

The above example only uses basic ports. Please refer to the Ports section and add additional ports as needed.

via Docker Compose

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

Standard

services:
  evcc:
    command:
      - 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
    # optional:
    #user: <UID>:<GID>

SMA Devices and EEBus

services:
  evcc:
    command:
      - evcc
    container_name: evcc
    image: evcc/evcc:latest
    ports:
      - 7070:7070/tcp
      - 8887:8887/tcp
      - 9522:9522/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
    restart: unless-stopped
    # optional:
    #user: <UID>:<GID>

NOTE

The above example only uses basic ports. Please refer to the Ports section and add additional ports as needed.

Start the container with:

sudo docker compose up -d

Updates

Navigate to the directory containing the evcc compose.yml file.

Update to the latest evcc image:

sudo docker compose pull

If a new image is available, the following command will restart the container - otherwise, the existing one will continue running:

sudo docker-compose up -d

Testing

After successfully creating and starting your container, you can access the evcc Web UI at http://<host>:7070. <host> 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)

If you cannot establish a connection, check your container logs. If you see the interface but an error message is displayed, check:

• For file-based configuration: the settings in your evcc.yaml file
• For UI configuration: the device settings on the configuration page

You can find more details in Configuration or in the GitHub Discussions.

Community Guides

Here you'll find user-created guides for specific systems. We cannot guarantee their accuracy or currentness.

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. 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: Anleitung: Synology Docker (PDF / DE)

More information on Bridge Mode can be found here: Anleitung: Synology Docker 2 (PDF / DE) by 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: Anleitung: QNAP (PDF / DE)