Inanis_Vault/21-Server Reference/pihole/stacks/home_assistant.md

Home Assistant

Self-hosted home automation platform. The primary reason this Pi exists.

Access

• Tailscale: homeassistant.bunny-wyvern.ts.net
• LAN: http://[pi-ip]:8123 (port exposed but access via Tailscale preferred)

Containers

Container	Image	Role
homeassistant	lscr.io/linuxserver/homeassistant:latest	Home automation hub
homeassistant-tailscale-sidecar	tailscale/tailscale:latest	Tailscale node

Compose File

Path: /home/artanis/Desktop/HomeAssistant/docker-compose.yaml (on the Pi)

Note: Dockhand reports the stack dir as /DockerFiles/home_assistant/ — this is the path as seen from inside the Hawser agent context. The actual host path is via ~/Desktop/HomeAssistant/.

services:
  homeassistant:
    image: lscr.io/linuxserver/homeassistant:latest
    container_name: homeassistant
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ: America/Chicago
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - /home/artanis/Desktop/HomeAssistant/config:/config
      - /run/dbus:/run/dbus:ro
      - /home/artanis/Desktop/HomeAssistant/media:/media
    ports:
      - 8123:8123
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped

  homeassistant-tailscale-sidecar:
    image: tailscale/tailscale:latest
    container_name: homeassistant-tailscale-sidecar
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    volumes:
      - homeassistant_tailscale_state:/var/lib/tailscale
    environment:
      - TS_AUTHKEY=<redacted>
      - TS_HOSTNAME=homeassistant
      - TS_STATE_DIR=/var/lib/tailscale
    network_mode: "service:homeassistant"

volumes:
  homeassistant_tailscale_state:

# matter-server is defined but commented out

Data Layout

Path	Contents
/home/artanis/Desktop/HomeAssistant/config	HA configuration, automations, integrations
/home/artanis/Desktop/HomeAssistant/media	Media files for HA
/run/dbus	Host D-Bus socket (read-only, for Bluetooth)

Hardware Devices

Device	Purpose
/dev/ttyUSB0	USB serial device — likely a Zigbee or Z-Wave stick

Notes

• network_mode: host — Home Assistant runs on the Pi's full host network. This is required for mDNS/Bonjour device discovery, Bluetooth, and multicast protocols that don't work through Docker's bridge NAT
• cap_add: NET_ADMIN, NET_RAW — required for network-level features (e.g. ping, ARP for device tracking)
• /run/dbus is mounted read-only for Bluetooth integration via D-Bus
• Matter server is fully defined in the compose file but commented out — can be enabled when needed
• There is an orphaned volume homeassistant_homeassistant_tailscale_state from an earlier stack iteration (project was named homeassistant instead of home_assistant)