Home Assistant

Home Assistant is the central nervous system of the smart home, coordinating devices, sensors, and automations across the entire homelab. Running as a Docker container, it provides local control with cloud-optional features.

Overview

What is Home Assistant? An open-source home automation platform that puts local control and privacy first. Integrates with thousands of devices and services for unified smart home management.

Why Home Assistant? - Local control (no cloud required) - Extensive device support (2000+ integrations) - Powerful automation engine - Privacy-focused - Active community

Installation

Docker Compose

version: '3.8'

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=America/Chicago
    volumes:
      - /opt/stacks/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: host  # Required for device discovery
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0  # Zigbee/Z-Wave dongle (if needed)
    restart: unless-stopped
    privileged: true

Initial Setup

1. Access web UI: http://homeassistant.local:8123
2. Create admin account
3. Set location and time zone
4. Add integrations for devices

Core Integrations

Device Platforms

Google Home / Nest

# configuration.yaml
google_assistant:
  project_id: homelab-project
  service_account: !include SERVICE_ACCOUNT.json
  exposed_domains:
    - light
    - switch
    - climate
    - scene

Philips Hue - Auto-discovery via mDNS - Bridge API integration - Light and scene control

Spotify (via Spotcast)

# configuration.yaml
spotcast:
  sp_dc: !secret spotify_sp_dc
  sp_key: !secret spotify_sp_key

Roborock Vacuum

# configuration.yaml
vacuum:
  - platform: xiaomi_miio
    host: 10.0.30.50
    token: !secret roborock_token

MQTT Sensors (ESP8266/ESP32)

# configuration.yaml
mqtt:
  broker: mosquitto.local
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_password

sensor:
  - platform: mqtt
    name: "Living Room Temperature"
    state_topic: "home/livingroom/temperature"
    unit_of_measurement: "°F"
    device_class: temperature

System Integrations

InfluxDB (Data Storage)

influxdb:
  host: influxdb.local
  port: 8086
  database: homeassistant
  username: !secret influxdb_user
  password: !secret influxdb_password
  include:
    domains:
      - sensor
      - climate

Proxmox Monitoring

proxmox:
  host: proxmox.local
  username: !secret proxmox_user
  password: !secret proxmox_password
  verify_ssl: false
  nodes:
    - pve-node-1
    - pve-node-2

Configuration Structure

Directory Layout

/config/
├── configuration.yaml      # Main config
├── automations.yaml        # Automation definitions
├── scripts.yaml            # Reusable scripts
├── scenes.yaml             # Scene definitions
├── secrets.yaml            # Sensitive data (gitignored)
├── customize.yaml          # Entity customization
├── groups.yaml             # Device groupings
└── packages/               # Split configs
    ├── lighting.yaml
    ├── climate.yaml
    └── security.yaml

Configuration.yaml

homeassistant:
  name: Home
  latitude: !secret latitude
  longitude: !secret longitude
  elevation: 250
  unit_system: imperial
  time_zone: America/Chicago
  customize: !include customize.yaml

# Load split configs
automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml
group: !include groups.yaml

# Integrations
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.20.0/24

recorder:
  db_url: !secret mariadb_url
  purge_keep_days: 30
  exclude:
    domains:
      - automation
      - updater
    entities:
      - sun.sun

logger:
  default: warning
  logs:
    homeassistant.components.mqtt: debug

Automation Examples

Advanced Presence Detection

automation:
  - alias: "Smart Arrival Home"
    trigger:
      - platform: state
        entity_id: person.max
        to: "home"
    condition:
      - condition: sun
        after: sunset
      - condition: state
        entity_id: climate.home
        state: "off"
    action:
      # Turn on entry lights
      - service: light.turn_on
        entity_id: group.entry_lights
        data:
          brightness: 255
          color_temp: 370

      # Set climate
      - service: climate.turn_on
        entity_id: climate.thermostat
        data:
          temperature: 72

      # Welcome notification
      - service: notify.mobile_app_iphone
        data:
          title: "Welcome Home"
          message: "Lights and climate adjusted"

      # Start music
      - delay: "00:00:05"
      - service: spotcast.start
        data:
          device_name: "Living Room Speaker"
          uri: "spotify:playlist:37i9dQZF1DWZeKCadgRdKQ"
          random_song: true

Energy Saving Mode

automation:
  - alias: "Energy Saver - No One Home"
    trigger:
      - platform: state
        entity_id: group.family
        to: "not_home"
        for: "00:30:00"
    action:
      # Turn off all lights
      - service: light.turn_off
        entity_id: all

      # Set thermostat to eco
      - service: climate.set_preset_mode
        data:
          entity_id: climate.thermostat
          preset_mode: "eco"

      # Turn off non-essential devices
      - service: switch.turn_off
        entity_id: group.non_essential_plugs

      # Notification
      - service: notify.mobile_app
        data:
          message: "Energy saver mode activated - no one home"

Smart Vacuum Schedule

automation:
  - alias: "Vacuum Living Room Daily"
    trigger:
      - platform: time
        at: "10:00:00"
    condition:
      - condition: state
        entity_id: binary_sensor.workday
        state: "on"
      - condition: state
        entity_id: group.family
        state: "not_home"
      - condition: numeric_state
        entity_id: sensor.roborock_battery
        above: 50
    action:
      - service: vacuum.send_command
        entity_id: vacuum.roborock
        data:
          command: app_segment_clean
          params: [18]  # Living room zone ID

Dashboards (Lovelace)

Example Dashboard Config

views:
  - title: Home
    icon: mdi:home
    cards:
      - type: weather-forecast
        entity: weather.home

      - type: entities
        title: Climate
        entities:
          - climate.thermostat
          - sensor.living_room_temperature
          - sensor.living_room_humidity

      - type: glance
        title: Lights
        entities:
          - light.living_room
          - light.kitchen
          - light.bedroom
          - light.office

      - type: media-control
        entity: media_player.living_room_speaker

      - type: vacuum-card
        entity: vacuum.roborock

Add-ons & Integrations

Essential Add-ons

Mosquitto MQTT Broker - Message broker for IoT devices - Required for ESP8266/ESP32 sensors

File Editor - Edit configuration files from web UI - Syntax highlighting

Samba Share - Network access to config folder - Easy backup and editing

Node-RED - Visual automation builder - Alternative to YAML automations

HACS (Home Assistant Community Store)

Custom integrations and frontend cards:

# Install HACS
wget -O - https://get.hacs.xyz | bash -

Popular HACS Integrations: - Spotcast – Spotify casting - Browser Mod – Control browser tabs as entities - Adaptive Lighting – Natural light color throughout day - Frigate – NVR with object detection

Mobile App

Companion App Features

• Remote access to Home Assistant
• Location tracking for presence detection
• Actionable notifications
• Camera access
• Sensor data (battery, steps, etc.)

Notification Examples

# Simple notification
- service: notify.mobile_app_iphone
  data:
    message: "Door opened"

# Notification with action
- service: notify.mobile_app_iphone
  data:
    title: "Garage Door Open"
    message: "Garage has been open for 30 minutes"
    data:
      actions:
        - action: "CLOSE_GARAGE"
          title: "Close Door"

Backup & Recovery

Backup Strategy

# Automated backup script
#!/bin/bash
tar -czf ha-backup-$(date +%Y%m%d).tar.gz \
  /opt/stacks/homeassistant/config/

rsync -av ha-backup-*.tar.gz /mnt/backup/homeassistant/

Snapshot Feature

Use Home Assistant's built-in backup:

Settings → System → Backups → Create Backup

Backup Schedule: - Daily automatic backups - Retain 7 days local - Weekly sync to offsite storage

Performance Optimization

Database Tuning

recorder:
  db_url: mysql://user:[email protected]/homeassistant
  purge_keep_days: 7  # Reduce for performance
  commit_interval: 30
  exclude:
    domains:
      - automation
      - script
    entity_globs:
      - sensor.weather_*

Enable Caching

http:
  ip_ban_enabled: true
  login_attempts_threshold: 5

Troubleshooting

Check Configuration

# Validate config before restart
docker exec homeassistant \
  python -m homeassistant --script check_config -c /config

View Logs

# Real-time logs
docker logs -f homeassistant

# Specific component
# In configuration.yaml:
logger:
  logs:
    homeassistant.components.mqtt: debug

Common Issues

Devices Not Discovering - Ensure network_mode: host in Docker - Check firewall rules for mDNS (port 5353)

Automations Not Triggering - Verify automation is enabled - Check conditions and triggers in trace - Review logs for errors

Best Practices

1. Use Secrets – Never commit passwords to Git
2. Split Config – Use packages for organization
3. Test Automations – Manually trigger before relying on them
4. Regular Backups – Automate daily backups
5. Update Safely – Review release notes, test in staging
6. Monitor Performance – Track database size and response times
7. Document Changes – Comment complex automations
8. Security – Use HTTPS and strong passwords

Resources

• Official Documentation
• Community Forum
• HACS
• Awesome Home Assistant