Apprise

Posté le 15. Mars 2023  •  6 minutes  • 1138 mots  • Autres langues:  English

La version v1.3 de BorgWarehouse intégrait une fonctionnalité attendue : les notifications par email. Cette option vous permet d’être alerté par email si l’un de vos repository BorgBackup n’a pas été sauvegardé depuis un certains temps configurable. Si vous n’avez pas encore cette version, je vous invite à mettre à jour votre instance BorgWarehouse et à paramétrer vos réglages SMTP .

Aujourd’hui, tout le monde a une boîte mail et la décentralisation¹ de l’email couplée à l’interopérabilité de ce protocole donne tort, année après année, à toutes celles et ceux qui annonçaient sa mort. Toutefois, les notifications par email c’est bien, mais en 2023 ce n’est plus suffisant. Nous avons tous·tes des usages personnels et différents de nos adresses emails. Ainsi, certain·e·s ne préfèrent plus voir des “alertes” en tout genre remplir leurs boîtes mails et utilisent d’autres canaux pour ce type de notification : SMS, Discord, Slack, Matrix, Mattermost… Mais comment faire pour intégrer dans une application autant de canaux de communication ?

C’est suite à une suggestion de la part d’un utilisateur de BorgWarehouse que j’ai découvert Apprise, la librairie qui est le sujet de ce nouvel article et qui résout cette dernière question.

C’est quoi Apprise ?

Apprise est une librairie écrite en Python et qui vous permet d’envoyer des notifications (push) à la quasi-totalité des services existant aujourd’hui. À ce jour, Apprise permet de notifier plus de 90 services dans la version 1.3.0, vous retrouverez la liste exhaustive ici .

Pour moi, la liste des avantages à utiliser Apprise est la suivante :

• C’est un logiciel libre.
• Une seule librairie à gérer pour communiquer avec 90+ services.
• Une documentation claire et précise pour chacun des services supportés !
• Extrêmement léger.
• Utilisation en paquet local ou par API avec un déploiement en micro-service.
• Envoi rapide et asynchrone des notifications à tous les services.

Pour mon cas, dans BorgWarehouse, sans Apprise il aurait fallu que j’intègre un à un chaque service de notification souhaité par les utilisateurs. C’est un travail laborieux et qui a pour conséquence une maintenance lourde et interminable. Grâce à Apprise, les utilisateurs peuvent notifier leur application favorite en quelques clics !

Enfin, un dernier avantage, et non des moindres, est que Apprise est un projet actif, avec de nombreux contributeur·rice·s et de nouveaux services qui sont régulièrement intégrés.

Le package Python

Vous pouvez choisir d’installer Apprise comme un paquet local sur votre machine. La librairie est écrite en Python, et l’installation se fera donc en passant par le gestionnaire de paquets Python : pip.

pip install apprise

Ensuite, le paquet vous permet d’envoyer des notifications à n’importe quelle application par le biais d’une ligne de commande simple qui pourra prendre diverses options telles que :

• Le corps du message
• Un titre (utile pour les notifications par email)
• l’URL du service à notifier

Vous trouverez les modèles d’URL pour chaque service dans cette documentation .

Quelques exemples tirés de la documentation Apprise :

# Send a notification to as many servers as you want
# as you can easily chain one after another (the -vv provides some
# additional verbosity to help let you know what is going on):
apprise -vv -t 'my title' -b 'my notification body' \
   'mailto://myemail:mypass@gmail.com' \
   'pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b'

Si vous ne spécifiez pas de corps (-b), alors la sortie standard est utilisée, pratique pour envoyer le résultat d’une commande.

# If you don't specify a --body (-b) then stdin is used allowing
# you to use the tool as part of your every day administration:
cat /proc/cpuinfo | apprise -vv -t 'cpu info' \
   'mailto://myemail:mypass@gmail.com'

# The title field is totally optional
uptime | apprise -vv \
   'discord:///4174216298/JHMHI8qBe7bk2ZwO5U711o3dV_js'

Enfin, vous pouvez vous faciliter la vie et éviter de mettre vos credentials dans des commandes en utilisant les fichiers de configuration Apprise .

L’API Apprise

Un autre moyen pour utiliser Apprise est de le déployer en tant que micro-service via un conteneur Docker par exemple. Le créateur de Apprise, Chris Caron , nous propose d’ailleurs un fichier docker-compose dans le dépôt qui concerne l'API Apprise, ici .

Cependant, si vous ne souhaitez pas builder vous-même votre image Docker, Chris Caron en maintient une mise à disposition sur le dockerhub .

Une fois votre serveur d’API Apprise en place, vous pourrez lui envoyer des requêtes et il se chargera d’envoyer les notifications aux services paramétrés.

L’API Apprise a deux grands modes de fonctionnement :

• Stateless
• Persistent storage

Pour ce dernier mode, il vous sera utile pour sauvegarder une configuration ou un ensemble d’URL Apprise que vous pourrez associer à une {KEY}. La configuration est persistante, vous pourrez l’effectuer entièrement via une interface web pour ensuite l’exploiter via des appels API. Les possibilités sont vraiment nombreuses !

L’intégration de Apprise dans BorgWarehouse

Coder me passionne, mais apprendre et comprendre le fonctionnement d’un service comme Apprise pour ensuite réfléchir à réaliser son intégration de la bonne manière dans BorgWarehouse a été tout aussi passionnant. Après avoir passé quelque temps à lire la documentation de Apprise et à tester la librairie, j’ai donc cherché comment intégrer Apprise de la bonne manière dans BorgWarehouse pour que l’expérience utilisateur soit la meilleure.

Pour l’intégration des URLs de service, j’ai choisi d’utiliser un formulaire avec un textarea permettant à l’utilisateur de rentrer autant d’URLs qu’il le souhaite. Pour l’aider dans la construction de ses URLs personnels, j’ai fourni un lien vers la documentation de Apprise.

Enfin, j’ai décidé de supporter à la fois le mode “Package” si l’utilisateur décide d’utiliser Apprise via le paquet Python, mais également le mode “API Stateless” si l’utilisateur préfère utiliser un conteneur Docker.

Bien évidemment, un bouton de test d’envoi de notification était de rigueur pour que l’utilisateur puisse bien valider ses réglages.

Conclusion

Je vous ai présenté en grande partie Apprise, son fonctionnement et mon cas d’usage avec BorgWarehouse. Bien entendu, ce logiciel permet de multiples autres usages et je vous laisse explorer le README pour pouvoir bien saisir le potentiel de cette incroyable librairie.

Je remercie particulièrement Chris Caron pour cette librairie et son travail ainsi que toute la communauté de contributeurs autour de ce joli projet qui permet d’améliorer encore l’expérience de BorgWarehouse.