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 <noreply@anthropic.com>

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:

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

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 |