Home Automation Infrastructure – Full Technical Documentation

Proxmox VE 8 • Home Assistant OS • Docker Stack • Raspberry Pi 5 Services

This document describes the complete home automation environment, including all installation steps, configuration details, and troubleshooting actions required to get the system fully operational. It is formatted for GitHub Gist.

1. Network Overview

Device / Service	IP Address	Description
Proxmox VE 8 Host	<LAN_IP_PROXMOX>	Hypervisor running HA VM + Docker stack
Home Assistant OS VM	<LAN_IP_HAS>	Main home automation platform
Raspberry Pi 5	<LAN_IP_PI5>	Frigate, Pi‑hole, Unbound, NPM
Docker Containers (Proxmox)	Docker internal network	Mosquitto, Zigbee2MQTT, Node‑RED

2. Proxmox VE 8 Installation

Proxmox VE 8 was installed following Derek Seaman’s guide (2023). Key steps:

Install Proxmox VE 8 from ISO
Configure static IP: <LAN_IP_PROXMOX>
Enable no‑subscription repository
Update system
Configure storage (ZFS or LVM)
Apply recommended VM settings for Home Assistant OS

3. Home Assistant OS VM (HAS)

Home Assistant OS was deployed as a KVM VM using the QCOW2 image.

VM Configuration

UEFI (Secure Boot disabled)
VirtIO SCSI
2–4 vCPUs
4–8 GB RAM
32–64 GB disk
Bridged networking (vmbr0)
Static DHCP lease: <LAN_IP_HAS>

Restoring Home Assistant Backup

After first boot:

Open HA onboarding page
Select Restore from Backup
Upload .tar snapshot
System restores all add‑ons, integrations, dashboards, and settings

4. Docker Stack on Proxmox Host

A dedicated directory was created:

/opt/ha-stack

Docker and Docker Compose were installed on Proxmox.

Directory Structure

/opt/ha-stack/
 ├── docker-compose.yml
 ├── mosquitto/
 │    ├── config/
 │    │     ├── mosquitto.conf
 │    │     └── passwd
 │    ├── data/
 │    └── log/
 ├── zigbee2mqtt/
 │    └── data/
 └── nodered/

5. Zigbee USB Adapter – Persistent Alias

To avoid device renaming issues, a persistent alias was created.

Identify the adapter

ls -l /dev/serial/by-id

Example output:

usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_1234-if00-port0

Create udev rule

sudo nano /etc/udev/rules.d/99-zigbee.rules

Add:

SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", SYMLINK+="zigbee"

Reload rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Now the adapter is always available as:

/dev/zigbee

6. Docker Compose Stack

docker-compose.yml

version: "3.9"

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: always
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    container_name: zigbee2mqtt
    restart: always
    volumes:
      - ./zigbee2mqtt/data:/app/data
    devices:
      - /dev/zigbee:/dev/zigbee
    depends_on:
      - mosquitto

  nodered:
    image: nodered/node-red:4.1.6
    container_name: nodered
    restart: always
    ports:
      - "1880:1880"
    volumes:
      - ./nodered:/data
    depends_on:
      - mosquitto

Start stack:

docker compose up -d

7. Mosquitto MQTT Broker

mosquitto.conf

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

Creating MQTT Users

Enter container:

docker exec -it mosquitto sh

Create users:

mosquitto_passwd -c /mosquitto/config/passwd ha
mosquitto_passwd /mosquitto/config/passwd zigbee
mosquitto_passwd /mosquitto/config/passwd nodered
mosquitto_passwd /mosquitto/config/passwd frigate

Fixing Permission Errors (Critical Step)

Mosquitto runs as user 1883, but the passwd file was owned by root:

-rw------- 1 root root passwd

This caused:

Mosquitto restart loop
Zigbee2MQTT restart loop
Home Assistant “Failed to connect”

Fix:

sudo chown 1883:1883 /opt/ha-stack/mosquitto/config/passwd
sudo chmod 640 /opt/ha-stack/mosquitto/config/passwd

Restart:

docker compose restart mosquitto

8. Zigbee2MQTT Configuration

zigbee2mqtt/data/configuration.yaml:

mqtt:
  server: mqtt://mosquitto
  user: zigbee
  password: YOUR_PASSWORD

serial:
  port: /dev/zigbee
  adapter: ezsp

Restart:

docker compose restart zigbee2mqtt

9. Node‑RED Configuration

Open:

http://<LAN_IP_PROXMOX>:1880

Install Home Assistant WebSocket nodes:

node-red-contrib-home-assistant-websocket

Configure MQTT server:

Server: mosquitto or <LAN_IP_PROXMOX>
Port: 1883
Username: nodered
Password: your password

Test flow:

MQTT In → topic zigbee2mqtt/bridge/state
Debug node

10. Home Assistant MQTT Integration

In HA:

Settings → Integrations → MQTT
Broker: <LAN_IP_PROXMOX>
Port: 1883
Username: ha
Password: your password

HA now auto‑discovers Zigbee2MQTT devices.

11. Raspberry Pi 5 Services (<LAN_IP_PI5>)

Frigate NVR

config.yml:

mqtt:
  host: <LAN_IP_PROXMOX>
  port: 1883
  user: frigate
  password: YOUR_PASSWORD
  topic_prefix: frigate

Restart:

sudo systemctl restart frigate

Pi‑hole + Unbound

Pi‑hole forwards DNS to Unbound
Unbound provides recursive DNS
Pi‑hole acts as network‑wide ad blocker

Nginx Proxy Manager

Reverse proxy for:
- Home Assistant
- Node‑RED
- Zigbee2MQTT
- Frigate

12. Troubleshooting Summary (All Issues Encountered)

Mosquitto restart loop

Cause:

passwd file owned by root
unreadable by mosquitto user

Fix:

chown 1883:1883 passwd
chmod 640 passwd

Zigbee2MQTT restart loop

Cause:

Mosquitto unavailable
Wrong serial port
Missing /dev/zigbee alias

Fix:

Create udev rule
Use /dev/zigbee
Fix Mosquitto permissions

Home Assistant “Failed to connect”

Cause:

Mosquitto not running
Wrong credentials
Wrong broker IP

Fix:

Use <LAN_IP_PROXMOX>
Use user ha

Node‑RED not connecting

Cause:

Wrong MQTT credentials
Wrong broker hostname

Fix:

Use nodered user
Use mosquitto or <LAN_IP_PROXMOX>

Frigate not publishing events

Cause:

No MQTT user
Wrong broker IP

Fix:

Create frigate user
Set host to <LAN_IP_PROXMOX>

13. Final System Architecture

                     ┌──────────────────────────────┐
                     │        Proxmox VE 8           │
                     │      <LAN_IP_PROXMOX>         │
                     └──────────────┬───────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
┌──────────────┐          ┌────────────────┐          ┌────────────────────┐
│ Home Assistant│          │ Docker Stack   │          │ Raspberry Pi 5      │
│ OS VM         │          │ (Mosquitto,    │          │ Frigate, Pi‑hole,   │
│<LAN_IP_HAS>   │          │ Z2M, Node‑RED) │          │ Unbound, NPM        │
└──────┬────────┘          └───────┬────────┘          └─────────┬──────────┘
       │                            │                               │
       │ MQTT (ha user)             │ MQTT (zigbee/nodered users)   │ MQTT (frigate user)
       │                            │                               │
       ▼                            ▼                               ▼
┌──────────────┐        ┌────────────────┐              ┌────────────────────┐
│ Home Assistant│◄──────► Mosquitto MQTT │◄────────────► Frigate NVR         │
│ Integrations  │        │ Broker         │              │ Pi‑hole / Unbound  │
└──────────────┘        └────────────────┘              │ Nginx Proxy Manager│
                                                         └────────────────────┘

thimslugga/README.md

Select an option

No results found

Select an option

No results found

Home Automation Infrastructure – Full Technical Documentation

1. Network Overview

2. Proxmox VE 8 Installation

3. Home Assistant OS VM (HAS)

VM Configuration

Restoring Home Assistant Backup

4. Docker Stack on Proxmox Host

Directory Structure

5. Zigbee USB Adapter – Persistent Alias

Identify the adapter

Create udev rule

6. Docker Compose Stack

docker-compose.yml

7. Mosquitto MQTT Broker

mosquitto.conf

Creating MQTT Users

Fixing Permission Errors (Critical Step)

8. Zigbee2MQTT Configuration

9. Node‑RED Configuration

10. Home Assistant MQTT Integration

11. Raspberry Pi 5 Services (<LAN_IP_PI5>)

Frigate NVR

Pi‑hole + Unbound

Nginx Proxy Manager

12. Troubleshooting Summary (All Issues Encountered)

Mosquitto restart loop

Zigbee2MQTT restart loop

Home Assistant “Failed to connect”

Node‑RED not connecting

Frigate not publishing events

13. Final System Architecture