Home Assistant

Home automation platform. Controls Zigbee devices via a ConBee II USB dongle, runs automations, and exposes a local dashboard for lights, sensors, and scenes.

Where it runs

• Host: Nexus (192.168.1.226)
• UI: http://192.168.1.226:8123
• Managed by: Komodo (despite host network mode — see note below)
• Compose file: homeassistant/docker-compose.yaml in homelab-docker repo
• Config volume: /mnt/server/containers/homeassistant/

Docker

Docker on Nexus is installed via snap. Always use docker compose (with a space), never docker-compose.

Key quirks

Home Assistant uses privileged: true and network_mode: host. This is required for mDNS/device discovery to work across the LAN. As a result:

• There is no port mapping in the compose file — port 8123 is exposed directly on the host network.
• The ConBee II Zigbee dongle is passed through via devices: /dev/ttyACM0:/dev/ttyACM0.
• There is no .env file — all configuration lives in YAML files inside the /mnt/server/containers/homeassistant/ config volume.

Current image pin (from compose file):

image: ghcr.io/home-assistant/home-assistant:2026.4.4

ConBee II (Zigbee Coordinator)

The ConBee II is a USB Zigbee coordinator that manages all Zigbee devices.

• Device path: /dev/ttyACM0 (also addressable by ID: /dev/serial/by-id/usb-dresden_elektronik_...)
• Always use a USB extension cable — the dongle must be on an extension to reduce RF interference from the host machine. Without it, Zigbee reliability degrades significantly.
• After moving or reseating the server: if HA reports it can't find the dongle, re-seat the extension cable and verify the device appears:

ssh matt@192.168.1.226 'ls /dev/ttyACM0'

Backup

• Config is included in the daily PBS snapshot of Nexus — no separate action needed for routine backups.
• Before a Renovate update, take a manual backup:

ssh matt@192.168.1.226 'tar czf ~/ha-backup-$(date +%Y%m%d).tgz /mnt/server/containers/homeassistant/'

Renovate Note

Renovate tracks the ghcr.io/home-assistant/home-assistant image tag and will open PRs for new releases. Home Assistant has breaking changes in nearly every major release. Before merging any Renovate PR:

1. Read the HA release notes for every version between the current pin and the target.
2. Take a manual config backup (command above).
3. Merge and monitor logs after the container restarts.

Troubleshooting

# Container logs
ssh matt@192.168.1.226 'docker logs homeassistant --tail 50'

# Restart (compose)
ssh matt@192.168.1.226 'cd /home/matt/repos/homelab-docker/homeassistant && docker compose restart'

# Manual redeploy (picks up image changes)
ssh matt@192.168.1.226 'cd /home/matt/repos/homelab-docker/homeassistant && docker compose up -d'

# Verify ConBee II is visible to the host
ssh matt@192.168.1.226 'ls /dev/ttyACM0'

Zigbee devices stopped responding

1. Check that the USB extension cable is firmly seated at both ends.
2. Verify the device node exists: ls /dev/ttyACM0
3. If the node is missing, re-seat the cable and check again. A reboot of Nexus is rarely needed but will re-enumerate USB if nothing else works.
4. After the dongle is confirmed present, restart the container and watch logs.

Dashboard

The Overview dashboard is a curated 4-view sections layout (Home / Security / Climate / System), created 2026-09-15, replacing the auto-generated one. Core cards only — no HACS frontend dependencies.

• Live config: /mnt/server/containers/homeassistant/.storage/lovelace (storage mode — editable in the HA UI).
• Versioned copy: homeassistant/lovelace-dashboard.json in the homelab-docker repo. See homeassistant/DASHBOARD.md there for how to sync UI edits back to git and how to restore.
• Revert to auto-generated: delete .storage/lovelace in the config dir and restart the container.