Support Tessera Docker Deployment on a Separate Host

Environment

Home Assistant OS running on a standalone device. In my case, a Pi4 2GB RAM. Tessera running in Docker on a separate host. Home Assistant and Tessera are on the same local network. Tessera configured with SCREEN_DEV=1.

Problem

Tessera's Docker deployment instructions assume it runs alongside Home Assistant on the same host. When running Tessera on a separate Docker host, the Home Assistant ingress integration returned 502 Bad Gateway.

With SCREEN_DEV=1, Tessera listens on 127.0.0.1:8099 and restricts requests to loopback. Publishing the container port directly does not work because Docker-forwarded requests are rejected. Setting SCREEN_DEV to 0 or removing it prevented the container from starting correctly and connecting to Home Assistant.

Working Solution

Keep SCREEN_DEV=1 enabled. Publish port 8100 on the Tessera container's network namespace. Run a lightweight socat proxy container sharing Tessera's network namespace using Docker's --network container: option.

sudo docker run -d \
  --name tessera-proxy \
  --restart unless-stopped \
  --network container:esp-screens \
  alpine/socat \
  TCP-LISTEN:8100,bind=0.0.0.0,fork,reuseaddr \
  TCP:127.0.0.1:8099

Configure the proxy to listen on 0.0.0.0:8100 and forward requests to 127.0.0.1:8099. Configure the Home Assistant hass_ingress integration to use the Docker host's LAN address and port 8100.

This allows Home Assistant to access Tessera over the LAN while preserving Tessera's loopback-only development mode. The proxy was created separately because the CasaOS Docker management interface's Compose importer removed the required network_mode: "service:" setting.

The interface initially displayed a white screen in Microsoft Edge, but eventually loaded and became usable as a Home Assistant sidebar tab.

Suggested Improvement

Document an officially supported deployment method for Tessera running on a separate Docker host from Home Assistant, including a supported proxy or configurable bind address that preserves appropriate security restrictions. Also document troubleshooting steps for Home Assistant ingress and blank embedded pages.