Home Assistant en Docker : domotique open source et MQTT

Home Assistant est la référence open source de la domotique : elle centralise des appareils de marques différentes (Zigbee, Wi-Fi, MQTT...) dans une interface unique, sans dépendre du cloud d'un fabricant. Je le déploie en variante Core (sans Supervisor ni add-ons) via Docker Compose, pour rester cohérent avec le reste de mon infrastructure conteneurisée — le compromis est de gérer soi-même les intégrations qui, en version Supervised, seraient de simples add-ons en un clic.

1. docker-compose.yml : Home Assistant + Mosquitto (MQTT)

Un broker MQTT (Mosquitto) est quasi indispensable pour faire remonter des capteurs tiers (modules Tasmota, ESPHome, passerelles Zigbee...) vers Home Assistant.

services:
  homeassistant:
    container_name: homeassistant
    image: homeassistant/home-assistant:stable
    restart: unless-stopped
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Europe/Paris
    ports:
      - "8123:8123"
    depends_on:
      - mosquitto

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2
    restart: unless-stopped
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"
      - "9001:9001"

Configuration minimale de Mosquitto (mosquitto/config/mosquitto.conf) :

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883
listener 9001
protocol websockets
allow_anonymous false
password_file /mosquitto/config/passwd

Créer un utilisateur MQTT :

$ sudo chown -R 1883:1883 mosquitto
$ docker run --rm -v $(pwd)/mosquitto/config:/mosquitto/config \
    eclipse-mosquitto:2 mosquitto_passwd -b -c /mosquitto/config/passwd homeassistant <mot_de_passe>

2. Accès HTTPS derrière un reverse proxy

Le WebSocket est obligatoire (sinon le frontend reste bloqué sur "Unable to connect"). Depuis les versions récentes, la configuration des proxies de confiance ne se fait plus en YAML (le bloc http: trusted_proxies: est obsolète) mais uniquement via l'interface : Paramètres → Système → Réseau → Proxy inverse. Il faut y déclarer 127.0.0.1/32, ::1/128, et la passerelle de chaque réseau Docker utilisé (visible via docker network inspect) — sinon Home Assistant refuse la connexion avec une erreur "Received X-Forwarded-For header from an untrusted proxy".

3. Intégrer un capteur MQTT manuellement

La découverte automatique MQTT ne fonctionne pas toujours de façon fiable selon le firmware de vos modules. Dans ce cas, déclarez le capteur manuellement dans configuration.yaml, avec un template tolérant aux données manquantes :

mqtt:
  sensor:
    - name: "Puissance instantanée"
      state_topic: "maison/energie/tele/SENSOR"
      value_template: "{{ value_json.METER.P if value_json.METER is defined else this.state }}"
      unit_of_measurement: "W"
      device_class: power
      state_class: measurement

Le if value_json.METER is defined else this.state évite que le capteur retombe à zéro lors d'une lecture temporairement absente — un cas fréquent avec les capteurs Téléinfo/Linky, où une trame sur plusieurs peut être incomplète.

Astuce réseau Docker : si Home Assistant doit joindre un autre conteneur (une base de données, par exemple) situé sur un réseau Compose distinct, ajoutez ce réseau en external: true dans le service — bien plus fiable qu'une IP fixe, qui change à chaque recréation du réseau.

Conclusion

Home Assistant en Docker Compose demande un peu plus de configuration manuelle que la version "appliance" (HAOS), mais s'intègre beaucoup mieux dans un serveur qui héberge déjà d'autres services. Une fois le proxy inverse et MQTT en place, l'ajout de nouveaux capteurs devient rapide.