Serveur web de documentation
| Présentation et définition du projet
Cette page a pour but de détailler un projet que j’ai réalisé en entreprise dans le cadre de mon alternance “Expert en ingénierie logiciel” à l’école Iscod.
Ce projet consistait à concevoir un serveur web permettant l’accès aux documentations techniques des développeurs de mon équipe.
La documentation dans une équipe de développeurs est primordiale et permet surtout de limiter la dette technique. Il existe plusieurs types de documentation, ce projet concerne uniquement la documentation technique des outils internes. La documentation technique détaille et explique le code. Elle permet aux développeurs de faciliter la compréhension du code ainsi que sa maintenance et son évolutivité.
| Contexte
Dans mon équipe, Sharepoint est utilisé pour toutes les documentations non techniques (procédures support, process, guides utilisateurs, ect..).
Concernant les documentations techniques, il n’existe pas un processus automatique pour les générer. Les développeurs génèrent les documentations en utilisant l’outil Sphinx pour certains outils mais pas de manière systématique. Les documentations sont ensuite déplacées “à la main” dans un répertoire dédié. Enfin, ces documentations sont générées dans un format .html de manière statique. L’accessibilité aux documentations n’était pas intuitive car il fallait renseigner le chemin de fichiers complet dans un navigateur pour accéder à la documentation.
Ce projet m’a été demandé d’être réalisé en autonomie, cependant je pouvais tout de même demander de l’aide si j’avais un point de blocage ou des interrogations.
| Objectifs et enjeux
L’objectif principal était de mettre en place une interface web accessible qui centralise et permet de naviguer vers n’importe quelles documentations techniques. La solution devait être légère, rapide et conteneurisée. L’objectif était d’automatiser le déploiement de l’interface afin de faciliter sa maintenance.
Cette interface avait pour enjeu principal de faciliter l’accessibilité aux documentations et de faciliter la navigation entre plusieurs documentations. L’enjeu personnel était d’acquérir de l’expérience professionnelle dans le développement d’une interface web au niveau frontend et backend.
| Risques
Ce projet ne présentait pas de risque majeur car il n’avait pas d’impact avec la production et je n’avais pas de date limite de réalisation. Cependant, ce projet représentait des défis de logique frontend/backend. Je devais m’assurer de maitriser ce concept afin de mettre en place une solution fonctionnelle et résiliente.
| Etapes du projet
Mise en place de l'environnement de développement
J’ai commencé par cloner le répertoire qui stockait toutes les documentations dans un espace de développement. Ayant des documentations techniques pour des outils Perl et Python, j’ai décidé de créer deux sous-répertoires afin de classifier les documentations dans les bons sous-dossiers.
Choix techniques
J’ai décidé de mettre en place un backend avec la librairie Python Flask et un frontend léger en langage html/css/js sans framework.
Concernant le backend, j’ai utilisé Flask pour sa légèreté et sa capacité à réaliser des traitements de données et implémenter des API.
J’ai choisi de ne pas utiliser de framework pour le frontend car l’interface est simple et représente qu’une seule page. Dans ce cas de projet, cela permet de gagner du temps de déploiement et de limiter la maintenance.
J’ai ensuite choisi Nginx pour permettre de réaliser du reverse proxy et accéder à l’interface via un domaine customisé.
Frontend
L’interface comporte un titre, une description et la liste dynamique de documentations. J’ai choisi un design épuré et des couleurs beige et bleu.
J’ai conteneurisé le frontend via un dossier frontend qui est exposé sur le port 8086. Ce dossier comporte les trois fichiers permettant la conception du visuel de l’interface: index.html, styles.css et script.js.
Le fichier script.js sert à réaliser l’implémentation de la liste dynamique des documentations. Elle permet aussi de défiler dynamiquement les différentes versions des documentations de chaque outil. Pour servir ces logiques le JavaScript appelle les API mises à disposition par le backend.
Backend
Le backend scanne et route les dossiers de documentation à travers des API structurées. Il permet aussi de récupérer des informations liées à la documentation comme sa version ou l’identité du développeur ayant créé la documentation.
Les API sont appelées par le frontend. Lorsque le backend reçoit la requête, il vérifie si le fichier existe toujours, l’ouvre et le renvoie au frontend via une requête HTTP. C’est ensuite le frontend qui s’occupe de l’afficher au niveau du navigateur.
La mise en place de la logique frontend/backend m’a permis de progresser dans la compétence d’algorithmie.
Nginx
Nginx permet de réaliser le « Reverse proxy ». J’ai choisi Nginx car même si Flask peut réaliser des redirections de requêtes, celui-ci n’est pas prévu initialement pour cela. Nginx permet aussi de sécuriser l’accessibilité avec l’implémentation d’un certificat SSL.
Sécurité
Au niveau sécurité, l’architecture actuelle permet d’isoler les différents services, de réduire les surfaces d’attaques et d’avoir un backend non exposé grâce au serveur Nginx. Concernant Flask, il permet de contrôler les chemins et d’interdire les tentatives d’accès plus large au système de fichiers.
Enfin Nginx permet aussi un chiffrement HTTPS et un filtrage des requêtes.
| Les acteurs
Ce projet a été réalisé entièrement de manière autonome. En effet, ce projet n’a pas d’impact direct en production et il m’a donc été laissé libre de le mener.
| Les résultats
Ce projet permet aujourd’hui à mon équipe de naviguer facilement dans une interface sobre à travers les différentes documentations techniques. La possibilité de naviguer entre les différentes versions d’une documentation technique est appréciée.
Cette interface permet de gagner du temps et je trouve que les bénéfices encouragent les développeurs à générer des documentations de manières plus récurrentes.
| Les lendemains du projet
Cette interface pourrait évoluer afin de répondre à un besoin client. En effet, l’équipe client doit maintenant avoir accès à certaines documentations. Elles utilisent alors l’ancienne méthode car pour l’instant il n’existe pas de système de gestion des droits. Cette fonctionnalité sera surement ajoutée prochainement.
Je pense qu’un système d’authentification devrait être mis en place pour tous les utilisateurs. On pourrait imaginer intégrer une connexion via le SSO (Single Sign-On) de l’entreprise afin de donner des droits en fonction des équipes.
| Mon regard critique
Je trouve que ce projet a un réel bénéfice et permet de limiter les actions manuelles qui sont parfois redondantes. En tant que développeur encore junior, je me suis rendu compte de l’importance de la documentation technique, et de les mettre en avant à travers ce projet a été très satisfaisant.
Dans un contexte plus global, je suggérerai de mettre en place un système de déploiement de documentations automatiques directement intégré dans la CI/CD des outils. Cela permettrait d’avoir une banque de documentations plus fournies et plus à jour. Dans ce cas, peut-être que cette solution devra évoluer pour supporter ce besoin.