Il existe plusieurs façons d’installer Home Assistant sur un système Linux, chacune offrant des avantages et des inconvénients selon vos besoins. Les trois méthodes principales sont Home Assistant OS (HAOS), l’installation dans une machine virtuelle (VM) avec Proxmox, et l’exécution via Docker. Voici une présentation détaillée pour vous aider à choisir la solution la mieux adaptée.
Home Assistant OS (HAOS)
Home Assistant OS est une solution tout-en-un, conçue pour être simple et rapide à mettre en place. Elle inclut un système d’exploitation minimal dédié uniquement à Home Assistant. L’installation est très intuitive, ce qui en fait un excellent choix pour les débutants. Avec HAOS, tout est préconfiguré, et vous bénéficiez du superviseur intégré qui permet de gérer facilement les mises à jour, les add-ons, les snapshots, et les restaurations. Cependant, cette simplicité a un coût : vous ne pouvez pas utiliser votre machine pour d’autres applications ou services. De plus, en cas de problème avec le système d’exploitation, toute la machine devient inutilisable. HAOS est donc idéal pour ceux qui recherchent une solution dédiée et sans effort de maintenance, mais il manque de flexibilité pour des configurations plus complexes.
Machine Virtuelle (VM) avec Proxmox
L’installation de Home Assistant dans une machine virtuelle via Proxmox est une option très intéressante pour les utilisateurs avancés. Proxmox, un hyperviseur open-source, permet de gérer plusieurs machines virtuelles ou conteneurs sur le même hôte. Avec cette méthode, Home Assistant est isolé dans une VM, ce qui améliore la sécurité et réduit les interférences avec d’autres applications. Cette approche offre une grande flexibilité, car elle vous permet d’exécuter plusieurs services sur la même machine, tout en profitant des fonctionnalités avancées de Proxmox, telles que les sauvegardes, les snapshots, et les migrations. Cependant, elle nécessite une certaine expertise pour l’installation et la gestion des VM. De plus, la virtualisation peut engendrer une légère surcharge de performances, et si Proxmox rencontre un problème, toutes les VM hébergées en seront affectées. Cette méthode est idéale pour les utilisateurs expérimentés cherchant à maximiser l’utilisation de leur machine.
Docker
Enfin, Docker permet d’exécuter Home Assistant comme un conteneur léger sur un système Linux existant. Cette méthode est particulièrement flexible, car elle permet de faire coexister Home Assistant avec d’autres applications sur le même hôte. Contrairement à la virtualisation, Docker fonctionne directement sur le système hôte, ce qui optimise les performances. Avec Docker, vous avez un contrôle total sur l’installation et la personnalisation de Home Assistant. Cependant, cette méthode demande une connaissance de base de la gestion des conteneurs Docker. Vous devrez également gérer manuellement les mises à jour, les sauvegardes, et certaines intégrations externes, car l’installation standard via Docker ne comprend pas le superviseur complet. Cette méthode convient parfaitement aux administrateurs Linux ou à ceux qui recherchent une solution légère et modulaire.
Résumé des choix
| Méthode | Simplicité d’installation | Flexibilité | Superviseur | Performances | Utilisateurs cibles |
| HAOS | ⭐⭐⭐⭐⭐ | ⭐⭐ | Oui | ⭐⭐⭐⭐ | Débutants |
| VM (Proxmox) | ⭐⭐⭐ | ⭐⭐⭐⭐ | Oui | ⭐⭐⭐ | Utilisateurs avancés |
| Docker | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Non | ⭐⭐⭐⭐⭐ | Administrateurs Linux |
Pour ma part, j’ai opté pour une installation sous Docker et ce tutoriel expliquera la procédure à suivre pour installer Home Assistant sous Docker.
1. Installation de Docker
Docker est un outil essentiel pour exécuter Home Assistant comme un conteneur léger. Voici les étapes détaillées pour installer Docker et Docker Compose sur Debian 12. Mise à jour du système et installation des dépendances
- Ajout du dépôt officiel Docker
- Installation de Docker Engine
- Configuration et démarrage de Docker
- Ajout de l’utilisateur au groupe Docker
- Test de Docker
Nous allons détailler l’ensemble des opérations à réaliser.
Avant d’installer Docker, assurez-vous que votre système est à jour. Exécutez les commandes suivantes pour installer les dépendances nécessaires :
| sudo apt update | Vérification du système |
| sudo apt upgrade -y | Exécution des mises à jour |
Deux choix s’offrent à nous pour installer Docker.
- Variante 1 : Installation de Docker depuis les dépôts par défaut de Debian
- Variante 2 (recommandée) : Installation de Docker depuis le dépôt Docker officiel
Je vous explique les deux variantes. Pour ma part j’ai opté pour la seconde, qui a l’avantage de pouvoir se mettre à jour via apt udpate/upgrade et que les mises à jour sont plus fréquentes et récentes. Je vous recommande de suivre cette variante n°2.
Variante 1 – Installation de Docker depuis les dépôts par défaut de Debian
Installer Docker à l’aide de la commande suivante :
| sudo apt install docker.io -y | Installation de Docker depuis les dépôts par défaut de Debian (peut contenir une version plus ancienne que celle disponible via les sources officielles de Docker) |
| docker –version | Vérification de l’installation |
Voici ce que la commande retourne au 10/01/2025.
Ensuite à ajoute notre utilisateur au groupe Docker afin d’éviter d’utiliser sudo à chaque commande
| sudo usermod -aG docker $USER | Ajout de notre utilisateur au groupe Docker |
Déconnecter-vous et reconnectez-vous pour que les changements prennent effet.
A présent nous allons installer Docker Compose.
Docker Compose est un outil qui simplifie la gestion des applications multi-conteneurs dans Docker. Lorsque vous avez une application composée de plusieurs services (comme une base de données, un backend, et un frontend), Docker Compose permet de les orchestrer facilement à partir d’un seul fichier de configuration.
Docker Compose utilise un fichier de configuration en format YAML (généralement nommé docker-compose.yml) pour définir tous les services nécessaires à votre application. Ce fichier décrit :
- Les images Docker à utiliser.
- Les volumes à monter (par exemple, pour la persistance des données).
- Les ports à exposer.
- Les réseaux à configurer entre les conteneurs.
- Les variables d’environnement nécessaires.
| sudo apt install docker-compose -y | Installation de Docker Compose |
| docker-compose –version | Vérification de l’installation |
Variante 2 – Installation de Docker depuis le dépôt Docker officiel (documentation)
Si vous avez choisi de suivre cette variante pour installer Docker, il faut tout d’abord installer les paquets et dépendances pour préparer l’ajout et l’utilisation des dépôts.
⚠️ WARNING : Si jamais vous aviez déjà installé Docker selon la variante 1 et que vous voulez passer à la variante 2, il est impératif de désinstaller Docker existant à l’aide de la commande :
| sudo apt remove docker docker.io containerd runc |
| dpkg -l | grep docker | Pour vérifier les paquets exacts installés |
| sudo apt remove -y docker.io | Désinstalle les paquets listés par la commande précédente |
| sudo apt purge -y docker docker.io containerd runc | Nettoie les fichiers restants |
| sudo apt autoremove -y |
⚠️ FIN DU WARNING
Passons à l’installation de Docker.
| sudo apt update | Vérification du système |
| sudo apt install -y ca-certificates curl gnupg |
Ajoutez la clé GPG pour valider les paquets du dépôt Docker officiel :
| sudo mkdir -p /etc/apt/keyrings | Création du dossier keyrings |
| https://download.docker.com/linux/debian/gpg | sudo gpg –dearmor -o /etc/apt/keyrings/docker.gpg |
On ajoute le dépôt officiel à notre fichier des sources APT :
| echo « deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable » | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null |
On va vérifier que le dépôt a été correctement ajouté :
| cat /etc/apt/sources.list.d/docker.list |
Le contenu doit ressembler à ceci :
deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bullseye stable
Enfin, nous mettons à jour la liste des paquets et installons Docker :
| sudo apt update | Vérification du système |
| sudo apt upgrade -y | Pour installer les mises à jour s’il y en a |
| sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin | Installation de Docker |
On peut vérifier l’installation avec la commande :
| docker –version |
Voici ce que la commande retourne au 10/01/2025.
Nous voilà armé pour passer à l’installation de Home Assistant.
2. Installation de Home Assistant
Dans un premier temps, il faut créer un répertoire pour Home Assistant. J’ai pour habitude de le mettre dans le dossier /home/homeassistant.
| mkdir -p /home/homeassistant | Création d’un dossier /homeassistant dans /home |
| cd /home/homeassistant | Monter le dossier |
On va créer le fichier de configuration des conteneurs docker-compose.yml dans ce dossier.
| nano docker-compose.yml | Création du fichier docker-compose.yml |
Dans le fichier docker-compose.yml ajouter la configuration suivante :
| version: ‘3.3’ services: homeassistant: container_name: homeassistant image: ghcr.io/home-assistant/home-assistant:stable volumes: – ./config:/config environment: – TZ=Europe/Paris restart: unless-stopped ports: – « 8184:8183 » |
Enregistrer et fermer le fichier (Ctrl+O, Enter, puis Ctrl+X).
Voyons un peu ce que nous venons de faire.
| version: ‘3.3’ | Version de docker-compose. |
| services: | |
| homeassistant: | Nom du service |
| container_name: homeassistant | Nom du conteneur. |
| image: ghcr.io/home-assistant/home-assistant:stable | Image Docker utilisée pour ce conteneur. |
| volumes: | Définit les volumes montés. |
| – ./config:/config | Monte le dossier local ./config dans le répertoire /config du conteneur. |
| environment: | Définit les variables d’environnement pour le conteneur. |
| – TZ=Europe/Paris | Définit le fuseau horaire du conteneur. |
| restart: unless-stopped | Spécifie la politique de redémarrage du conteneur. |
| ports: | |
| – « 8184:8183 » | Redirige le port 8184 vers le port 8183. |
On peut à présent accéder à Home Assistant via http://<IP_de_votre_hôte>:8124.
3. Installation de MQTT Broker
Il existe deux outils pour intégrer des produits sous zigbee dans HA. Nous pouvons utiliser Zigbee Home Assistant(ZHA) qui est une intégration native de HA ou bien Zigbee2MQTT qui est une solution indépendante mais qui offre plus de possibilité de personnalisations. Cependant, ce dernier nécessite un certain nombre d’opération de paramétrage de notre système. C’est la solution que j’ai choisie.
| Caractéristique | Zigbee2MQTT | ZHA |
| Simplicité d’installation | ⚠️ Nécessite MQTT et configuration manuelle | ✅ Intégration native et facile à configurer |
| Compatibilité des appareils | ✅ Très large, supporte de nombreux appareils | ⚠️ Bonne, mais certains appareils peuvent manquer |
| Personnalisation | ✅ Paramètres avancés disponibles | ⚠️ Options limitées |
| Indépendance | ✅ Fonctionne indépendamment de Home Assistant | ⚠️ Dépend de Home Assistant |
| Diagnostic et logs | ✅ Journaux détaillés et complets | ⚠️ Fonctionnalités de base |
L’installation d’un broker MQTT est une étape essentielle pour permettre à Home Assistant de communiquer avec divers appareils IoT (Internet des objets) comme les capteurs, les actionneurs, ou les systèmes domotiques. MQTT (Message Queuing Telemetry Transport) est un protocole léger conçu pour les communications efficaces entre appareils.
A présent, nous allons installer Mosquitto, l’un des brokers MQTT les plus populaires et fiables.
- Création des répertoires nécessaires.
- Création du fichier de configuration mosquitto.conf.
- Configuration des permissions.
- Configuration de docker-compose.yml.
- Démarrage et activation du service.
- Test de Mosquitto.
- Intégration dans HA.
Nous allons utiliser Docker pour installer Mosquitto en tant que conteneur avec l’image officielle eclipse-mosquitto:latest. Cela nous permet de gérer Mosquitto dans un environnement isolé sans dépendre des paquets système installés via APT.
| mkdir -p /home/homeassistant/mosquitto/{config,data,log} | Création des dossiers : config, data et log |
A présent nous allons créer le fichier de configuration mosquitto.conf. Monter le dossier /home/homeassistant/mosquitto/config.
Créer le fichier mosquitto.conf à l’aide de la commande :
| nano mosquitto.conf | Création du fichier de configuration |
Dans le fichier mosquitto.conf, ajouter la configuration suivante :
| persistence true | |
| persistence_location /mosquitto/data/ | |
| log_dest file /mosquitto/log/mosquitto.log | |
| listener 1883 | |
| # Authentication (si nécessaire) | |
| allow_anonymous true | Permet aux clients de se connecter au courtier sans avoir besoin de fournir un nom d’utilisateur ou un mot de passe |
Enregistrer et fermer le fichier (Ctrl+O, Enter, puis Ctrl+X).
Enfin, nous allons vérifier les permissions des dossiers :
| sudo chown -R 1883:1883 /home/homeassistant/mosquitto |
A présent nous allons configurer le conteneur docker-compose.yml en ajoutant un nouveau service.
| nano docker-compose.yml |
| version: ‘3.3’ | Ne pas remettre |
| services: | Ne pas remettre |
| mosquitto: | |
| container_name: mosquitto | |
| image: eclipse-mosquitto:latest | |
| volumes: | |
| – /home/homeassistant/mosquitto/config:/mosquitto/config | |
| – /home/homeassistant/mosquitto/data:/mosquitto/data | |
| – /home/homeassistant/mosquitto/data:/mosquitto/log | |
| restart: unless-stopped | |
| ports: | |
| – « 1883:1883 » | |
| – « 9001:9001 » |
Votre fichier doit ressembler à cela :
Nous pouvons à présent redémarrer Docker compose afin que la configuration soit prise en compte.
| docker-compose down | Eteint le conteneur |
| docker-compose up -d | Démarre le conteneur |
| docker ps | Vérifie que le conteneur est lancé |
Nous sommes prêts pour intégrer Mosquitto dans Home Assistant.
Dans Home Assistant, allez dans Paramètre > Appareils et services > Ajouter une intégration.
Recherchez « MQTT ». La fenêtre suivante va s’afficher :
| Courtier : mosquitto (nom du conteneur Docker) |
| Port : 1883 |
| Nom utilisateur : Laissez vide si allow_anonymous est true |
| Mot de passe : Laissez vide si allow_anonymous est true |
Valider la connexion. Home Assistant devrait se connecter avec succès à Mosquitto.
4. Installation de Zigbee2MQTT (Z2M)
A présent, nous allons installer Zigbee2MQTT.
- Création des répertoires nécessaires
- Configuration des permissions
- Configuration de docker-compose.yml
- Configuration de Zigbee2MQTT
- Démarrage et test
- Intégration de l’interface Z2M dans HA
Dans un premier temps, on crée les dossiers pour stocker la configuration et les données de Zigbee2MQTT.
| mkdir -p /home/homeassistant/zigbee2mqtt/data | Crée deux dossiers : zigbee2MQTT et data |
On s’assure que Zigbee2MQTT puisse accéder à ces fichiers.
| sudo chown -R 1883:1883 /home/homeassistant/zigbee2mqtt |
A présent nous allons configurer le conteneur docker-compose.yml en ajoutant un nouveau service. Nous devons nous appuyer sur la documentation officielle Zigbee2MQTT.
| nano docker-compose.yml |
| version: ‘3.3’ | Ne pas remettre |
| services: | Ne pas remettre |
| zigbee2mqtt: | |
| container_name: zigbee2mqtt | |
| image: koenkk/zigbee2mqtt | |
| restart: unless-stopped | |
| volumes: | |
| – /home/homeassistant/zigbee2mqtt/data:/app/data | Stocke les configurations et données de Zigbee2MQTT |
| – /run/udev:/run/udev:ro | Permet la détection des adaptateurs Zigbee dans Docker |
| ports: | |
| – « 8080:8080 » | |
| devices: | |
| – /dev/ttyUSB0:/dev/ttyUSB0 | Correspond au port de l’adaptateur Zigbee |
Votre fichier doit ressembler à cela :
Enfin, nous devons configurer le fichier configuration.yaml de Zigbee2MQTT.
Localisez le fichier configuration.yaml dans /home/homeassistant/zigbee2mqtt/data. S’il n’existe pas, créer le fichier configuration.yaml.
| nano configuration.yaml |
| mqtt: | |
| base_topic: zigbee2mqtt | |
| server: mqtt://mosquitto | Le courtier MQTT utilisé (nom du conteneur Docker, ici mosquitto) |
| user: » | |
| password: » | |
| serial: | Port de l’adaptateur Zigbee |
| port: /dev/ttyUSB0 | |
| frontend: | Définit le port de l’interface web Zigbee2MQTT |
| port: 8080 |
Le fichier doit ressembler à cela :
Nous pouvons maintenant redémarrer Docker Compose.
| docker-compose down | Eteint le conteneur |
| docker-compose up -d | Démarre le conteneur |
| docker ps | Vérifie que le conteneur est lancé |
Nous pouvons nous rendre dans notre navigateur pour accéder à l’interface Zigbee2MQTT à l’aide de l’adresse http://<IP_DU_SERVEUR>:8080. Pour ma part, 192.168.XXX.XXX :8080.
Comme vous pouvez le remarquer, nous devons nous connecter à une page internet en dehors de l’interface de Home Assistant. Ce n’est pas optimal. Il existe une solution ! La création d’un dashboard, qui sera l’image du site web de Z2M.
Pour ce faire, dans Home Assistant allez dans Paramètre > Tableaux de bord > Ajouter un tableau de bord > Page Web.
Dans URL, rentrer l’adresse http://<IP_DU_SERVEUR>:8080 (192.168.XXX.XXX :8080 dans mon cas).
| Nommez votre dashboard (ex : Zigbee2MQTT) |
| Ajouter une icône (ex : mdi:zigbee) |
| Saisissez l’URL (ex : dashboard-zigbee2mqtt). Doit se remplir tout seul lors de la saisie du titre. |
| Cliquer sur Créer |
Le nouveau dashboard s’est ajouté sur la barre latérale droite. En cliquant dessus, nous arrivons sur la page de configuration des appareils.
Nous espérons que ce guide vous aura permis de bien débuter avec Home Assistant et de poser les bases de votre installation domotique. N’hésitez pas à consulter la documentation officielle de chaque composant pour approfondir vos connaissances et exploiter pleinement leurs fonctionnalités. Pour toute question ou assistance, la communauté Home Assistant est également une ressource précieuse.
Bonne exploration et personnalisation de votre système domotique ! 🚀
