README.md

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.

Image 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

avec un LDAP custom :

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

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 app.ts puis lancé sur le port 3000 dans index.ts.

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/config.ts.
• Si la variable d'environnement LDAP_URI est définie, l'adresse où trouver le LDAP est remplacée.

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