SRS - Gestionnaire de packages

Voici la fiche SRS du Projet 2017 : Gestionnaire de package.

Page d'accueil du projet

= Équipe =
 * Rémi Gattaz
 * Germain Lecorps (Chef de Projet)
 * Thibaut Nouguier
 * Régis Ramel (Scrum Master)

= Description générale =

Le but du projet
Le but de ce site est de fournir une plateforme de rencontre et de mise en relation des particuliers ou des professionnels qui souhaitent proposer des produits à la vente d'occasion, ou chercher des articles hors des magasins ou sites de vente traditionnels. Ce site a pour but d'être accessible et facile d'utilisation pour les personnes qui n'ont pas une grande expérience dans l'utilisation de sites webs.

Fonctionnalités

 * Visualisation des packages disponibles
 * Filtrage sur la visualisation des packages (Mots-Clés, Filière, Matière)
 * Connexion utilisateur
 * Dépôt d'une archive pour la création d'un package par un utilisateur authentifié
 * Suppression d'un package existant par l'utilisateur qui a demandé sa création
 * Création d'un package en traitant l'archive (tar, zip, ...) déposée par un utilisateur
 * Ajouter/Supprimer des packages
 * Ajouter/Supprimer des utilisateurs
 * Mise à jour / maintenance automatique des packages

Étudiant
Personne souhaitant télécharger des packages spécifiques à sa formation

Enseignant
Personne souhaitant créer un package pour sa matière.

Administrateur
Il peut également ajouter des packages ou en supprimer. Il peut aussi accéder à la maintenance des packages en cas d'erreur pendant l'automatisation.

Cas d'utilisations
//TODO

//Nécessite de mettre au point l'IHM

Contraintes générales
Pour déposer un package : Environnement de l'application :
 * Avoir un compte enseignant pour s'authentifier sur la plate-forme
 * Avoir un minimum de connaissances sur les outils qui doivent être déposé pour constituer l'archive
 * Les composants builder et coordinateur sont sur des machines de types Debian (64 bits).
 * Le Repository doit également être un Debian (64 bits)
 * Le traitement des archives doit s'effectuer avec un langage de script (shell, ruby, perl).

= Fonctionnement des composants =

Structure de l'application
Le schéma de la structure de l'application est disponible ici.

Liste des packages
Cette page sert aux utilisateurs à consulter la liste des packages disponibles sur le repository.

En haut de la page, un tutoriel explique aux utilisateurs comment utiliser le repository sur linux, c'est à dire à le rajouter dans les sources de packages, puis à installer les packages avec les commandes "sudo apt-get install ...".

Le reste de la page correspond à la liste des packages disponibles sur le repository, ainsi que des options de filtre pour restreindre la liste à certaines filières, matières, etc.

Dépôt d'une contribution
Cette page consiste en un formulaire à remplir pour proposer une contribution.

En haut de la page, un tutoriel explique aux utilisateurs ce qu'ils doivent saisir dans chacun des champs du formulaire, ainsi que les différents types de dépôts gérés par le système.

L'utilisateur doit d'abord se logguer avec ses identifiants AGALAN, puis effectuer le dépôt de l'outil. Il y a pour cela plusieurs solutions :
 * L'utilisateur dépose un lien Git contenant déjà tout ce dont le système a besoin pour générer un package.
 * L'utilisateur dépose un lien Git ne contenant pas tous les fichiers nécessaires à la création du package.
 * L'utilisateur dépose un lien vers une archive (tarball) sur le site de téléchargement de l'outil.
 * L'utilisateur dépose directement la tarball en mode dépôt de fichier.
 * L'utilisateur n'a pas su trouver un lien pour télécharger l'outil. Il peut alors déposer un lien vers le site de l'outil, pour laisser au gérant du système le soin de trouver les fichiers dont le système a besoin.

De plus, l'utilisateur doit renseigner le nom du package, le numéro de version, l'architecture (32/64 bits), le maintainer (responsable), la filière pour laquelle cet outil est requis (ex : RICM5), la matière pour laquelle cet outil est requis (ex : TMA). Il est possible de laisser une description expliquant l'utilité de l'outil, ainsi que de spécifier des dépendances.

La contribution doit ensuite être soumise pour être envoyé à l'administrateur pour la validation.

Administration
Cette page propose des outils d'administration du repository, tels que :
 * La liste des packages disponibles
 * La page de validation/refus des contributions
 * Une interface de monitoring (logs)

Controller
Le Controller est le composant central du BackEnd. C'est celui qui va gérer toutes les interactions au cœur de l'application. Il fourni une API Rest ainsi qu'une interface en ligne de commande (CLI). Nous avons choisi de le développer en Javascript.

Ses trois fonctions principales sont :
 * La création des liens Git à envoyer au Builder pour générer les packages
 * La copie des packages .deb générés par le Builder dans le Repository
 * La mise à jour automatique des packages déjà déposés dans le Repository.

Génération du lien Git
A la réception de la contribution, l'administrateur doit déclencher la génération du package. Le Controller doit alors lancer la génération automatique du lien Git à envoyer au Builder. Selon le type de dépôt, le Controller adapte le traitement :
 * Si le contributeur à déposé un lien Git déjà utilisable par le Builder, il n'y a rien à faire : le lien est directement envoyé au Builer.
 * Si le contributeur à déposé un lien Git, une tarball, ou un lien vers une tarball qui ne contient pas tous les fichiers nécessaires au Builder, le traitement consiste à analyser le contenu du dépôt Git (ou de la tarball) pour construire les fichiers manquants, et ainsi générer un lien Git correct pour l'envoyer au Builder.
 * Si le contributeur dépose simplement une demande pour un outil, c'est à l'administrateur de trouver les ressources nécessaires pour installer l'outil.

Une fois le lien Git généré et envoyé au Builder avec un Tag qui correspond au commit à partir duquel le Builder doit travailler, le Controller attend un retour :
 * Si la création s'est bien passé, l'administrateur reçoit un accusé de réussite, et le Controller dépose le fichier .deb sur le Repository.
 * Si la création a échoué, l'adminstrateur reçoit un accusé d'échec ainsi que les logs d'erreur. Il peut alors intervenir manuellement pour résoudre le problème en générant lui-même le lien Git.

Copie des packages dans le Repository
Une fois que le Builder a généré les packages, ceux-ci sont déposés avec l'outil DPUT.

Mise à jour automatique des packages
Le fonctionnement des mises à jour automatique dépend du type de dépôt au moment de la contribution :
 * Si le contributeur a déposé un lien (Git ou tarball), alors la recherche de mises à jour est possible :
 * Lien Git : il est possible de savoir si une nouvelle version de l'outil est disponible sur un dépôt Git.
 * Lien de téléchargement de tarball : Si le lien de téléchargement est dynamique, c'est à dire s'il renvoi la dernière version de l'outil disponible, alors le système peut détecter une mise à jour en téléchargeant la tarball, et en la comparant avec le dépôt initial.
 * Si le contributeur a déposé un tarball, la recherche de mises à jour est malheureusement impossible.

Si une mise à jour est disponible, le Controller met à jour le dépôt Git généré à la création du premier package, puis envoi au Builder le nouveau dépôt Git avec le nouveau Tag pour obtenir le package correspondant à la nouvelle version de l'outil. Une fois le nouveau package généré, il est déposé sur le Repository avec le numéro de version correspondant.

Builder
Le Builder est le composant qui va gérer la création du package. Il utilise les lien Git envoyé par le Controller pour obtenir les fichiers sources de l'outil à packager.

Le Builder est basé sur un composant Docker de génération de Package (choix à définir). La construction consiste en une suite de commande Unix, c'est pourquoi nous avons choisi le Shell.

Nous avons décidé qu'une fois le package crée, le Builder le renvoi au Controller au lieu de directement le copier sur le Repository. Nous avons fait ce choix pour ce soit le Controller qui effectue les copies sur le Repository.

Repository
Le Repository contient les fichiers nécessaires aux stockages des packages :
 * Les packages (fichiers .deb)
 * Les clés GPG (Voir si l'on peut générer plusieurs clés publiques à partir d'une clé privée)
 * Les hash des clés

Le Repository est mis à disposition du public grâe à une url. L'accès se fait grâce à une clé GPG et les ports 80/443 (HTTP/HTTPS).

= Réalisations =

Frontend
Visualisation des packages
 * Fonctionnel :
 * L'affichage des packages à partir de la base de données (API) est fonctionnelle.
 * Les différents filtres pour trier les packages sont fonctionnels.
 * La recherche par mots-clés est opérationnelle.

Visualisation des tickets
 * Fonctionnel :
 * Fonctionnement similaire à la visualisation des packages. Les fonctionnalités disponibles sont les mêmes.
 * Un système de vote a été mis en place pour indiquer la "popularité" d'un package.
 * Un bouton est affiché si l'utilisateur est administrateur.
 * Le système de vote +/- est fonctionnel. L'utilisateur peut ajouter/supprimer/mettre à jour son vote.
 * A faire :
 * Implémenter le système de tri par résultat des votes.

Formulaire de dépôt d'un package
 * Fonctionnel :
 * Il est possible de remplir le formulaire pour ajouter un ticket. Le ticket est ajouté à la base de données sous forme d'un fichier JSON.
 * A faire :
 * Le ticket actuellement ajouté n'est pas lié à du code (tarball, git...). Il faut donc lier les information du package au code qui deviendra le package.

FAQ
 * Fonctionnel :
 * La page de FAQ est lue à partir de deux fichiers JSON contenant les différents tutoriels ainsi que les questions de la FAQ pour faciliter la modification du contenu en fonction des besoins des utilisateurs.

= Annexes =

Glossaire
BackEnd : Le BackeEnd est la partie de l'application invisible de l'utilisateur. C'est la partie qui traite, stocke, et mets les données à disposition Debian : Debian est une famille de distribution Linux.

FrontEnd : Le FrontEnd est la partie de l'application visible par l'utilisateur, c'est à dire le site Web qui permet les interactions de l'utilisateur avec le système.

Git : Git est un système de dépôt collaboratif de fichier.

Identifiants AGALAN : Les identifiants AGALAN sont les identifiants qui permettent de se connecter à tous les services universitaires.

Maintainer : Le Maintainer est la personne responsable de la maintenance du package, c'est à dire les mises à jour régulières du package, ainsi que du support.

Package : Un Package est un outil Linux qui s'installe via une commande de type "apt-get install ..."

Repository : Un Repository est un serveur qui contient des packages Linux. Il permet aux utilisateurs d'installer ces packages avec la commande "apt-get install".

Tarball : Une tarball est une archive de fichiers (zip, rar, tar.gz, ...).

Structure du SRS
The document is based on template of the Software Requirements Specification (SRS) inspired of the IEEE/ANSI 830-1998 Standard.

References :

 * http://www.cs.st-andrews.ac.uk/~ifs/Books/SE9/Presentations/PPTX/Ch4.pptx
 * http://en.wikipedia.org/wiki/Software_requirements_specification
 * IEEE Recommended Practice for Software Requirements Specifications IEEE Std 830-1998