Home Assistant Setup Guide

Home Assistant Setup Guide

Introduction

Home Assistant is an open-source, local-first home automation platform designed to centralize control of smart devices across your network. It provides unified dashboards, complex automation capabilities, and integration support for thousands of protocols and platforms (including Zigbee, Z-Wave, MQTT, HomeKit, and cloud APIs).

⚠️ Containerized (Docker) vs HAOS Note: Running Home Assistant via Docker Compose uses Home Assistant Container. It does not include the Home Assistant Supervisor or Add-ons Store. External applications (like Mosquitto MQTT or Frigate) are run as separate, sidecar Docker containers in your stack rather than installed through the HA UI.

---

Step 1: Initial Container Deployment

1. Copy the homeassistant.yaml file into your active server compose directory:

cp compose/templates/homeassistant.yaml compose/server1/homeassistant.yaml

2. Ensure your root .env file contains your server configuration variables:

DOMAINNAME=yourdomain.com
HOST_NAME=server1
TZ=America/New_York
PUID=1000
PGID=100

3. Create the host directory for configuration files and logs:

sudo mkdir -p ${DOCKERDIR}/homeassistant/config ${DOCKERDIR}/logs/homeassistant

4. Launch the container:

docker compose -p mediaserver -f docker-compose-server1.yaml up -d homeassistant

⚠️ Network & Hardware Notice: Home Assistant uses network_mode: host to facilitate mDNS device discovery, UPnP, and local network scans. It also runs in privileged mode to allow direct access to attached hardware, such as USB Zigbee or Z-Wave dongles.

---

Step 2: Service Definition (homeassistant.yaml)

# ------------------------------------------------------------------------------
# Home Assistant - Smart Home Control Center
# ------------------------------------------------------------------------------
services:
  homeassistant:
    container_name: homeassistant.${HOST_NAME}
    hostname: homeassistant.${HOST_NAME}.lan
    image: ghcr.io/home-assistant/home-assistant:stable
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
      DOMAINNAME: ${DOMAINNAME}      
      HOST_NAME: ${HOST_NAME}.lan
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${DOCKERDIR}/homeassistant/config:/config
      - ${DOCKERDIR}/logs/homeassistant:/var/log
    restart: always
    network_mode: host
    privileged: true
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8123"]
      interval: 30s
      timeout: 10s
      retries: 5
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Infrastructure"
      - "homepage.name=Home Assistant"
      - "homepage.icon=home-assistant.png"
      - "homepage.href=http://ha.${DOMAINNAME}/"
      - "homepage.description=Smart home control center"

---

Step 3: Crucial Configuration (configuration.yaml)

Because Home Assistant runs on the host network behind reverse proxies (Traefik, Cloudflared, etc.), you must update your HA HTTP settings before remote or proxy access will function cleanly.

1. Open ${DOCKERDIR}/homeassistant/config/configuration.yaml in a text editor:

nano ${DOCKERDIR}/homeassistant/config/configuration.yaml

2. Add the http block to trust your local subnet and Docker proxy headers:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - 10.0.0.0/8       # Adjust to match your local LAN subnet
    - 172.16.0.0/12    # Adjust to match your Docker network bridge subnets
    - 192.168.1.0/24   # Adjust to match your home network subnet

3. Restart Home Assistant to apply the configuration:

docker compose -p mediaserver -f docker-compose-server1.yaml restart homeassistant

---

Step 4: UI Onboarding & Essential Integrations

1. Open your browser and navigate to http://<your-ip-address>:8123.
2. Follow the setup wizard to create your admin account, set your home location, and set time zones.

Connecting Common Docker Services

• MQTT (Mosquitto): Go to Settings -> Devices & Services -> Add Integration -> MQTT. Enter your container host (mosquitto or server1.lan) and port 1883.
• HACS (Home Assistant Community Store): Execute the HACS download script inside the running container to install community custom cards and integrations:

  docker exec -it homeassistant.${HOST_NAME} bash -c "wget -O - https://get.hacs.xyz | bash -"

  After running the script, restart Home Assistant and add HACS via Settings -> Devices & Services.

---

Step 5: Backup & Restore

Backing Up

• Built-in System Backup: Go to Settings -> System -> Backups inside the HA UI to generate downloadable .tar backup files.
• Directory Backup: Stop the container and back up the entire ${DOCKERDIR}/homeassistant/config directory.

Restoring

On a fresh Home Assistant setup screen, click Restore from backup on the initial onboarding page and upload your backup file.

---

Step 6: Troubleshooting

• 400 Bad Request when accessing via Proxy: Ensure your reverse proxy IP/subnet is explicitly listed under trusted_proxies in configuration.yaml.
• Zigbee / Z-Wave USB Stick Not Detected: Ensure the physical device (e.g., /dev/ttyUSB0 or /dev/serial/by-id/...) is plugged in and accessible by the host user.
• Logs: Monitor startup errors in real time:

  docker logs -f homeassistant.${HOST_NAME}