geek-cookbook/manuscript/recipes/homeassistant.md

Home Assistant

Home Assistant is a home automation platform written in Python, with extensive support for 3rd-party home-automation platforms including Xaomi, Phillips Hue, and a bazillion others.

This recipie combines the extensibility of Home Assistant with the flexibility of InfluxDB (for time series data store) and Grafana (for beautiful visualisation of that data).

Ingredients

1. Docker swarm cluster with persistent shared storage
2. Traefik configured per design
3. DNS entry for the hostname you intend to use, pointed to your keepalived IP

Preparation

Setup data locations

We'll need several directories to bind-mount into our container, so create them in /var/data/homeassistant:

mkdir /var/data/homeassistant
cd /var/data/homeassistant
mkdir -p {homeassistant,grafana,influxdb-backup}

Now create a directory for the influxdb realtime data:

mkdir /var/data/runtime/homeassistant/influxdb

Prepare environment

Create /var/data/config/homeassistant/grafana.env, and populate with the following - this is to enable grafana to work with oauth2_proxy without requiring an additional level of authentication:

GF_AUTH_BASIC_ENABLED=false

Setup Docker Swarm

Create a docker swarm config file in docker-compose syntax (v3), something like this:

!!! tip I share (with my patreon patrons) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that patrons can launch any recipe with just a git pull and a docker stack deploy 👍

version: "3"

services:
    influxdb:
      image: influxdb
      networks:
        - internal
      volumes:
        - /var/data/homeassistant/influxdb:/var/lib/influxdb
        - /etc/localtime:/etc/localtime:ro

    homeassistant:
      image: homeassistant/home-assistant
      dns_search: hq.example.com
      volumes:
        - /var/data/homeassistant/homeassistant:/config
        - /etc/localtime:/etc/localtime:ro
      deploy:
        labels:
          - traefik.frontend.rule=Host:homeassistant.example.com
          - traefik.docker.network=traefik_public
          - traefik.port=8123
      networks:
        - traefik_public
        - internal
      ports:
        - 8123:8123

    grafana-app:
      image: grafana/grafana
      env_file : /var/data/config/homeassistant/grafana.env
      volumes:
        - /var/data/homeassistant/grafana:/var/lib/grafana
        - /etc/localtime:/etc/localtime:ro
      networks:
        - internal

    grafana-proxy:
      image: a5huynh/oauth2_proxy
      env_file : /var/data/config/homeassistant/grafana.env
      dns_search: hq.example.com
      networks:
        - internal
        - traefik_public
      deploy:
        labels:
          - traefik.frontend.rule=Host:grafana.example.com
          - traefik.docker.network=traefik_public
          - traefik.port=4180
      volumes:
        - /var/data/config/homeassistant/authenticated-emails.txt:/authenticated-emails.txt
      command: |
        -cookie-secure=false
        -upstream=http://grafana-app:3000
        -redirect-url=https://grafana.example.com
        -http-address=http://0.0.0.0:4180
        -email-domain=example.com
        -provider=github
        -authenticated-emails-file=/authenticated-emails.txt

networks:
  traefik_public:
    external: true
  internal:
    driver: overlay
    ipam:
      config:
        - subnet: 172.16.13.0/24

!!! note Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See my list here.

Serving

Launch Home Assistant stack

Launch the Home Assistant stack by running docker stack deploy homeassistant -c <path -to-docker-compose.yml>

Log into your new instance at https://YOUR-FQDN, the password you created in configuration.yml as "frontend - api_key". Then setup a bunch of sensors, and log into https://grafana.YOUR FQDN and create some beautiful graphs :)

Chef's Notes 📓

1. I tried to protect Home Assistant using oauth2_proxy, but HA is incompatible with the websockets implementation used by Home Assistant. Until this can be fixed, I suggest that geeks set frontend: api_key to a long and complex string, and rely on this to prevent malevolent internet miscreants from turning their lights on at 2am!