From 79a84a4c77b26eb391bdbe3636d182a6395361ec Mon Sep 17 00:00:00 2001 From: Max Gramser Date: Tue, 15 Sep 2026 19:01:39 +0200 Subject: [PATCH] Run ESP Screen Manager in Docker next to Home Assistant Container (docs only) For Home Assistant Container users without the App store: docker/compose.yaml builds the same app image from main and runs it with the existing SCREEN_DEV settings, so the page only listens on 127.0.0.1 and Home Assistant (hass_ingress) or an SSH tunnel gives access. docs/DOCKER.md covers the token, the sidebar panel, USB, backups and updates; the README links to it. The ESPHome folder mounts at /config because the ESPHome image keeps its CLI in /esphome, and the healthcheck checks the page instead of the ESPHome dashboard. No app or firmware change, so no version bump. Co-Authored-By: Claude Opus 5 --- README.md | 2 + docker/compose.yaml | 36 ++++++++++++++++ docs/DOCKER.md | 103 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+) create mode 100644 docker/compose.yaml create mode 100644 docs/DOCKER.md diff --git a/README.md b/README.md index 8f7af66..8b04173 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,8 @@ are generated per new screen and stay in that device's own profile. ### Step by step +For Home Assistant Container (Docker) without the App store, follow [ESP Screens with Docker](docs/DOCKER.md). + For Home Assistant OS with Apps/Add-ons on **aarch64 or amd64**: 1. Open the App store and add this repository: diff --git a/docker/compose.yaml b/docker/compose.yaml new file mode 100644 index 0000000..034c8de --- /dev/null +++ b/docker/compose.yaml @@ -0,0 +1,36 @@ +# ESP Screen Manager for Home Assistant Container (Docker), without the Supervisor. +# Guide: https://github.com/MaxGramser/homeassistant_espscreen/blob/main/docs/DOCKER.md +# +# Next to this file, create `ha_token` with a long-lived access token, then: +# docker compose up -d --build + +services: + esp-screens: + container_name: esp-screens + build: + # The same image as the Home Assistant app, built from the main branch. + context: https://github.com/MaxGramser/homeassistant_espscreen.git#main:screen_manager + restart: unless-stopped + # Home Assistant reaches the page on 127.0.0.1:8099, and .local names resolve. + network_mode: host + environment: + SCREEN_DEV: "1" # outside the Supervisor: token from HA_TOKEN_FILE, page on 127.0.0.1 only + HA_API: http://127.0.0.1:8123/api # Home Assistant's address, ending in /api + HA_TOKEN_FILE: /run/secrets/ha_token + ESPHOME_CONFIG: /config # not /esphome: that holds the ESPHome CLI itself + SCREEN_DATA: /data + secrets: + - ha_token + volumes: + - ./esphome:/config # device profiles and secrets.yaml; or your ESPHome Device Builder folder + - ./data:/data # layouts, update settings and build caches + healthcheck: + # The base image checks the ESPHome dashboard, which doesn't run here. + test: ["CMD", "curl", "--fail", "--silent", "--output", "/dev/null", "http://127.0.0.1:8099/"] + # USB flashing (Linux only): connect the screen first, then uncomment and set its port. + # devices: + # - /dev/ttyUSB0:/dev/ttyUSB0 + +secrets: + ha_token: + file: ./ha_token diff --git a/docs/DOCKER.md b/docs/DOCKER.md new file mode 100644 index 0000000..c9772da --- /dev/null +++ b/docs/DOCKER.md @@ -0,0 +1,103 @@ +# ESP Screens with Home Assistant Container (Docker) + +Home Assistant Container has no App store, so ESP Screen Manager can't be installed as an +app there. This guide runs the same app as its own container next to Home Assistant, with +the ESPHome CLI included. On Home Assistant OS, follow the +[normal installation](../README.md#installing-from-home-assistant) instead. + +This route is new. If something doesn't work on your setup, please +[open an issue](https://github.com/MaxGramser/homeassistant_espscreen/issues). + +## What you need + +- Home Assistant Container on a Linux host (aarch64 or amd64) with host networking, + as in the Home Assistant installation docs. +- Docker with Compose on the same host. +- The ESPHome integration in Home Assistant, to pair the screens. ESPHome Device Builder + is optional: the ESPHome CLI is already in this image. + +## Install + +1. Create a folder, for example `esp-screens`, and put + [`docker/compose.yaml`](../docker/compose.yaml) in it. +2. In Home Assistant, open your profile → **Security** → **Long-lived access tokens** and + create a token, signed in as an administrator. Save only the token in a file named + `ha_token` next to `compose.yaml`, readable for you only (`chmod 600 ha_token`). +3. Check two lines in `compose.yaml`: + - `HA_API`: `http://127.0.0.1:8123/api` works when Home Assistant runs on the same host + on port 8123. Keep `/api` at the end. + - The ESPHome folder: `./esphome` works as is. Already using ESPHome Device Builder? + Use its folder instead, so both see the same device profiles. +4. Start it: + + ```sh + docker compose up -d --build + ``` + + The first build downloads the official ESPHome image. `docker compose logs -f` shows + `Home Assistant connected` once the token works. + +## Open ESP Screens + +The page has no login of its own, so it only listens on `127.0.0.1:8099` of the Docker +host. Don't make port 8099 reachable from your network without a login in front of it. + +**In the Home Assistant sidebar (recommended).** Install +[hass_ingress](https://github.com/lovelylain/hass_ingress) from HACS, add this to +`configuration.yaml`, and restart Home Assistant: + +```yaml +ingress: + esp_screens: + title: ESP Screens + icon: mdi:monitor-dashboard + require_admin: true + url: http://127.0.0.1:8099 +``` + +Home Assistant then handles the login, like the app panel on Home Assistant OS. + +**Through an SSH tunnel.** From your computer: + +```sh +ssh -L 8099:127.0.0.1:8099 you@docker-host +``` + +Then open `http://localhost:8099`. The **Open Devices & services** button only works in +the sidebar panel; here, open Home Assistant yourself. + +## Using it + +From here it works like the app: **Settings → New screen** installs a screen, you pair it +under **Settings → Devices & services** in Home Assistant, and then choose the tiles. See the +[installation guide](EASY_SETUP.md). + +- **USB (Linux only):** connect the screen, uncomment `devices:` in `compose.yaml` with its + port (`/dev/ttyUSB0` or `/dev/ttyACM0`), and run `docker compose up -d` again. Installs + over Wi-Fi (OTA) and the nightly updates need nothing extra. +- **Backups:** Home Assistant backups don't include this container. Keep a copy of + `data/screens.json` and `data/updates.json` (layouts and update settings) and of the + ESPHome folder. `data/build` and `data/platformio` are caches. +- **Claude:** **Install for Claude Code** is meant for the Claude Code app on Home Assistant + OS. Use **Download for claude.ai** instead. + +## Updating + +```sh +docker compose build --pull +docker compose up -d +``` + +This builds the latest version from `main`, the same one the App store offers. To stay on +one version, replace `main` in `compose.yaml` with a release tag, such as `screens-v0.2.49`. +After an update, ESP Screens shows per screen whether newer firmware is available, as usual. + +## Settings in compose.yaml + +| Setting | What it does | +| --- | --- | +| `SCREEN_DEV: "1"` | Runs the app outside the Supervisor: it reads the token from `HA_TOKEN_FILE` and only listens on 127.0.0.1 | +| `HA_API` | Home Assistant's address, ending in `/api` | +| `HA_TOKEN_FILE` | The token file inside the container (the `ha_token` secret) | +| `ESPHOME_CONFIG` | The ESPHome folder inside the container | +| `SCREEN_DATA` | Layouts, update settings, and build caches |