Édition, gestion de version et partage de mes fichiers de configuration

oncleben31 · Décembre 19, 2020, 11:15

Edit du 11/09/2021:

Ajout d’explication de comment j’utilise les commandes de synchronisation.
Recommandation d’utiliser des tags supplémentaires sur GitHub.
Recommandation d’ajouter vos configurations partagées sur l’awesome list francophone.

Introduction

Ceci est un guide en français pour expliquer comment je gère mes fichiers de configurations.

Il y a beaucoup de chose qui sont faisables uniquement à partir de l’IHM Home Assistant. Mais pour certaines intégrations ou pour mettre au point certaines automatisations avancées vous allez avoir besoin de modifier les fichiers de configuration de Home Assistant qui sont au format YAML.

Le plus simple est d’utiliser l’addon officiel File Editor. Beaucoup d’entre nous ont commencé par là. En revanche si vous passez du temps sur la modification de ces fichiers, vous voudrez sûrement rendre cette activité plus confortable. Il y a de nombreuses façons de faire et c’est surtout une histoire de goût. Dans cet article, je vous montre ce que j’ai mis en place pour éditer, gérer les versions et partager ma configuration sur GitHub.

Édition des fichiers

L’éditeur

J’ai décidé de gérer l’édition de mes fichiers de configuration sur mon Mac, de façon déportée et asynchrone de mon instance de production de Home Assistant. J’y vois les avantages suivants:

J’ai de nombreuses solutions différentes et confortables pour éditer les fichiers
Je peux utiliser toutes les ressources de calcul pour l’éditeur sans mettre à risque le CPU qui fait tourner HA.
Je peux faire des grands chantiers pendant plusieurs jours ou semaines si nécessaire sans mettre à risque la stabilité de ma domotique.

J’ai choisi Visual Studio Code (VSC) après en avoir testé plusieurs sur MacOS. Je me suis arrêté sur cet outil car il semblait de plus en plus populaire et que j’y ai trouvé plusieurs addons qui me facilite la vie.
Si vous ne devez installer qu’un addon c’est Home Assistant Config Helper:

Il vérifie la syntaxe de vos fichiers YAML, propose une complétion automatique lors de l’édition des fichiers de configuration YAML car il connaît les structures mais aussi les noms de vos entités et services. En effet, cet addon se connecte à votre instance de production de Home Assistant pour y récupérer, en direct, la liste de ces éléments.
De façon plus avancé il permet d’évaluer un modèle Jinja.
En bonus sans quitter l’éditeur je peux lancer des commandes pour recharger les automatisations, redémarrer le serveur, etc…

En mode avancé et pour les développeurs, VSC permet aussi de debugger en mode pas à pas son instance Home Assistant en utilisant l’intégration Remote Python Debugger.

La synchronisation

Pour synchroniser les fichiers de conf entre mon Mac et mon serveur Home Assistant, j’ai une solution un peu complexe. J’utilise rsync qui se connecte en ssh à mon serveur Home Assistant depuis mon Mac. L’avantage c’est que je peux comparer ce qui change entre ma version local (mon Mac) et la version distante (mon serveur HA).
En effet, avec HACS ou les éditeurs intégrés dans l’interface graphique de Home Assistant certains fichiers de configuration peuvent évoluer sur mon serveur alors que je travaille en parallèle en local sur mon Mac. L’outil rsync me permet alors de détecter les conflits et de choisir ce que j’importe ou exporte depuis mon Mac.

Pour implémenter ce système de synchronisation j’ai besoin:

De l’addon SSH & Web Terminal installé sur HassOS. C’est lui qui gère le service SSH sur mon serveur Home Assistant et gère les clés publiques/privées pour s’authentifier sans échanger de login et mot de passe.
De l’addon sync-rsync installé sur Visual Studio Code. Il ajoute des aides dans la palette de commande et dans les menus contextuels pour lancer les synchronisations soient totales soit partielles (un fichier ou un répertoire uniquement)
De l’outil rsync installé sur votre système. Attention sur MacOS la version installée par défaut avec l’OS est une ancienne version qui ne se comporte pas toujours comme le décrit la documentation. Il est indispensable d’installer manuellement une version récente.
Du fichier de paramétrage .rsync-filter (exemple de ma configuration) qui permet de lister les fichiers que je veux inclure ou exclure de la synchronisation. Par exemple je ne vais pas synchroniser en local la base de données.

Ma structure de répertoire

J’ai décidé de créer un répertoire qui contient le dossier config qui est l’image de ma configuration sur mon serveur Home Assistant. Les autres fichiers et dossiers servent à documenter et paramétrer les outils que j’utilise pour modifier ou partager ma configuration.

L’utilisation

Une fois paramétré, j’utilise la palette de commande pour demander:

soit une comparaison entre tous les fichiers sur ma machine de dev et la machine qui héberge home assistant.
soit la synchronisation entre ces deux machine dans un sens ou dans un autre.

Il y aussi la possibilité d’utiliser le menu contextuel sur un fichier ou un répertoire pour synchroniser uniquement cet élément de votre configuration.

Gestion de version

Pourquoi ?

Je suis convaincu que la gestion de version est un incontournable. Si vous n’en avez pas réfléchissez y sérieusement.
La domotique à pour objectif d’être au coeur de nos maisons. C’est donc un système central et critique. C’est aussi un système que vous allez constamment modifier pour ajouter de nouvelles intégrations, implémenter une nouvelle fonctionnalité de Home Assistant, améliorer une automatisation. Les risques d’introduire une modification qui va perturber quelque chose qui fonctionnait correctement sont réels. Vous aurez aussi peut être un jour besoin de savoir pourquoi vous aviez fait cette modification il y a plusieurs mois.

Donc même si à l’origine réservé à un publique de codeur, la gestion de version est un moyen de gérer ces risques et de construire un historique de l’évolution de notre configuration. Vous pourrez alors revenir sur n’importe quelle modification du passé et lire le commentaire associé à une ancienne modification pour comprendre pourquoi vous l’aviez implémentée.
C’est un complément à une stratégie de backup (tout aussi indispensable) mais les deux ne sont pas équivalents.

git

C’est pour cela que je vous recommande d’utiliser une gestion de version. Et l’outil incontournable aujourd’hui pour faire cela c’est git.

Une fois que vous êtes convaincus voilà les 3 choses à faire:

Installer git sur votre système (s’il n’est pas déjà présent) et l’activer pour le dossier qui regroupe vos fichiers de configurations
paramétrer le fichier .gitignore (exemple de ma configuration) qui, comme pour le fichier de paramétrage de rsync permet de choisir ce que l’on veut inclure ou exclure de la gestion de version.
IMPORTANT: vous poser la question de la sensibilité de certaines données si vous comptez à un moment partager votre configuration sur GitHub ou équivalent (voir paragraphe dédié dans la section suivante).

L’avantage de ce setup, c’est que l’édition et la gestion de version est asynchrone de ma configuration en production.

Un exemple d’usage: Je peux faire, avec git, une branche dédiée à un gros chantier (par exemple refactorisation des automatisations suite à la sortie de la fonction choose et wait_for_trigger), avec des commits au fur et à mesure que j’avance. Je synchronise de temps en temps pour tester en production.
Comme c’est pas complètement terminé, je peux basculer sur la branche principale faire quelques modifications de maintenance, synchroniser à nouveau avec mon Home Assistant pour avoir une configuration sans les modifications du gros chantier et les partager sur GitHub. Quand j’ai du temps je peux revenir sur ma branche dédiée et reprendre mon travail de refactorisation. Quand c’est mature je merge ces modifications dans la branche principale, synchronise et partage sur GitHub.

Usage optionnel et avancé: pre-commit

L’outil git permet aussi de lancer des vérifications automatiques sur les fichiers modifiés avant de faire les commits. Si ca vous interesse, documentez vous sur l’outil pre-commit et le concept de hook.

Ma configuration est paramétré pour vérifier à chaque commit:

La syntaxe YAML
La mise en forme des fichiers (exemple: ligne vide à la fin d’un fichier ; éviter les espaces à la fin du ligne, etc…)

Partage sur GitHub

Comme de nombreux autre utilisateurs je partage ma config sur GitHub pour inspirer la communauté.

Comme expliqué plus haut, je partage un répertoire qui contient le dossier config. C’est lui qui est utilisé par Home Assistant pour paramétrer votre serveur domotique. Ca me permet de mettre à la racine des fichiers spécifiques pour le paramétrage de l’éditeur, de rsync, de git, de GitHub et un fichier README.md.

Ce fichier README.md permet de documenter la structure de ma configuration. J’ai décidé aussi de documenter tous les fichiers avec une description rapide de leur rôle. C’est pour la communauté mais aussi pour moi pour me faciliter la vie quand je dois reprendre des fichiers qui n’ont pas été touchés depuis plusieurs mois. Vous remarquerez que j’ajoute régulièrement un lien vers la documentation officielle en lien avec le contenu du fichier. Ca me permet très rapidement de vérifier une information si j’en ai besoin.

Attentions à vos données sensibles

Vos données sensibles peuvent être un login, un mot de passe, un token d’accès à un équipement ou service, une adresse IP. Cela peut être aussi une information personnelle comme les coordonnées GPS de votre maison, le nom de ses occupants, etc.
Toutes ces données peuvent exister dans vos fichiers de configuration et si vous les incluez dans la gestion de version et que vous décidez de les partager elle seront facilement trouvées par des moteurs de recherches dédiés au service de personnes mal intentionnées.

Pour gérer ces information sensibles utilisez le fichier secrets.yaml. Assurez vous qu’il est bien dans le .gitignore pour ne pas être géré par git et donc partagé. Dans le reste de la configuration vous pouvez faire appelle à vos secrets avec la syntaxe !secret nom_de_la_cle. Il y a d’autres solutions pour gérés les secrets mais je n’ai pas d’expérience avec: keyring et credstash

Les erreurs ca arrive, si jamais vous faites un commit (une validation dans sa traduction française) avec une donnée sensible, il existe des moyens pour en limiter les impacts.
Attention, dans certains contextes vous n’aurez aucun moyen de faire disparaître complètement l’information et la seule solution sera de révoquer le token ou changer le mot de passe. Et comme vous ne pouvez pas facilement changer de nom de famille ou d’adresse, si ces information sont confidentielle pour vous, soyez prudent dans l’usage que vous faites avec cet outil.

Partager votre configuration

Donc si vous voulez vous lancer, une fois vos fichiers rassemblés sur une machine où git est installé, allez sur GitHub pour créer un nouveau dépôt (exemple home-assistant-config). Suivez les instructions de GitHub pour le lier à vos fichier de configuration.
Ca y est votre configuration et partagé avec la communauté. N’oubliez pas d’ajouter les mots clés à votre dépôt pour donner de la visibilité. Au minimum ajouté le mot clé home-assistant-config. Les mots clés francais ou francophone sont aussi recommandés si vous avez décidé d’écrire vos commentaires en français.

Enfin vous pouvez promouvoir l’existence de votre configuration partagée sur l’awesome list francophone pour la rendre visible à la communauté HACF.

Usage optionnel et avancé: Continuous Integration (CI)

Maintenant que vous avez votre configuration sur GitHub vous pouvez en profiter pour utiliser certaines fonctionnalités avancées. Les GitHub workflows permettent de réaliser des tâches automatiques lorsque que vous poussez vos commits. Les possibilités sont infinis. Cela s’appelle en anglais le Continuous Integration.

Pour ma configuration à chaque nouvelle version publiée:

Je teste la syntaxe de tous les fichiers YAML avec yamllint
Je teste la syntaxe des fichiers markdown (extension .md)
Je vérifie que tous les liens de mon README ne sont pas morts
Je vérifie ma configuration sur la dernière version stable et beta publiée. Equivalent de l’action Vérifier la configuration dans l’IHM de Home Assistant.

Si ca vous intéresse vous pouvez regarder le contenu de mon répertoire .github de ma configuration.

Conclusion

Bravo si vous êtes allez au bout de la lecture de ce pavé.
J’espère que je vous ai convaincu pour partager votre configuration. Si cela vous intéresse je vous invite à investiguer le sujet pour voir les alternatives implémentées par d’autres.

Sylvain_G · Décembre 21, 2020, 2:54

@oncleben31, j’ai un peu de mal à comprendre comment tu fais ta synchronisation entre ton poste local, où tu modifies tes fichiers via VSCode, et les fichiers distants sur l’hôte du Home Assistant.

Tu passes par le partage Samba ou en SFTP ?

Ayant déjà pété ma configuration de HA, je voudrais pouvoir travailler sereinement en local avant de pousser mes modifications sur HA. Mais je suis sur RPi (distant) / Win10 (local) et je ne voudrais pas installer une usine à gaz plus complexe que HA lui-même.
Il existe des installations de RSync via WSL, … j’ai un peu de mal à comprendre…

Est-ce qu’une synchro via SFTP est possible sous HA ?
Si oui, est-ce que l’utilisation de VS Code SFTP peut être possible et pas trop complexe ?
Où se trouve les fichiers du répertoire config ?

pepite · Décembre 22, 2020, 6:46

Bonjour,

Non, il utilise rsync entre son HA et son Mac dans un sens comme dan l’autre

Sylvain_G · Décembre 22, 2020, 6:48

OK, mais rsync doit utiliser une URL de connexion ou un port. Comment est configuré rsync ?

pepite · Décembre 22, 2020, 6:58

Pour RSYNC tu as un demon et un client.
Le client se connecte au demon par une adresse IP

Sylvain_G · Décembre 22, 2020, 7:18

ok, merci je ne connaissais pas rsync et sous WIN10, ça n’a pas l’air simple d’installation…
Et sais-tu où se trouve les fichiers contenus dans le répertoire config sur l’hôte de HA ?

oncleben31 · Décembre 22, 2020, 8:35

Avec une install HassOS, les fichier sont dans le repertoire config

Sylvain_G · Décembre 22, 2020, 8:41

@oncleben31, lorsque tu te connectes en ssh, est-ce que tu peux me donner le path absolu de ce répertoire config s’il te plait.

pepite · Décembre 22, 2020, 9:41

cd /config

Ca devrait le faire

oncleben31 · Décembre 22, 2020, 9:47

Ils ont du faire plusieurs point de montage. La config est dispo à:

/config
/root/config

oncleben31 · Décembre 22, 2020, 9:54

J’en profite pour partager une partie du paramétrage de l’addon rsync:

		"sync-rsync.sites": [
			{
				"name": "NOM_DE_LA_CONF",
				"localPath": "/PATH/home-assistant-config/config",
				"remotePath": "USER@SERVEUR_IP:/root/config"
			}
		], 
		"sync-rsync.autoShowOutput": true,
		"sync-rsync.showProgress": false,
		"sync-rsync.delete": true,
		"sync-rsync.options": [

			[
				"--filter",
				"._/PATH/home-assistant-config/.rsync-filter"
			]
		],

Sylvain_G · Décembre 22, 2020, 10:07

Ah, @oncleben31, tu es sous Hassio ?
Je suis sous Docker superviser …

Effectivement sans Docker c’est plus simple d’accès

Comment je peux faire pour accéder à ces fichiers sous une installation via Docker. Ces fichiers doivent pourtant être sauvegardés quelque part car j’ai tout réinstallé Docker + HA et j’ai retrouvé mes fichiers d’avant la réinstallation.
Le seul endroit où je les ai trouvé, c’est :

/usr/share/hassio/homeassistant/

Est-ce que vous pouvez confirmer que c’est bien ces fichiers ?

Sylvain_G · Décembre 22, 2020, 11:03

@oncleben31, pour configurer dans VSCode Home Assistant Config Helper, dans Paramètres > Extensions > Home Assistant Config Helper , que doit-on mettre pour :

Host Url :
J’ai essayé, sans succès :
- IP de l’hôte du HA
- IP de l’hôte du HA:8123
- https://url_de_ha
Long Lived Access Token
J’ai créer un token via le compte admin de HA et Jetons d'accès longue durée. C’est bien ça ?

oncleben31 · Décembre 22, 2020, 3:42

J’ai mis https://url_de_ha

Oui c’est ca

Matilas · Décembre 22, 2020, 3:57

Merci pour ton post très intéressant ! J’en suis pas encore à ce niveau là car je commence à peine mais ça mérite réflexion tant que mon système n’est pas complexe !

Jefnewtech · Décembre 29, 2020, 4:43

Bonjour superbe description,

Je suis sous macOS également mais je n’arrive pas à utiliser rsync

Est-il possible de rentrer plus dans les détails de la configuration complète pour ce passage ?

Merci

Pozzi · Décembre 29, 2020, 6:36

Je ne sais pas si tu as résolu ton problème depuis mais le dossier config doit être sur ton hôte et non sur ton container HA. Dans le fichier docker compose (si tu utilises ça) tu dois avoir des volumes de précisé pour monter le dossier config.
Ensuite pour rsync le mieux est d’utiliser le protocol ssh (qui est pas défaut je crois), le port doit être ouvert sur ton hôte.

Pozzi · Décembre 29, 2020, 6:37

Où en es-tu dans ta configuration ? Quels messages d’erreurs ? Qu’est-ce qui pose problème ?

Jefnewtech · Décembre 29, 2020, 6:45

Pour le moment j’ai ma configuration sur un raspberry pi 3b+ et j’ai une copie de la configuration sur mon mac que je modifie avec vscode.

Ce que je fait pour l’instant c’est que j’envoie ma config sur GitHub pour mon suivi perso et je transfère chaque fichiers modifiés manuellement avec l’accès via samba.

J’ai installer sync-rsync sur vscode mais je n’arrive pas à comprendre où le paramétrer et ce que je dois ajouter sur HA

Merci

Pozzi · Décembre 29, 2020, 6:54

C’est un rpi dédié ? Si c’est le cas, as-tu installé l’addon SSH & Web terminal sur HA ?