Home Assistant : migrer Zigbee2MQTT en conteneur sur une machine virtuelle dédiée

Dans ce tutoriel, je vais vous expliquer comment migrer Zigbee2MQTT du mode : module complémentaire intégré à Home Assistant à un conteneur Docker dans une machine virtuelle dédié.

Cette solution permet d’avoir le service Zigbee2MQTT (Z2M) dans une machine virtuelle détachée de Home Assistant. Le but de cette opération est de moins dépendre de la machine Home Assistant pour le réseau Zigbee.

Avec cette installation, quand vous redémarrez votre serveur Home Assistant, la liaison Zigbee n’est pas coupé, ce qui permet une reprise plus rapide de votre domotique, en cas de restauration de Home Assistant, Z2M est indépendant.

J’ai personnellement effectuée cette migration suite à une restauration de mon Home Assistant. malgré une restauration de la VM HA depuis une sauvegarde avec Proxmox, j’ai eu pas de problème pour un retour à la normale de mes différents périphériques Zigbee et j’ai également perdu une journée de données du fait que la base de données (MariaDB) est également sur le VM Home Assistant (dans un autre tutoriel je vous expliquerai comment migrer la base de données MariaDB).

Pour information, voici mon environnement qui fait fonctionner ma domotique :

• Mini PC fonctionnant sur Proxmox avec une machine virtuelle dédié à Home Assistant et tous les modules complémentaires.

Dans un premier temps, le but est de sortie Z2M dans un environnement détaché de Home Assistant.

Si vous êtes comme moi sur Proxmox, je vous conseille de faire une sauvegarde de la VM Home Assistant.

Préparation de la machine virtuelle

Sur Internet, vous trouverez plusieurs tutoriels qui expliquent comment créer un conteneur LXC dédié à Zigbee2MQTT.

Pour ma part, je n’ai pas choisi cette solution, j’ai préféré dédié créer une machine virtuelle qui sera dédiée à Docker pour faire fonctionner différent « modules complémentaires » en conteneur avec Docker.

Le second point qui m’a décidé à utiliser une VM à la place d’un conteneur LXC est la gestion des périphériques USB notamment pour le dongle USB Zigbee qui est plus facile.

Etant à habituer à Ubuntu, j’ai installé une VM sous Ubuntu 24.04.

Les différentes étapes :

• Télécharger l’ISO de l’OS que vous souhaitez installer
• Envoyer l’ISO sur Proxmox
• Créer une machine virtuelle configurée pour démarrer sur l’ISO précédemment envoyer sur Proxmox.
• Installer l’OS (Ubuntu) en configuration une adresse IP fixe et en activant le serveur SSH pour la connexion distante ( lien n°1 – lien n°2)

Concernant les paramètres de la VM, j’ai alloué de 2CPU, 2Go de RAM et 50 Go d’espace disque.

Une fois Ubuntu installé, connecter vous dessus en SSH, depuis Windows :

ssh user@ip

Commencer par mettre à jour le système d’exploitation :

sudo apt update && sudo apt upgrade -y

Redémarrer le système pour appliquer les mises à jour.

sudo reboot

On va maintenant passer à l’installation de Docker sur la VM, connecter vous en SSH dessus.

Pour Ubuntu j’ai préparé un script qui va permettre d’installer Docker.

Commencer par créer un fichier :

nano docker-install.sh

Copier le contenu du fichier suivant :

Enregistrer le fichier.

Executer le script pour installer Docker et docker compose :

sudo docker-install.sh

Patienter pendant l’installation de Docker.

Pour finir, nous allons modifier le comportement du système pour ne pas à avoir à saisir le mot de passe de l’utilisateur sur les commandes sudo, ceci est nécessaire par la suite pour le transfert de fichiers sur le serveur.

Entrer la commande suivante :

sudo visudo

A la fin du fichier ajouter la ligne suivante :

utilisateur ALL=(root) NOPASSWD: ALL

Sauvegarder les modifications.

Les bases de la machine virtuelle qui va nous servir sont prêtes.

Avant de se lancer dans la configuration, tester que le broker mosquitto est disponible sur votre réseau, pour cela depuis Windows entrer la commande PowerShell suivante :

Test-NetConnection ip-home-assistant -Port 1883

Si vous avez TcpTestSucceeded : true tout est bon !

Préparation du conteneur Docker Zigbee2MQTT

Par habitude, je stocke mes conteneurs dans le dossier /containers.

Aller à la racine du disque :

cd /

Créer le dossier containers :

sudo mkdir containers

Aller dans le dossier containers :

cd containers

Créer le dossier z2m (zigbee2mqtt) :

sudo mkdir z2m

Aller ensuite dans le dossier z2m :

cd z2m

Dans le dossier z2m créer le dossier data :

sudo mkdir data

Dans le dossier z2m, on va créer notre fichier docker-compose.yml qui va contenir les paramètres du conteneur pour Zigbee2MQTT.

Entrer la commande suivante :

sudo nano docker-compose.yml

Copier le contenu suivant dans le fichier :

Pour le moment le conteneur ne sera pas fonctionnel car nous n’avons pas mapper le dongle USB Zigbee et copier les fichiers de configuration

Récupérer la configuration Zigbee2MQTT dans Home Assistant

Avant d’attaquer la migration, nous allons récupérer la configuration actuelle dans Home Assistant pour ne pas perdre d’appareils.

Pour cela vous avez besoin d’avoir File editor d’installé sur Home Assistant.

Aller sur File editor 1 puis rechercher le dossier zigbee2mqtt 2, cliquer dessus pour accéder aux contenus.

Nous avons le contenu du dossier zigbe2mqtt dans Home Assistant :

Télécharger l’ensemble des fichiers (sauf le dossier log), pour cela cliquer sur points verticaux 1.

Puis cliquer sur Download 1.

Enregistrer les fichiers sur votre ordinateur.

Vous devriez avoir quelques choses comme ça :

Arrêter Zigbe2MQTT dans Home Assistant

Pour éviter tout conflit, arrêter Z2M dans Home Assistant, aller dans Paramètres / Modules complémentaires puis cliquer sur Zigbee2MQTT 1.

Commencer par cliquer sur ARRETER 1.

Une fois arrêter, désactiver les différents paramètres :

• Lancer au démarrage
• Chien de garde
• Afficher dans la barre latérale.

Modification de la configuration Zigbee2MQTT

Il va falloir apporter quelques modifications aux fichiers de configuration de Z2M.

Ouvrir le fichier configuration.yml téléchargé précédemment

Adapter le serveur mqtt en indiquant l’adresse ip du serveur Home Assistant :

mqtt:
  server: mqtt://x.x.x.x:1883

Configurer la partie serial :

serial:
  port: /dev/ttyACM0

Ne modifier par le paramètre adapter:

Changer le port du frontend qui permet l’accès à l’interface Web.

frontend:
  port: 8080

Sauvegarder le fichier.

Envoyer les fichiers de configuration sur le nouveau serveur

Pour cette opération depuis Windows, vous aurez besoin de WinSCP.

Pour un besoin ponctuel, je vous conseille d’utiliser le version portable.

Créer une nouvelle connexion, en sélectionnant SCP 1, indiquer l’adresse IP de la machine 2, entrer votre nom d’utilisateur 3 puis cliquer sur Advanced 4.

Dans les paramètres, aller sur SCP/Shell 1 puis dans le champ Shell, sélectionner sudo su - 2 et cliquer sur OK 3.

De retour à la page de configuration de la connexion, cliquer sur le bouton Save et ensuite connecter vous en cliquant sur Login, lors de la connexion entrer le mot de passe de l’utilisateur.

Dans la partie de gauche, aller à l’emplacement ou se trouve les fichiers téléchargés de zigbee2mqtt puis dans la fenêtre de droite (le serveur) aller dans le dossier /containers/z2m/data. Sélectionner le fichier en local et les faire glisser sur la partie droite pour les envoyer sur le serveur.

Changer le dongle Zigbee de machine virtuelle

On va maintenant passer au dongle Zigbee qui doit être branché sur la nouvelle machine virtuelle.

Commencer par arrêter la VM Home Assistant : Paramètres / Système.

Arrêter la VM où Docker est installé :

sudo poweroff

Dans Proxmox, sélectionner la VM Home Assistant 1, aller sur Hardware 2, sélectionner le périphérique USB 3 qui correspond au dongle USB Zigbee puis cliquer sur Remove 4.

Confirmer l’action en cliquant sur Yes 1.

Le dongle USB Zigbee n’est plus lié à la VM Home Assistant

Comme vous l’avez déjà fait pour la VM Home Assistant, on va ajouter le dongle à la nouvelle VM, sélectionner la VM 1, aller dans Hardware 2 et sur le bouton Add 3 puis sur USB Device 4.

Sélectionner Use USB Vendor/Device ID 1 puis sélectionner le dongle USB Zigbee 2 et cliquer sur Add 3.

Le dongle USB est ajouté à la machine virtuelle qui va héberger Zigbee2MQTT.

Démarrer la VM qui va faire fonctionner Zigbee2MQTT et connecter vous en SSH dessus de nouveau.

Configurer le dongle USB Zigbee

Maintenant, nous allons devoir récupérer l’ID du périphérique USB et l’indiquer dans le fichier docker-compose.yml.

Pour afficher les périphérique en fonction de leur id entrer la commande suivante :

ls -l /dev/serial/by-id

Copier l’ID du dongle Zigbee qui correspond à la partie en bleu.

Aller dans le dossier du conteneur z2m :

cd /containers/z2m

Ouvrir le fichier docker-compose.yml :

sudo nano docker-compose.yml

Coller l’ID du périphérique comme sur la capture ci-dessous :

Sauvegarder les modifications.

Démarrer le conteneur Zigbee2MQTT

On arrive à la dernière étape de ce tutoriel, on va commercer par télécharger l’image du conteneur :

sudo docker compose pull

Démarrer le conteneur :

sudo docker compose up -d

Maintenant, on va vérifier le bon fonctionnement du conteneur en regardant les logs de celui-ci qui va nous retourner les logs de zigbee2mqtt comme sous Home Assistant.

Entrer la commande suivante :

sudo docker compose logs -f

Comme on peut le voir sur les captures, le conteneur a démarré sans problème et on peut même voir des périphériques qui communiquer avec le coordinateur zigbee. Sur la seconde capture, on peut voir une erreur car z2m n’arrive pas à contacter le broker mqtt, ce qui est normalement car celui ci se trouve sur Home Assistant et la VM est arrêtée.

Démarrer le VM Home Assistant sur Proxmox et patienter, normalement vous devriez voir que Zigbee2MQTT arrive à communiquer avec le broker MQTT qui se trouve sur Home Assistant.

Tout fonctionne correctement, il ne vous reste plus qu’à vérifier dans Home Assistant que tout remonte correctement.

Compléments

L’interface Web de Z2M est accessible par cette adresse : http://ip-vm-z2m:8080

Pour mettre à jour le conteneur, aller dans le dossier /containers/z2m et entrer la commande suivante :

sudo docker compose pull && sudo docker compose down -v && sudo docker compose up -d