Introduction

Ce dépôt contient le backend de Sigma, le successeur de Frankiz, un site étudiant permettant de gérer les groupes et les étudiants du plateau de Saclay.

Pour obtenir une copie de ce dépôt, clonez-le avec

git clone git@gitlab.binets.fr:br/sigma-backend.git

ou git clone https://gitlab.binets.fr/br/sigma-backend.git, puis installez les dépendances JavaScript avec npm install.

À terme, ce projet doit tourner sur un serveur du BR et servir d'API à un frontend React au code séparé et documenté séparément toute les données nécessaires à son bon fonctionnement (authentification, appartenance à un groupe, droits de visibilité...). Le dépôt pour le serveur front se trouve ici : https://gitlab.binets.fr/br/sigma-frontend (on l'appellera indifféremment serveur front, front ou frontend...)

Ce document détaille les différentes dépendances du projet, sa structure générale, détaille un peu plus des éléments sur la base de données et la documentation ; le code est également commenté en détail.

Dépendances

Une dépendance, c'est un librairie JavaScript dont dépend le code source, soit pour le faire tourner soit pour faire tourner les outils dévs. Les dépendances développeur servent à tester par exemple. On trouve la liste des dépendances dans package.json. Express est un exemple de dépendance normale, nodemon et ESLint (voir infra) sont des dépendances dev (devDependencies).

Les dépendances s'installent avec npm install. Par défaut, toutes les dépendances sont installées. Si la variable NODE_ENV est configurée (vérifier avec la commande echo "$NODE_ENV"),

• la valeur development installe tout
• la valeur production n'installe pas les dépendances développeur

Certaines d'entre elles comme KnexJS ou Webpack doivent être installées globalement :

npm install -g knex
npm install -g webpack
npm install -g eslint

Les dépendances les plus importantes sont knex.js, notre outil de gestion de BDD locale, GraphQL qui sert à communiquer entre serveurs, ldap.js qui interroge le LDAP avec la plupart des données, webpack qui sert à la gestion du serveur. ESlint est un outil de vérification syntaxique.

Le serveur utilisé est express.js ; il est configuré dans server.js puis lancé sur le port 3000 dans index.js.

Configuration LDAP

L'API de Sigma nécessite de se connecter au LDAP Frankiz, à la fois pour obtenir des données et pour l'authentification des utilisateurs. Cela est fait à l'aide de la librairie ldapjs pour faire les requêtes au LDAP et passportJS pour l'auth.

• La configuration LDAP de base se situe dans ldap_config.json.

• Elle est importée dans l'application depuis src/ldap/config.js. Ce fichier écrase la config de base selon les options suivantes :

  Variable	Description	Défaut (ldap_config.json)
  LDAP_URI	URI vers le serveur LDAP.	ldap://frankiz.eleves.polytechnique.fr:389

Exemple

Si on développe en dehors du plâtal et qu'on ouvre un proxy SSH port forwarding du LDAP de Frankiz (frankiz.polytechnique.fr:389) vers localhost:8389, on s'y connecte en définissant

export LDAP_URI=ldap://localhost:8389

et le fichier config.js s'occupe du reste.

Panneau d'administration

Il est accessible au path /adminview/admin ; n'importe quel path devrait rediriger dessus, ou alors vers /adminview/login. Les identifiants à utiliser sont ceux de Frankiz. L'authentification se fait par le LDAP Frankiz.

Accès direct à la BDD via knex

Le panneau d'administration sert (ou plutôt, servira à terme) à accéder directement à la BDD propre de sigma. On accède à la table table_name par une requête GET à /adminview/db/table_name' et aux colonnes columns de cette table par une requête GET à /adminview/db/table_name?columns=columns. Ces pages sont protégées pour n'être accessibles qu'en étant authentifié.

GraphiQL et Voyager

A partir du panneau d'admin, en faisant des requêtes GET à /graphiql et /voyager respectivement, on accède à GraphiQL et à GraphQL Voyager. Ces pages sont protégées pour n'être accessibles qu'en étant authentifié.

Scripts

Les scripts sont des instructions en ligne de commande que l'on peut faire tourner avec la commande npm run. Ce sont des raccourcis pour gagner du temps sur des opérations un peu longues. Ils sont définis dans package.json.

Les plus importants sont détaillées ci-dessous (ne pas oublier npm install déjà mentionné plus tôt) :

On utilisera Webpack pour transpiler le fichier source src/index.js en build/bundle.js qui est suit la syntaxe ES5 compatible Node. Pour ça, on utilise :

• npm run build qui exécute la commande webpack avec le fichier de configuration webpack.config.js, ou
• npm run watch qui recompile automatiquement dès que le code est modifié.

Démarrer le serveur

Pour faire tourner le serveur, lancer

npm start

démarre le serveur compilé build/bundle.js avec nodemon, outil dév, et le redémarre automatiquement après modification.

Donc, lancer npm run watch dans un terminal et npm start dans un autre permet de recompiler le serveur et le relance automatiquement.

Le script pour faire tourner JSDoc et régénérer la documentation est : npm run doc

Documentation

La documentation détaillée du projet est ici. Elle a été compilée avec JSDoc sous format hmtl selon le fichier de configuration configfile_doc.json à la racine du projet.

Les fichiers compilés se situent dans doc avec leurs fichiers image. Par nature de l'outil JSDoc il est facile de documenter en détail des fonctions .js mais plus compliqué de documenter un fichier.

A la fin de ce fichier JSDoc rajoute les commentaires placés dans chacun des fichiers et des hyperliens pour y accéder.