Skip to content
Snippets Groups Projects
Select Git revision
  • master default
  • 82-retravailler-le-type-message
  • add_adminview_tools
  • stable
  • v0.1
5 results
Blame Permalink
Forked from an inaccessible project.
README.md 17.05 KiB

pipeline status

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 avoir un guide détaillé de l'installation de l'environnement de dev, voir ce carnet.

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

Installer les dépendances npm

On utilise un serveur node.js avec express.js. 1 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

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 et TSLint, pour le développement, outils de vérification syntaxique.

Pour pouvoir initialiser la BDD PostgreSQL avec les migrations du repo, il faut installer la dépendance knex.js globalement :

sudo npm install -g knex

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

sudo apt install postgresql

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. En deux mots :

Certains de ces fichiers de configurations ont une version "distribution" en "_dist" qui permet de les partager (le reste du temps ils sont dans le .gitignore), quitte à les renommer et à les modifier en local.

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 pour 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>"
}

On peut s'inspirer de ldap_credentials_dist.json.

  • 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 (ldap.eleves.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.ts s'occupe du reste.

Variables d'environnement

Variable Description Défaut
NODE_ENV Type de l'environnement pour node : development ou production development
TARGET_ENV Config choisie pour la BDD et le LDAP : development, staging ou production .env
HOST Addresse sur laquelle le serveur écoute des requêtes. index.ts
PORT Port sur lequel le serveur écoute .env
LDAP_URI URI vers le serveur LDAP. ldap_config.json
DB_HOST Addresse de la base de données. knexfile.js
DB_USER Utilisateur de la BDD knexfile.js
DB_PASSWD Mot de passe de la BDD knexfile.js
DB_DATABASE Base sur laquelle se connecter knexfile.js

Certaines variables doivent etre définies dans un fichier .env. On peut se contenter de recopier .env_dist avec cp .env_dist .env.

Par ailleurs, 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 (cela écrase la valeur dans la session, mais seulement pour cette commande) : 
    KEY=value npm start
  • dans un fichier .env (plus faible niveau, n'écrase jamais une valeur déja existante) : 
    KEY1=value1
KEY2=value2
...