Quels éléments pour documenter le déploiement d'un projet open source ?
Ce document s’adresse à tous les porteurs de projets de services numériques : il explique le positionnement de l’Incubateur des Territoires en faveur de l’Open Source et propose une méthodologie pour la documentation du déploiement d’un logiciel dont le code est ouvert.
140 VuesVues·2 EnregistrementsEnregistrementsL’Incubateur des Territoires oeuvre en faveur de l’open source, c’est à dire un positionnement philosophique et politique pour garantir les quatre libertés de l’utilisateur :
la liberté d'exécuter le programme, pour tous les usages ;
la liberté d'étudier le fonctionnement du programme et de l'adapter à ses besoins ;
la liberté de redistribuer des copies du programme (ce qui implique la possibilité aussi bien de donner que de vendre des copies) ;
la liberté d'améliorer le programme et de distribuer ces améliorations au public, pour en faire profiter toute la communauté.
Il part du principe qu’un logiciel financé par le contribuable doit être ouvert et mis à disposition de la collectivité. Il s’inscrit dans cette mesure dans le cadre de la Loi pour une République Numérique (2016) ainsi que dans l’esprit de la campagne de la Free Software Foundation Europe “Argent Public Code Public”. Il s’agit donc d’avoir un code source ouvert et accessible en ligne, encadré par une licence libre et dont la notice d’installation, d’administration et d’utilisation soit correctement documentée afin de faciliter sa réutilisation.
L’ouverture du code source d’un logiciel offre plusieurs avantages:
une capacité à être autonome sur la solution ;
des possibilités de personnalisation ;
des améliorations apportées par la communauté ;
une mutualisation de la maintenance ;
une absence de coût de licence ;
une transparence de fonctionnement, des échanges et de la sécurité ;
un intérêt pédagogique grâce à la liberté d'étudier la mécanique interne du logiciel ;
la consolidation de biens communs qui permettent de favoriser l'innovation.
L’open source incite donc à un respect des valeurs fondamentales autour du partage, de la coopération et de l'entraide. Un projet dont les sources sont ouvertes permet à un autre acteur de réutiliser un outil existant et de ne pas réinventer la roue. Dans le principe, un projet open source est donc fait pour être partagé.
En tant que porteur, vous avez été financés dans le cadre de l'accompagnement France Relance: vous devez donc ouvrir votre projet. L’idée est que celui-ci puisse être réutilisé par d’autres acteurs, de la manière la plus simple possible. Une documentation est ainsi nécessaire pour permettre son déploiement et son utilisation par tout acteur intéressé, à l’image d’un meuble IKEA et de sa notice.
Le but de ce document est de présenter quelques pistes à suivre pour documenter le déploiement de son projet open source.
L'étape de Build
Si votre projet comporte une étape de build, il est nécessaire de la documenter.
À noter que cela ne concerne pas seulement les langages compilés, mais tout projet dont les sources doivent être transformées par un process avant de pouvoir être utilisé dans un environnement de production.
Cela concerne par exemple de façon non exhaustive :
Un frontend en JavaScript devant être minifié
Les projets en TypeScript devant être transpilés
Les langages devant être compilés comme Rust, C, Java
Les projets dépendant de librairies maintenues par la communauté open source qui doivent être installées auparavant
Les projets à déployer via des conteneurs
#Dépendances
Quelle est la plateforme/l'OS préconisée pour l'étape de build ? Sur quelle version ? Quels logiciels/paquets/librairies doivent être installées pour le build ? Des versions spécifiques sont-elles nécessaires ?
Comment installer des dépendances du projet s'il y en a ? Quelle commande lancer avec quelles options ? (composer, cake, gem, pip, npm...)
#Configuration
Faut-il configurer le build du projet ? Par exemple, un frontend statique devant être configuré avec l'URL du backend. Comment configurer ces options ? Via quel(s) fichier(s) ou quelle(s) variable(s) d'environnement ?
#Build
Comment lancer le build du projet ? Quelles options disponibles ? Quelle commande ? Quel script lancer ?
Où se trouve le résultat du build ? Quels fichiers devront être conservés pour le déploiement ?
L'environnement de déploiement
Cette étape concerne principalement les projets web, que ce soit en interne ou sur internet.
#Dépendances
Quelle est la plateforme/l'OS préconisée pour déployer le projet ? Sur quelle version ?
Quels logiciels/paquets/librairies doivent être installées pour le déploiement ? Des versions spécifiques sont-elles nécessaires ?
Le projet a-t-il des dépendances d'infrastructure ? En quelle version ? Par exemple :
Base de données : MariaDB, MySQL, PostgreSQL... Des extensions sont-elles nécessaires ? Comment les installer/configurer ?
Redis
Memcached
Authentification via un SSO. Quel type ? OIDC, LDAP, SAML... Quels sont les rôles/groupes/attributs nécessaires ?
#Configuration
Faut-il servir les projets au moyen d'un serveur web type Apache ou Nginx ? Comment le configurer ?
Le projet a-t-il besoin d'être configuré pour le déploiement ? Quelles valeurs par défaut, et quelles options importantes ? Des recommandations de sécurité ? Où doit s'effectuer cette configuration ? Par exemple :
Via des variables d'environnement
Via un fichier de configuration. Quel est son format ? Où doit-il se trouver ?
Le projet doit-il avoir accès à un disque pour persister des fichiers ? Par exemple ceux uploadés par les utilisateurs ? Quel espace est recommandé ? Quelles permissions donner à ces fichiers ?
#Exécution
Où doivent être placées les sources/le résultat de build pour déployer le projet ? Comment démarrer le process/lancer le service ? Avec quel nom d'utilisateur le processus doit-il être lancé ? Comment créer les premiers utilisateurs/administrateurs ?
🌐 Pour en savoir plus sur les offres et les services public numériques portés par l’Incubateur des Territoires, rendez-vous sur https://incubateur.anct.gouv.fr/