EOS/docs/develop/install.md

% SPDX-License-Identifier: Apache-2.0 (install-page)=

Installation Guide

This guide provides different methods to install Akkudoktor-EOS:

• Installation from Source (GitHub) (M1)
• Installation from Release Package (GitHub) (M2)
• Installation with Docker (DockerHub) (M3)
• Installation with Docker (docker-compose) (M4)
• Installation in Home Assistant (M5)

Choose the method that best suits your needs.

:::{admonition} Tip :class: Note If you need to update instead, see the Update Guideline. For reverting to a previous release see the Revert Guideline. :::

Installation Prerequisites

Before installing, ensure you have the following:

For Source / Release Installation (M1/M2)

• Python 3.11+
• uv (recommended)
• Git (only for source)
• Tar/Zip (for release package)

For Docker Installation (M3/M4)

• Docker Engine 20.10 or higher
• Docker Compose (optional, recommended)

:::{admonition} Tip :class: Note See Install Docker Engine on how to install docker on your Linux distro. :::

For Installation in Home Assistant (M5)

• Home Assistant Operating System

:::{admonition} Warning :class: Warning Akkudoktor-EOS is a Home Assistant add-on. Home Assistant Container installations don’t have access to add-ons. :::

Install uv (one-time setup)

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        irm https://astral.sh/uv/install.ps1 | iex

  .. tab:: Linux

     .. code-block:: bash

        curl -LsSf https://astral.sh/uv/install.sh | sh

Installation from Source (GitHub) (M1)

Recommended for developers or users wanting the latest updates.

1) Clone the Repository (M1)

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        git clone https://github.com/Akkudoktor-EOS/EOS.git
        cd EOS

  .. tab:: Linux

     .. code-block:: bash

        git clone https://github.com/Akkudoktor-EOS/EOS.git
        cd EOS

2) Create a Virtual Environment and install dependencies (M1)

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        uv sync --extra dev

  .. tab:: Linux

     .. code-block:: bash

        uv sync --extra dev

3) Run EOS (M1)

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        uv run python -m akkudoktoreos.server.eos

  .. tab:: Linux

     .. code-block:: bash

        uv run python -m akkudoktoreos.server.eos

EOS is now available at:

• API: http://localhost:8503/docs
• EOSdash: http://localhost:8504

If you want to make EOS and EOSdash accessible from outside of your machine or container at this stage of the installation provide appropriate IP addresses on startup.

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        uv run python -m akkudoktoreos.server.eos --host 0.0.0.0 --eosdash-host 0.0.0.0

  .. tab:: Linux

     .. code-block:: bash

        uv run python -m akkudoktoreos.server.eos --host 0.0.0.0 --eosdash-host 0.0.0.0

4) Configure EOS (M1)

Use EOSdash at http://localhost:8504 to configure EOS.

Installation from Release Package (GitHub) (M2)

This method is recommended for users who want a stable, tested version.

1) Download the Latest Release (M2)

Visit the Releases page and download the latest release package (e.g., akkudoktoreos-v0.2.0.tar.gz or akkudoktoreos-v0.2.0.zip).

2) Extract the Package (M2)

tar -xzf akkudoktoreos-v0.2.0.tar.gz  # For .tar.gz
# or
unzip akkudoktoreos-v0.2.0.zip  # For .zip

cd akkudoktoreos-v0.2.0

3) Create a virtual environment and run and configure EOS (M2)

Follow Step 2), 3) and 4) of method M1. Start at 2) Create a Virtual Environment and install dependencies

4) Update the source code (M2)

To extract a new release to a new directory just proceed with method M2 step 1) for the new release.

You may remove the old release directory afterwards.

Installation with Docker (DockerHub) (M3)

This method is recommended for easy deployment and containerized environments.

1) Pull the Docker Image (M3)

docker pull akkudoktor/eos:latest

For a specific version:

docker pull akkudoktor/eos:v<version>

2) Run the Container (M3)

Basic run:

docker run -d \
  --name akkudoktoreos \
  -p 8503:8503 \
  -p 8504:8504 \
  -e OPENBLAS_NUM_THREADS=1 \
  -e OMP_NUM_THREADS=1 \
  -e MKL_NUM_THREADS=1 \
  -e EOS_SERVER__HOST=0.0.0.0 \
  -e EOS_SERVER__PORT=8503 \
  -e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
  -e EOS_SERVER__EOSDASH_PORT=8504 \
  --ulimit nproc=65535:65535 \
  --ulimit nofile=65535:65535 \
  --security-opt seccomp=unconfined \
  akkudoktor/eos:latest

3) Verify the Container is Running (M3)

docker ps
docker logs akkudoktoreos

EOS should now be accessible at http://localhost:8503/docs and EOSdash should be available at http://localhost:8504.

4) Configure EOS (M3)

Use EOSdash at http://localhost:8504 to configure EOS. In the dashboard, go to:

Config

Installation with Docker (docker-compose) (M4)

1) Get the akkudoktoreos source code (M4)

You may use either method M1 or method M2 to get the source code.

2) Build and run the container (M4)

.. tabs::

  .. tab:: Windows

     .. code-block:: powershell

        docker compose up --build

  .. tab:: Linux

     .. code-block:: bash

        docker compose up --build

3) Verify the Container is Running (M4)

docker ps
docker logs akkudoktoreos

EOS should now be accessible at http://localhost:8503/docs and EOSdash should be available at http://localhost:8504.

The configuration file is in ${HOME}/.local/share/net.akkudoktor.eos/config/EOS.config.json.

4) Configure EOS (M4)

Use EOSdash at http://localhost:8504 to configure EOS. In the dashboard, go to:

Config

You may edit the configuration file directly at ${HOME}/.local/share/net.akkudoktor.eos/config/EOS.config.json.

Installation in Home Assistant (M5)

1) Add the repository URL (M5)

In Home Assistant, go to:

Settings → Add-ons → Add-on Store → ⋮ (top-right menu) → Repositories

and enter the URL of this Git repository:

https://github.com/Akkudoktor-EOS/EOS

2) Install the add-on (M5)

After adding the repository, the add-on will appear in the Add-on Store. Click Install.

3) Start the add-on (M5)

Once installed, click Start in the add-on panel.

4) Access the dashboard (M5)

Click Open Web UI in the add-on panel.

5) Configure EOS (M5)

In the dashboard, go to:

Config

Helpful Docker Commands

View logs

docker logs -f akkudoktoreos

Stop the container

docker stop akkudoktoreos

Start the container

docker start akkudoktoreos

Remove the container

docker rm -f akkudoktoreos

Update to latest version

docker pull Akkudoktor-EOS/EOS:latest
docker stop akkudoktoreos
docker rm akkudoktoreos
# Then run the container again with the run command

Solve docker DNS not working

Switch Docker to use the real resolv.conf, not the stub.

1️⃣ Replace /etc/resolv.conf symlink

sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf

This file contains the actual upstream DNS servers (e.g. your Fritz!Box).

2️⃣ Restart Docker

sudo systemctl restart docker

3️⃣ Verify

docker run --rm busybox nslookup registry-1.docker.io

You should now see a valid IP address.