README.md

ESPHome-NonRoot

ESPHome docker container that supports non-root operation.

License

Licensed under the MIT License

Build

Code and Pipeline is on GitHub.
Docker image is published on Docker Hub.
Image is rebuilt weekly, or when a new ESPHome version is released, picking up the latest ESPHome release and upstream container updates.

Status

Release Notes

• Version 1.6:
  • Support tmpfs for optional /tmp volume, use /tmp instead of /cache/tmp for temp files.
  • Make /cache volume mount optional.
  • Replace locales-all package with locales to reduce image size.
• Version 1.5:
  • Using Python 3.13 base image.
• Version 1.4:
  • Removed custom handling for ESPHOME_VERBOSE enabling --verbose, PR merged.
• Version 1.3:
  • Added Dev Container Workspace that maps config and cache volumes.
• Version 1.2:
  • Delete temp directory contents and prune PIO cached content on startup.
  • Added Dev Container that can be used for ESPHome or PlatformIO debugging.
• Version 1.1:
  • Added daily actions job to trigger a build if the ESPHome version changed.
• Version 1.0:
  • Initial public release.

Usage

Configuration

• volumes :
  • /config : Volume mapping to project files.
  • /cache (Optional) : Volume mapping to runtime generated content.
  • /tmp (Optional) : Volume mapping for temp files.
• user (Optional) : Run the container under the specified user account.
  • Use the uid:gid notation, e.g. user: 1001:100.
    • Get the uid : sudo id -u nonroot.
    • Get the gid : sudo id -g nonroot.
  • Use an existing user or create a system account on the host.
    • adduser --no-create-home --disabled-password --system --group users nonroot.
  • Omitting the user option will run under default root account.
  • Make sure the container user has permissions to the mapped /config and /cache volumes.
    • sudo chown -R nonroot:users /data/esphome
    • sudo chmod -R ug=rwx,o=rx /data/esphome
• environment :
  • ESPHOME_VERBOSE (Optional) : Enables verbose log output, e.g. ESPHOME_VERBOSE=true.
  • ESPHOME_DASHBOARD_USE_PING (Optional) : Use ping instead of mDNS to test if nodes are up, e.g. ESPHOME_DASHBOARD_USE_PING=true.
  • TZ (Optional) : Sets the timezone, e.g. TZ=America/Los_Angeles, default is Etc/UTC.

Docker Compose Dashboard

services:
  esphome:
    image: docker.io/ptr727/esphome-nonroot:latest
    container_name: esphome-test
    restart: unless-stopped
    user: 1001:100
    environment:
      - TZ=America/Los_Angeles
      - ESPHOME_VERBOSE=true
      - ESPHOME_DASHBOARD_USE_PING=true
    network_mode: bridge
    ports:
      - 6052:6052
    volumes:
      - /data/esphome/config:/config
      - /data/esphome/cache:/cache
    tmpfs:
      - /tmp:size=1g,mode=1777

# Create nonroot user
adduser --no-create-home --disabled-password --system --group users nonroot
id nonroot
# uid=1001(nonroot) gid=100(users) groups=100(users)

# Prepare directories for use by nonroot:users
mkdir -p /data/esphome/config /data/esphome/cache
sudo chown -R nonroot:users /data/esphome
sudo chmod -R ug=rwx,o=rx /data/esphome

# Launch stack
docker compose --file ./Docker/Compose.yml up --detach

# Open browser: http://localhost:6052
# Attach shell: docker exec -it --user 1001:100 esphome-test /bin/bash

# Destroy stack
docker compose --file ./Docker/Compose.yml down --volumes

Docker Run Command

# esphome version
docker run --rm --pull always --name esphome-test -v /data/esphome/config:/config -v /data/esphome/cache:/cache ptr727/esphome-nonroot:latest esphome version

latest: Pulling from ptr727/esphome-nonroot
Digest: sha256:8f32848551446d0420390477fccb8c833d879b640b95533f443cb623882e9688
Status: Image is up to date for ptr727/esphome-nonroot:latest
Version: 2024.5.5

Docker Run Interactive Shell

# /bin/bash
docker run --rm --user 1001:100 -it --pull always --name esphome-test -v /data/esphome/config:/config -v /data/esphome/cache:/cache ptr727/esphome-nonroot:latest /bin/bash

latest: Pulling from ptr727/esphome-nonroot
Digest: sha256:8f32848551446d0420390477fccb8c833d879b640b95533f443cb623882e9688
Status: Image is up to date for ptr727/esphome-nonroot:latest
I have no name!@012d4b62d376:/config$ id
uid=1001 gid=100(users) groups=100(users)
I have no name!@012d4b62d376:/config$

Docker Compose with Static IP and Traefik

  esphome:
    image: docker.io/ptr727/esphome-nonroot:latest
    container_name: esphome
    hostname: esphome
    domainname: ${DOMAIN_NAME}
    restart: unless-stopped
    user: ${USER_NONROOT_ID}:${USERS_GROUP_ID}
    group_add:
      - ${DOCKER_GROUP_ID}
    security_opt: # Use with care
      - seccomp=unconfined
      - apparmor=unconfined
    environment:
      - TZ=${TZ}
      # - ESPHOME_VERBOSE=true
    volumes:
      - ${APPDATA_DIR}/esphome/config:/config
      - ${APPDATA_DIR}/esphome/cache:/cache
    tmpfs:
      - /tmp:size=1g,mode=1777
    networks:
      public_network:
        ipv4_address: ${ESPHOME_IP}
        mac_address: ${ESPHOME_MAC}
      local_network:
      stack_network:
    labels:
      - traefik.enable=true
      - traefik.http.routers.esphome.rule=HostRegexp(`^esphome${DOMAIN_REGEX}$$`)
      - traefik.http.services.esphome.loadbalancer.server.scheme=http
      - traefik.http.services.esphome.loadbalancer.server.port=6052

Use Case

• Running containers as non-privileged and as non-root is a docker best practice.
• The official ESPHome docker container does not support running as a non-root user.
  • Issue #3558 : Docker requires root.
  • Issue #2752 : Docker image does not allow running rootless.
  • Issue #3929 : Not possible to run docker esphome/esphome container - problem with platformio.
  • HA Community : Is there a way to run ESPhome in docker with custom UID and GID.
  • Etc.
• Issue analysis based on ESPHome 2024.5.5 (current version as of writing) Dockerfile:
  • PLATFORMIO_GLOBALLIB_DIR=/piolibs sets the PlatformIO globallib_dir option to /piolibs.
    • /piolibs is not mapped to an external volume.
    • /piolibs has default permissions and requires root write permissions at runtime.
    • The globallib_dir option has been deprecated.
      • This option is DEPRECATED. We do not recommend using global libraries for new projects. Please use a declarative approach for the safety-critical embedded development and declare project dependencies using the lib_deps option.
  • platformio_install_deps.py installs global libraries using pio pkg install -g, the -g option has been deprecated.
    • We DO NOT recommend installing libraries in the global storage. Please use the lib_deps option and declare library dependencies per project.
  • The presence of a /cache directory changes pio_cache_base to /cache/platformio, the default is /config/.esphome/platformio
    • PLATFORMIO_PLATFORMS_DIR="${pio_cache_base}/platforms", PLATFORMIO_PACKAGES_DIR="${pio_cache_base}/packages", and PLATFORMIO_CACHE_DIR="${pio_cache_base}/cache" is explicitly set as child directories of pio_cache_base.
    • It is simpler to set PLATFORMIO_CORE_DIR PlatformIO core_dir option, and not setting PLATFORMIO_PLATFORMS_DIR platforms_dir, PLATFORMIO_PACKAGES_DIR packages_dir, and PLATFORMIO_CACHE_DIR cache_dir options, that are by default child directories of core_dir.
  • The presence of a /build directory sets the ESPHOME_BUILD_PATH environment variable, that sets the CONF_BUILD_PATH ESPHome build_path option, the default is /config/.esphome/build.
    • The directory presence detection could override an explicitly set ESPHOME_BUILD_PATH option.
  • ESPHOME_DATA_DIR can be used to set the ESPHome data_dir intermediate build output directory, the default is /config/.esphome, or hardcoded to /data for the HA addon image.
  • PLATFORMIO_CORE_DIR PlatformIO core_dir option is not set and defaults to ~/.platformio.
  • PIP_CACHE_DIR is not set and defaults to ~/.cache/pip.
  • HOME (~) is not set and defaults to e.g. /home/[username] or / or /nonexistent that either does not exists or the executing user does not have write permissions.

Project Design

• Use Python docker base image simplifying use for Python in a container environment.
• Use a multi-stage build minimizing size and layer complexity of the final stage.
• Build wheel archives for the platform in the builder stage, and install the platform specific generated wheel packages in the final stage.
• Set appropriate PlatformIO and ESPHome environment variables to store projects in /config and dynamic and temporary content in /cache volumes.
• Refer to Dockerfile for container details.
• Refer to BuildDockerPush.yml and for pipeline details.

Debugging

The included Dev Container can be used for ESPHome Python or PlatformIO C++ debugging in VSCode.

Detailed debug setup details are beyond the scope of this project, refer to my ESPHome-Config project for slightly more complete debugging setup instructions.