@@ -9,6 +9,8 @@ Ce dépôt contient le _backend_ de Sigma, le successeur de Frankiz, un site ét
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 :
On utilise un serveur node.js avec [express.js](https://expressjs.com/). [^server]
Utiliser Node.js permet d'utiliser facilement [*npm*](https://www.npmjs.com/)(Node Package Manager). Une "dépendance" est un package utilisé dans le projet.
...
...
@@ -48,7 +48,77 @@ Et une dépendance supplémentaire, PostgreSQL (linux est supposé) :
sudo apt install postgresql
```
### Setup la BDD 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 :
*[`package.json`](../package.json) et [`package-lock.json`](../package-lock.json) : gestion des dépendances usuel
*[`tsconfig.json`](../tsconfig.json) : configure la compilation de fichiers Typescript en Javascript
*[`tslint.json`](../tslint.json) : configure tslint, utilisé plutôt que tsc dans le projet final
*[`.env`](../.env) : définit les variables d'environnement et ports utilisés...
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](http://ldapjs.org) pour faire les requêtes au LDAP et [passportJS](http://www.passportjs.org/) pour l'authentification.
* La configuration LDAP de base se situe dans [ldap_config.json](../ldap_config.json).
* Les identifiants utilisés pour authentifier le serveur au LDAP sont dans [ldap_credentials.json](../ldap_credentials.json). Ils prennent la forme suivante:
On peut s'inspirer de [ldap_credentials_dist.json](../ldap_credentials_dist.json).
* Elle est importée dans l'application depuis [src/ldap/internal/config.ts](../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](http://jxplorer.org/) et gérant ses propres logs (voir [ce blog](https://www.vincentliefooghe.net/content/openldap-gestion-des-logs)).
**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** |
| ------ | ------ | ----- |
| NODE_ENV | Type de l'environnement pour node | `development` |
| TARGET_ENV | Type de l'environnement ciblé : `development`, `staging` ou `production` | [.env](../.env) |
| LDAP_URI | URI vers le serveur LDAP. | [ldap_config.json](../ldap_config.json) |
| HOST | Addresse sur laquelle le serveur écoute des requêtes. | [index.ts](../src/index.ts) |
| DB_HOST | Addresse de la base de données. | [.env](../.env) |
| DB_PASSWD | Mot de passe de la BDD | [.env](../.env) |
Certaines variables doivent etre définies dans un fichier `.env`. On peut se contenter de recopier [.env_dist](../.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`) :
```bash
export KEY=value
```
* au moment de lancer l'application :
```bash
KEY=value npm start
```
* dans un fichier [`.env`](https://www.npmjs.com/package/dotenv) :
```dotenv
KEY1=value1
KEY2=value2
...
```
## 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" :
...
...
@@ -63,10 +133,13 @@ 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`.
- 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`.
-`sudo nano /etc/postgresql/<version>/main/pg_hba.conf` (en tant qu'utilisateur normal)
- remplacer tous les `peer` par `md5`
- redémarrer le serveur postgres : `sudo /etc/init.d/postgresql restart`
- Si vous souhaitez utiliser d'autres noms que "sigma" et "sigma_dev" : ça ne pose pas de problème, il vous faudra simplement modifier [.env](../.env).
- Sortir de l'utilisateur `postgres` avec CTRL + d
Exécuter les *migrations* et les *seeds* de knex :
Exécuter les *migrations* et les *seeds* de knex (dans le dossier `db`) :
```bash
# construire le schéma de la BDD, i.e. définir les tables et leur structure.
knex migrate:latest
...
...
@@ -77,7 +150,7 @@ knex seed:run
Voilà, vous avez une base de données à jour !
### Démarrer le serveur
## Démarrer le serveur
Dire à webpack de build le projet (build le bundle `../build/bundle.js`) :
```bash
npm run dev # en mode developpement
...
...
@@ -119,78 +192,19 @@ Les plus importants sont détaillées ci-dessous :
-`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 start_prod` : lancer le serveur avec Node
-`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 lint` : discontinué
-`npm run eslint` : vérifier la syntaxe de tous les fichiers .js du dossier src/
-`npm run tslint` : vérifier la syntaxe de tous les fichiers .ts du dossier src/
-`npm run tsfix` : vérifie et corrige
-`npm run tsc` : compile le code TypeScript
-`npm run test` : démarre les tests unitaires
`npm run start` démarre en fait le serveur buildé [`build/bundle.js`](../build/bundle.js) avec [nodemon](https://nodemon.io/), 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. En deux mots :
*[`package.json`](../package.json) et [`package-lock.json`](../package-lock.json) : gestion des dépendances usuel
*[`tsconfig.json`](../tsconfig.json) : configure la compilation de fichiers Typescript en Javascript
*[`tslint.json`](../tslint.json) : configure tslint, utilisé plutôt que tsc dans le projet final
*[`.env`](../.env) : définit les variables d'environnement et ports utilisés...
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](http://ldapjs.org) pour faire les requêtes au LDAP et [passportJS](http://www.passportjs.org/) pour l'authentification.
* La configuration LDAP de base se situe dans [ldap_config.json](../ldap_config.json).
* Les identifiants utilisés que authentifier le serveur au LDAP sont dans [ldap_credentials.json](../ldap_credentials.json). Ils prennent la forme suivante:
* Elle est importée dans l'application depuis [src/ldap/internal/config.ts](../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](http://jxplorer.org/) et gérant ses propres logs (voir [ce blog](https://www.vincentliefooghe.net/content/openldap-gestion-des-logs)).
**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.
