Sigma - serveur backend

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.

À 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...)

Le but des lignes qui suivent est de permettre au lecteur de rapidement mettre en place et lancer un sigma local et se familiariser avec son administration. Comment obtenir la documentation détaillée du projet est expliqué à la fin de ce document.

Pour obtenir une copie du projet, cloner le dépôt par :

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

Démarrer le serveur (en mode développement)

Installer les dépendances npm

On utilise un serveur node.js avec express.js. ¹ Utiliser Node.js permet d'utiliser facilement npm (Node Package Manager). Une "dépendance" est un package utilisé dans le projet.

On trouve la liste des dépendances dans package.json. Express est un exemple de dépendance normale, utilisée en production ; nodemon et ESLint (voir infra) sont des dépendances dev (devDependencies), utilisées seulement en mode développement.

Les dépendances s'installent avec npm install. Cette commande a deux comportements possibles selon la valeur de la variable NODE_ENV (vérifier avec la commande echo "$NODE_ENV"):

• si NODE_ENV n'est pas configuré : on installe tout
• si NODE_ENV == development : on installe tout
• si NODE_ENV == production : on n'installe pas les dépendances développeur

Pour installer les dépendances spécifiées dans package.json il faut donc lancer :

npm install

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 principales utilisées sont

• knex.js, qui permet de construire des requêtes SQL facilement,
• GraphQL, qui fournit une couche d'abstraction pour l'échange de données frontend-backend,
• ldap.js, qui permet d'interroger un serveur LDAP,
• webpack, qui compile et optimise tout le code source javascript en un bundle.js,
• ESlint, pour le développement, outil de vérification syntaxique.

Et une dépendance supplémentaire, PostgreSQL (linux est supposé) :

sudo apt install postgresql

Setup la BDD PostgreSQL

La BDD PostgreSQL est utilisée pour stocker permissions, écoles des utilisateurs, annonces et événements.

Créer un rôle PostgreSQL "sigma" :

sudo -u postgres -s
createuser sigma --login --createdb --pwprompt
# penser à répercuter le mot de passe choisi dans `./db/knexfile.js` et `./db/knex_init.js`

Créer une base de données PostgreSQL "sigma_dev" :

createdb sigma_dev -U sigma -W

• Si vous n'arrivez pas à vous connecter (createdb: could not connect to database template1: FATAL: Peer authentication failed for user) : mettre à jour votre fichier pg_hba.conf.
  • voir https://stackoverflow.com/questions/1471571/how-to-configure-postgresql-for-the-first-time
• Si vous souhaitez utiliser d'autres noms que "sigma" et "sigma_dev" : ça ne pose pas de problème, il vous faudra simplement modifier ../db/knexfile.js et ../db/knex_init.js.

Exécuter les migrations et les seeds de knex :

# construire le schéma de la BDD, i.e. définir les tables et leur structure.
knex migrate:latest

# insérer des données de test dans la BDD
knex seed:run

Voilà, vous avez une base de données à jour !

Démarrer le serveur

Dire à webpack de build le projet (build le bundle ../build/bundle.js) :

npm run dev # en mode developpement
# ou
npm run build # en mode production

Lancer un serveur express/node :

npm run start # ou le raccourci: npm start

Comme indiqué dans src/index.js, ceci lance un serveur servant l'application express sur le port 3000. Ce serveur va ensuite éxecuter le reste du code comme si il était déployé ou presque.

Alternative : déployer dans un conteneur Docker

L'image Docker est définie dans Dockerfile. Il s'agit d'une distro Alpine avec Node.js et libstdc++. Lors du build les dépendances runtime dont dépend le bundle.js sont installées.

Compiler l'image :

docker build -t sigma-api .

Faire tourner le conteneur :

docker run sigma-api

Idem mais avec un LDAP custom :

docker run -e LDAP_URI=ldap://172.17.0.1:8389 sigma-api

Mode développement / staging / production

TODO Ca a un rapport avec NODE_ENV ?

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 :

• npm run build : transpiler avec Webpack, en mode production
• npm run dev : idem, mais en mode développement
• npm run watch : idem, mais retranspile automatiquement dès que le code est modifié.
• npm run start : lancer un serveur Node avec nodemon
• npm run doc : générer la doc JSDoc
• npm run lint : vérifier la syntaxe de tous les fichiers .js et .ts du dossier src/

npm run start démarre en fait le serveur buildé build/bundle.js avec nodemon, un outil de dév qui le redémarre automatiquement après toute modification du bundle.

Donc, lancer npm run watch dans un terminal et npm run start dans un autre permet de rebuilder et relancer automatiquement le serveur, après toute modification du code source.

Configuration

L'API est conçue pour êtes modulaire et pour fonctionner dans plusieurs environnements.

On peut donc le configurer via des fichiers ou des variables d'environnement.

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'authentification.

• La configuration LDAP de base se situe dans ldap_config.json.
• Les identifiants utilisés que authentifier le serveur au LDAP sont dans ldap_credentials.json. Ils prennent la forme suivante:

{
    "dn": "uid=<username>,ou=eleves,dc=frankiz,dc=net",
    "passwd": "<password>"
}

• Elle est importée dans l'application depuis src/ldap/internal/config.ts.
• Si la variable d'environnement LDAP_URI est définie, l'adresse où trouver le LDAP est remplacée.

Le LDAP de Frankiz est sous OpenLDAP, qui a l'avantage d'être largement utilisée, documentée sur Internet, compatible avec des lecteurs génériques comme JXplorer et gérant ses propres logs (voir ce blog).

Exemple

Si on développe en dehors du plâtal et qu'on ouvre un proxy SSH avec port forwarding du LDAP de Frankiz (frankiz.polytechnique.fr:389) vers localhost:8389, on s'y connecte en définissant : LDAP_URI=ldap://localhost:8389, soit en faisant export LDAP_URI=..., soit en écrivant un fichier .env. Le fichier config.js s'occupe du reste.

Variables d'environnement

Variable	Description	Défaut (ldap_config.json)
LDAP_URI	URI vers le serveur LDAP.	ldap://frankiz.eleves.polytechnique.fr:389
TARGET_ENV	Type de l'environnement ciblé : development, staging ou production	development
HOST	Addresse sur laquelle le serveur écoute des requêtes.	localhost en développement, 0.0.0.0 en staging/prod.
DB_HOST	Addresse de la base de données.	localhost ou 129.104.201.10 en staging/prod.
DB_PASSWD	Mot de passe de la BDD	password

On peut définir ces variables d'environnement, dans l'ordre décroissant de priorité :

• dans sa session de terminal (équivalent à docker run -e KEY=value) :

  export KEY=value

• au moment de lancer l'application :

  KEY=value npm start

• dans un fichier .env :

  KEY1=value1
  KEY2=value2
  ...

Panneau d'administration

Il est accessible par navigateur au path /adminview/admin ; n'importe quel path devrait rediriger dessus.

L'accès y est protégé par une page d'authentification, les identifiants à utiliser sont ceux de Frankiz. Le hruid (i.e. prenom.nom) de l'utilisateur doit de plus être sur une whitelist des hruid autorisés. Pour l'instant cette whitelist est hardcodée dans le code source.

Accès direct à la BDD

Le panneau d'administration sert (ou plutôt, servira à terme) à accéder directement à la BDD propre de sigma, grâce à une API REST. Autrement dit :

• 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.

GraphQL Voyager

L'application Voyager, accessible à /adminview/voyager, permet de visualiser le « graphe » sous-jacent à la structure de l'API.

GraphQL Playground

== Attention, comme tout GraphQL Playground est géré directement par le package apollo-server-express, les requêtes dans le Playground ne sont pas soumises au mêmes règles de permission que dans adminview. (D'ailleurs, /graphql n'est même pas un sous-path de /adminview.) ==

Accéder via un navigateur à /graphql renvoie vers l'application GraphQL Playground.

Il s'agit du même /graphql que l'endpoint de l'API, mais le serveur est configuré de sorte à renvoyer Playground lorsqu'il détecte un accès via navigateur. Les requêtes dans le Playground sont cependant soumises au mêmes permissions que dans l'API GraphQL ². GraphQL Playground est désactivé en production.

Tests

³

Sigma possède une suite de tests unitaires, déstinés à tester les resolvers graphql.

Pour executer les tests, il suffit d'utiliser la commande npm test.

Les tests effectués sont dans test/testData.js, sous la forme d'une liste. Chaque élément contient une requête graphql, et les données qu'elle doit renvoyer. Quand les seed sont modifiées, il faudra modifier les resultats attendus également. Les tests peuvent être créés ou mis à jour en entrant la requête dans graphiql, et en copiant le resultat.

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.

Le script pour faire tourner JSDoc et régénérer la documentation est : npm run doc. Les liens ett images sont faits pour fonctionner en local, donc ne vous étonnez pas si vous avez des surprises en regardant ce README depuis git.

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 chaque execution JSDoc rajoute les commentaires placés dans chacun des fichiers dans la doc de façon structurée. Les notes en Markdown placés dans notes/ sont également rajoutées en tant que tutoriels (voir {@tutorial CONTRIBUTING}).

1. il est configuré dans app.ts puis lancé sur le port 3000 dans index.ts. ↩

2. euuuuh à vérifier... ↩

3. cette fonctionnalité n'a pas été utilisée ni testée depuis beaucoup trop de commits pour que cette partie soit fiable actuellement (2018-12-04). ↩