L’objectif de cette méthode est de mettre en place un système de documentation de l’installation HA, automatique et évolutif.
Il repose sur l’emploi d’un LLM couplé à HA et d’une plateforme de gestion documentaire, ici Bookstack.
Le choix s’est porté sur bookstack pour 3 raisons :
- C’est une plateforme historiquement ancienne et maintenue, avec une grosse communauté
- Il existe une installation de type Add-on pour homeassistant, pour ceux qui sont sous HAOS
- Les serveurs MCP qui permettent l’interaction avec le Bot sont opérationnels et disposent de toutes les fonctionnalités d’édition nécessaires
Ce bout de tutoriel vient en complément de l’article déjà fait sur l’installation et la connexion d’un LLM à HA via Telegram et le bot Nanobot :
Il nécessite que le bot soit opérationnel et connecté à HA via le MCP dédié.
Bookstack
Ce n’est pas l’objet ici d’installer bookstack, il existe plein de façons de le faire :
- soit avec les instructions officielles (en script ou en docker)
- Soit dans proxmox avec le script dédié,
- Soit directement en Add-on dans HAOS
Néanmoins il y a deux sujets à traiter :
- La gestion de l’URL d’accès / proxy en cas de besoin d’accès externe.
- La creation d’un utilisateur et de son accès API
URL d’accès
Bookstack crée des liens internes basés sur l’URL fixe qui est définie dans la config de base via le fichier .env :
# Application URL
# This must be the root URL that you want to host BookStack on.
# All URL's in BookStack will be generated using this value.
APP_URL=https://example.com
# Trusted proxies
# Used to indicate trust of systems that proxy to the application so
# certain header values (Such as "X-Forwarded-For") can be used from the
# incoming proxy request to provide origin detail.
# Set to an IP address, or multiple comma seperated IP addresses.
# Can alternatively be set to "*" to trust all proxy addresses.
APP_PROXIES=null
Si vous travaillez uniquement sur le réseau local, votre APP_URL sera de la forme http://192.168.x.x.
Si vous travaillez derrière un proxy, il vous faudra alors spécifier APP_URL avec votrenom de domaine https://bookstack.mondomaine.com et spécifier l’IP du proxy dans APP_PROXIES.
C’est assez restrictif mais si jamais vous changez d’avis en cours de route il existe une commande pour mettre à jour la base de données :
php artisan bookstack:update-url https://old.example.com https://new.example.com
Pour l’Addd-on HAOS je n’ai pas testé, mon installation tourne sous docker mais le sujet doit être le même.
Pour la suite je consière que l’accès se fera uniquement en local, via l’IP locale http://192.168.x.x
Utilisateur dédié
on va créer un utilisateur dédié pour le bot, ce qui simplifie la gestion des accès. C’est très simple ça se fait par l’interface :
Préférences / Utilisateur / Ajouter un nouvel utilisateur :
on lui donne un idenifiant, un mot de passe et on choisis ses droits d’accès. Pour aller plus vite on va le mettre admin dans un premier temps. Il faudra lui créer un rôle sur mesure si vous voulez gérer au plus près les drois d’accès :
Une fois que l’utilisateur est crée, on se loggue sur l’interface avec ce nouvel utilisateur et on lui crée un accès API :
Mon compte / Accès et sécurité / Jetons API / Créer un jeton :
La création du jeton va vous donner deux « tokens » :
- Token ID
- Token SECRET
notez les bien quelque part on va en avoir besoin.
C’est fini du côté de bookstack. Je vous laisse gérer et personnaliser suivant votre convenance.
Connexion du bot
Le bot est dejà opérationnel, connecté à télégram et à HA. On va lui adjoindre une connexion a Bookstack par une serveur MCP dédié :
La procédure reste identique aux autres, on édite le fichier config.json et on lui ajoute le serveur MCP dédié :
"bookstack": {
"command": "npx",
"args": ["-y", "bookstack-mcp-server"],
"env": {
"BOOKSTACK_BASE_URL": "http://192.168.x.x/api",
"BOOKSTACK_API_TOKEN": "Token_ID:Token_SECRET",
"LOG_LEVEL": "error",
"LOG_FORMAT": "pretty",
"DEBUG": "false"
}
}
ou le BOOKSTACK_API_TOKEN est constitué des deux Tokens qu’on a noté précédemment Token_ID:Token_SECRET
et voilà, c’est fini, le bot est maintenant capable de discuter avec bookstack et de créer ou de maintenir de la documentation à la demande :
Un exemple rapide :
Il suffit de demander au bot de documenter une automatisation, un script, des helpers, une install … et de gérer le versionning, ou de gerer la mise à jour de la doc quand vous faites un changement.