Focus sur les technologies utilisées pour la publication du projet d’établissement 2024-2028 de l’Abes

Au cours de l’année 2023, l’Abes a préparé son projet d’établissement pour la période 2024-2028. Une équipe Scrum, composée de 10 agents issus des 3 départements de l’Abes, a été mise en place pour travailler de manière itérative sur l’analyse des produits et services de l’Abes, le recueil des besoins utilisateurs, des propositions de services et enfin la rédaction du document de projet. 

Pour cette dernière étape, un site web public, doté d’un système permettant aux utilisateurs de déposer des commentaires, a été mis en place : https://projet2024.abes.fr

Cet article a pour objectif de détailler les technologies utilisées pour la conception de ce site web : 

• Docusaurus, 
• Hypothes.is, 
• CI/CD avec GitHub et Docker
  

Docusaurus 

Le socle du site est le logiciel libre Docusaurus (dans sa version 2) dont la devise est : « Construisez rapidement des sites web optimisés, concentrez-vous sur votre contenu.” 

Il s’agit d’un logiciel très populaire – https://docusaurus.io/showcase – dans le monde de l’IT maintenu par les développeurs de Facebook. Son principal cas d’usage est de simplifier la création et la maintenance de documentation en ligne. Il permet de générer des sites web statiques, fluides au niveau de la navigation et optimisés pour le référencement web.

Le workflow Docusaurus pour la publication du contenu est le suivant : 

1. L’auteur rédige ou modifie un fichier au format markdown (syntaxe wiki devenue très populaire avec l’arrivée de GitHub). 

• • Voici le fichier markdown du texte du projet 2024-2028 de l’Abes : https://github.com/abes-esr/projet2024/blob/develop/docs/projet2024.md

• • Et voici ce même fichier markdown en format brut (sans prévisualisation) : https://raw.githubusercontent.com/abes-esr/projet2024/develop/docs/projet2024.md

      2 – Le système de compilation de Docusaurus va ensuite générer les pages statiques HTML, CSS, JS du site web à partir des fichiers markdown. Cette opération est automatisée à l’aide  des technologies  CI/CD : Github & Docker.

Les fichiers markdown – qui intègrent le contenu du site – sont consignés dans un dépôt GitHub dédié : https://github.com/abes-esr/projet2024. Les contenus peuvent être modifiés à tout moment, que ce soit directement via Git ou via l’interface wysiwyg de GitHub.

Comme pour tous les développements opensource de l’Abes, nous avons suivi le workflow GitFlow pour déployer le site du projet sur les 3 environnements (développement, test, production) en préservant une correspondance entre les branches et tags du GitFlow et l’environnement cible. Voici par exemple ce que cela donne pour l’application « projet2024 » :  

• Environnement « dev » (développement) : toutes les modifications de contenus (fichiers markdown) et de configuration du site web sont réalisées sur la branche « develop » qui se retrouve alors automatiquement déployée sur l’URL suivante : https://projet2024-dev.abes.fr  (uniquement accessible depuis le réseau interne de l’Abes) 
• Environnement « test » : une fois les modifications prêtes à être testées, on fusionne la branche « develop » dans la branche « main » et l’ensemble se retrouve alors automatiquement déployé sur l’URL suivante : https://projet2024-test.abes.fr  (uniquement accessible depuis le réseau interne de l’Abes) 
• Environnement « prod » (production) : une fois les tests validés sur l’environnement précédent, une release (un tag git) est générée qui permet un déploiement sur l’URL de production : https://projet2024.abes.fr   

Ce système, dont les technologies sont détaillées dans le chapitre « CI/CD : Github & Docker », permet d’assurer une autonomie au rédacteur qui, ainsi, ne dépend pas d’un informaticien pour publier les contenus. 

Nous avons également utilisé la technologie Mermaid, disponible par défaut sous forme d’un plugin Docusaurus. Cette fonctionnalité, qui permet de générer des diagrammes au moyen d’une syntaxe textuelle spécifique, a servi pour tracer les diagrammes de Gantt de la partie « calendrier du projet » : https://projet2024.abes.fr/docs/2.4/projet2024-calendrier  

 

 

Hypothes.is 

La seconde technologie utilisée est le logiciel libre Hypothes.is, dans sa version SaaS, dont la devise est : Collaborer avec n’importe qui, de n’importe où (« Collaborate with anyone, anywhere. ») 

Ce logiciel, au code source ouvert – https://github.com/hypothesis – permet de déposer des commentaires partout sur le web. Pour le site du projet de l’Abes, nous avons utilisé la version publique hébergée en SaaS également proposée par l’entreprise Hypothes.is.

Pour la publication de commentaires sur le site « projet2024 », le wokflow Hypothes.is est le suivant : 

• L’utilisateur crée un compte sur la plateforme SaaS Hypothes.is 
• Il peut alors surligner le texte qu’il souhaite commenter puis rédiger un commentaire qui sera accessible publiquement dans le panneau latéral droit 
• De la même manière, il peut cliquer sur les commentaires des autres utilisateurs et y répondre 

 

Ce système, complètement indépendant de la technologie Docusaurus, est pratique du fait qu’il évite de devoir embarquer dans Docusaurus un système potentiellement complexe pour gérer la création de compte et l’authentification. Il permet de déposer et de répondre à des commentaires de manière très ergonomique. 

Enfin, l’intégration d’Hypothes.is dans le site web « projet2024 » a été simple et rapide : il a suffi d’ajouter un morceau de javascript embed.js dans les pages du site web et de rédiger un tutoriel à destination des utilisateurs. 

CI/CD : GitHub & Docker 

Le système d’intégration et déploiement continus de l’Abes a permis de compiler, intégrer puis déployer automatiquement ce site web. Ainsi, ce site est déployé de la même manière que les applications ITEM (cf dépôt GitHub),  QualiMarc (cf dépôt GitHub) ou theses.fr (cf dépôt GitHub). 

Pour mettre en place cette CI/CD sur l’application « projet2024 », la première étape a consisté à déposer son code en opensource sur le GitHub de l’Abes – https://github.com/abes-esr/projet2024 – et la seconde  à ajouter deux GitHub Action dans son code source, ce qui permet de : 

• build-test-pubtodockerhub.yml : compiler, tester et publier l’image docker de l’application sur Docker hub –  https://hub.docker.com/r/abesesr/projet2024/ 
• create-release.yml : générer une release, version de l’application respectant le semver. Exemples de releases : https://github.com/abes-esr/projet2024/tags 

Enfin, la troisième étape a consisté à préparer un dépôt GitHub dédié au déploiement de l’application « projet2024 » dans les 3 environnements (développement, test, production) : https://github.com/abes-esr/projet2024-docker 

Ce dernier dépôt comporte trois fichiers clé : 

• docker-compose.yml : contient la description et la configuration statique des différents conteneurs de l’application, soit, dans notre cas, les deux conteneurs suivants : 
  • projet2024 : conteneur principal comportant un serveur web nginx légèrement configuré et dont le rôle est d’exposer les sources HTML/JS/CSS statiques générées par le logiciel Docusaurus dans la phase de CI
  • projet2024-watchtower :  conteneur particulier du fait qu’on le retrouve dans toutes les applications Abes déployées avec cette CI/CD (pour rappel : ITEM, QualiMarc, theses.fr …). Il utilise le logiciel Watchtower – https://containrrr.dev/watchtower – qui permet de scanner toutes les n minutes dockerhub pour vérifier si une nouvelle version de l’application est prête à être déployée ou non. C’est ce conteneur qui permet de faire le “CD” de “CI/CD”. 

• .env-dist : contient les paramètres de l’application pouvant être personnalisés entre les trois environnements de déploiement (dev, test et prod). 
• README.md :  contient les procédures d’exploitation de l’application (comment l’installer, la démarrer, la stopper, la superviser, la sauvegarder) 

Conclusions

L’utilisation des technologies Docusaurus et Hypothes.is a constitué une première à l’Abes. Nous avons particulièrement apprécié la facilité et la rapidité de production  (mise en œuvre d’environ 4 jours de travail à 3 personnes) d’un site web fonctionnel doté d’une navigation rapide et moderne (et responsive). 

Pour sa part, le système d’intégration et déploiement continus (CI/CD), sur lequel repose l’ensemble des nouvelles applications développées à l’Abes, a permis de publier facilement et sereinement les versions successives du projet d’établissement (versionnements Git et Docusaurus). 

En revanche, la fonctionnalité d’édition/publication depuis le format markdown – qui représente pourtant un des points forts de Docusaurus pour gérer collaborativement l’édition et la publication de documentation sur un site web – n’a pas été utilisée : de fait, pour collaborer sur le contenu du document de projet, il a été décidé d’utiliser le logiciel Microsoft Word associé à OneDrive, bien connu des membres de l’équipe du Projet d’établissement. L’intégration des contenus dans le site web final n’a donc pas été aussi fluide et intégrée que cela aurait pu l’être en l’éditant directement à partir du markdown. De fait, pour réaliser la conversion automatique de .docx vers markdown (cf procédure), le logiciel Pandoc a été utilisé.

Le type d’architecture présentée dans cet article nous a donc convaincus. Elle est actuellement utilisée à l’Abes pour la publication de la documentation d’un projet interne et servira également pour la publication d’un site web dédié à la politique de développement informatique de l’Abes, actuellement géré directement en markdown depuis GitHub.