Skip to content

Latest commit

 

History

History
281 lines (187 loc) · 7.82 KB

INSTALLATION.md

File metadata and controls

281 lines (187 loc) · 7.82 KB
Raw

Installation

Prérequis

Vous devez au préalable avoir correctement installé les logiciels suivants :

  • Git (2.6.4)
  • Node.js (version utilisée disponible dans les fichiers .nvmrc) il est recommandé d'utiliser un gestionnaire de versions tel que nvm
  • Docker (20.10)

⚠️ Les versions indiquées sont celles utilisées et préconisées par l'équipe de développement. Il est possible que l'application fonctionne avec des versions différentes.

Assurez-vous aussi de ne pas avoir de processus écoutant sur le port:

  • 5432 (PostgreSQL), ou surchargez la variable PIX_DATABASE_PORT;
  • 6379 (redis), ou surchargez la variable PIX_CACHE_PORT.

Instructions

Récupérer le code source.

Récupérer le code source en local

git clone [email protected]:1024pix/pix.git && cd pix

⚠️ Cela prend environ 10 minutes avec une connexion standard. Pour ne récupérer que la dernière version, qui ne prend qu'une minute, exécuter plutôt :

git clone --filter tree:0  [email protected]:1024pix/pix.git && cd pix

Configurer l'environnement de développement sous Windows (si applicable)

Définir dans .npmrc l'invite de commande à utiliser pour lancer les script-shell.

Ouvrir une invite de commande (cmd.exe) puis:

  • installation 64bit :
npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"
  • installation 32bit:
npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"

Enfin, pour éviter les problèmes de retour ligne sous Windows:

git config --local core.autocrlf input
git rm -r --cached .
git reset --hard

Configurer l'environnement de développement

Le script d'installation effectue les tâches suivantes :

  • créer la base de données et le cache (conteneurs Docker)
  • installer les librairies communes à tous les projets

Il prend moins de 5 minutes. Exécutez-le avec npm run configure

Vérifiez que le script s'est bien terminé : le message "🎉 Congratulations! Your environment has been set up." doit être affiché. Si ce n'est pas le cas, contactez les équipes de développement en ouvrant une issue.

IDE

VSCode

Pour les utilisateur de vscode, des fichiers de config sont disponibles dans le dossier .vscode. Pour les utiliser: cp .vscode/sample.launch.json .vscode/launch.json cp .vscode/sample.settings.json .vscode/settings.json

Les extensions recommandées peuvent se retrouver dans l'onglet extension en renseignant le filtre @recommanded

Démarrer les applications

Pour démarrer l'ensemble des applications, exécuter npm run dev

⚠️ Cela prend entre 10 et 15 minutes et la consommation mémoire est élevée lors de cette opération.

Si cela pose problème, démarrer sélectivement les applications :

  • Admin : npm run dev:admin
  • Api : npm run dev:api
  • App : npm run dev:mon-pix
  • Certif : npm run dev:certif
  • Orga : npm run dev:orga
  • Pix1d : npm run dev:pix1d

Accéder aux applications

Le mot de passe est par défaut pix123. D'autres comptes sont disponibles dans les seeds.

Complément

Accès aux sources de données

Se connecter à la base de données :

  • de test manuel : docker exec -it pix-api-postgres psql -U postgres pix;
  • de test automatique : docker exec -it pix-api-postgres psql -U postgres pix_test.

Se connecter au cache : docker exec -it pix-api-redis redis-cli

Configuration

Pix s'appuie sur la bibliothèque Dotenv pour gérer les variables d'environnement en local.

Le script scripts/configure.sh génère un fichier .env standard.

Vous pouvez l'adapter à vos besoins:

  • activer le logging détaillé avec pretty-print :
LOG_ENABLED=true
LOG_LEVEL=debug
LOG_FOR_HUMANS=true
  • permettre la suppression du schéma de la base de données sans arrêter l'API :
FORCE_DROP_DATABASE=true
  • se connecter à un autre référentiel pédagogique que celui de base (test):
LCMS_API_KEY=<SOME_KEY>
LCMS_API_URL=<SOME_URL>

Configurer les domaines locaux

Il est possible d'accéder aux applications Pix avec des domaines *.dev.pix.<tld> plutôt que localhost:port :

Pour configurer les domaines locaux, exécuter le script :

sudo npm run domains:install

Démarrer le conteneur docker :

npm run domains:start

Arrêter le conteneur :

npm run domains:stop

Charger des SSO OIDC lors du chargement des seeds

Le chargement des SSO OIDC lors du chargement des seeds est effectué depuis la variable d’environnement OIDC_PROVIDERS si elle définie. Si elle est définie elle doit contenir du JSON. Écrire ce JSON est assez pénible car il y a beaucoup de propriétés à fournir et qu’on ne peut actuellement pas utiliser de retours à la ligne dans le fichier .env (même si ce serait théoriquement possible avec la notation here-document). Aussi un fichier d'exemple OIDC_PROVIDERS.example.json est fourni avec un mode opératoire facilité décrit ci-dessous.

  1. Copier et adapter le fichier OIDC_PROVIDERS.example.json à votre besoin :

    cp OIDC_PROVIDERS.example.json OIDC_PROVIDERS.json

  2. Définir la variable d’environnement OIDC_PROVIDERS avec le contenu du fichier OIDC_PROVIDERS.json :

    export OIDC_PROVIDERS=$(cat OIDC_PROVIDERS.json)

  3. Exécuter le chargement des seeds avec du debug pour constater le bon chargement des SSO OIDC :

    export DEBUG="pix:oidc-providers:*"
npm run db:reset

Exécuter le lint à chaque commit

Activer

Ce repository est configuré pour indiquer aux IDE Webstorm et Vscode la configuration du linter. Malgré cela, il peut arriver que des erreurs de lint soient introduites.

Pour tenter de les corriger automatiquement lors du commit, installer un hook de pre-commit.

npm run local:add-optional-checks

Si vous souhaitez désactiver

npm run local:remove-optional-checks

Détecter des secrets

Installer un hook de pre-commit.

npm run local:add-optional-checks

Si vous souhaitez le désactiver

npm run local:remove-optional-checks

Tester les envois d'e-mails

Avec une interface web

Il est possible de tester les envois d'e-mails avec Mailpit, un outil qui simule un serveur SMTP et offre une interface web permettant de voir les e-mails envoyés.

Il faut pour cela ajouter deux variables d'environnement au .env:

MAILING_ENABLED=true
MAILING_PROVIDER=mailpit

Mailpit est inclus dans les images du fichier docker-compose.yml et sera donc lancé automatiquement.

On peut accéder à l'interface web Mailpit à l'adresse http://localhost:8025.

Dans un terminal

On peut également tracer de manière détaillée (debug) l'appel de l'API d'email avec la configuration d'une variable d'environnement :

export DEBUG="pix:mailer:email"

Cette variable d'environnement peut également être alimentée dans le fichier .env.