🇬🇧 English version

[Startup Pôle emploi] Estime - simulateur d'aides à la reprise d'emploi

L’idée :

Proposer un simulateur qui encourage l'acte de reprise à l'emploi d'un demandeur d’emploi en lui offrant la possibilié de visualiser, sur une période de 6 mois, toutes ses futures ressources financières en cas de reprise d’emploi (aides Pôle emploi, aides CNAF). Plus d'informations sur notre démarche https://beta.gouv.fr/startups/estime.html

Accéder à l'application : https://estime.pole-emploi.fr/

[Architecture] Schéma simplifié

• Github application REST Springboot
• Github application REST Openfisca.

🔐 L'accès au service Estime est sécurisé par une authentification avec Pôle emploi Connect.

[Code Source] Quelques explications

Ce projet est développé en Typescript avec le framework Angular.

Ce projet a été généré avec Angular CLI et utilise npm pour gérer les dépendances externes.

Structuration du code source

• ./src/app/public : composants publics, accessibles en non authentifié (homepage, cgu, etc...).
• ./src/app/protected : composants protégés, accessibles seulement authentifié (étapes de la simulation, etc...).
• ./src/app/commun : composants communs, directives, guards, pipes, models
• ./src/app/core : services singleton
• ./docker : fichier de configuration Docker
• ./cypress : tests e2e

librairies HTML et CSS

• Bootstrap 4
• ngx-bootstrap..
• Scss, préprocesseur de CSS.

Gestion des dépendances avec npm

Les mises à jour des dépendances du projet se font avec npm. Pour contrôler la mise à jour des versions, pas d'utilisation de ~ ou ^ dans le package.json, les versions sont mise à jour manuellement.

🔧 Outils utiles :

• npm-check
• npm-audit

[Développement en local] Lancer l'application sur localhost

Prérequis

Installation de NodeJS avec une version 12.11.x minimum.

👍 Installer NodeJS avec un outil permettant de gérer plusieurs versions de Node (exemple : nvm). Plus d'informations, par ici.

Vérifier votre installation :

foo@bar:~$ node -v
foo@bar:~$ npm -v

Les étapes à suivre

1. Installer Angular CLI

   foo@bar:~$ npm install -g @angular/cli

2. Cloner le projet avec git

3. Ouvrir le projet via votre IDE préféré

   👍 VS Code est un IDE gratuit, légé et qui permet d'avoir un excellent confort de développement sur Angular

4. Installer les dépendances du projet

   foo@bar:~estime-frontend$ npm install

5. Créer un fichier nommé environment.local.ts dans estime-frontend/src/environments

   • Copier le contenu suivant et remplacer les variables %% à renseigner %%
   • Pour le paramètre apiEstimeURL, consulter la section Application Springboot
   
   

   export const environment = {
      production: false,
      /******** url de l'api coeur métier Estime ************/
      apiEstimeURL: '%% à renseigner %%',
      /******** OpenID Connect PE properties ************/
      peconnectClientid: '%% à renseigner %%',
      peconnectRedirecturi: 'http://127.0.0.1:9001/',
      peconnectScope: '%% à renseigner %%',
      peconnectIdentityServerURL: 'https://authentification-candidat.pole-emploi.fr',
      /******** url du script TagCommander (activation du taggage et du consentement Cookies)  ************/
      /** non renseigné car le taggage et le consentement Cookies n'est pas activé en localhost          **/
      tagCommanderScriptUrl: ''
   };

6. Démarrer l'application :

   foo@bar:~estime-frontend$ npm start

[Application REST Springboot] Installer l'application en local

1. suivre les instructions du README du projet

2. renseigner le paramètre apiEstimeURL du fichier environment.local.ts comme ci-dessous :

   export const environment = {
   production: false,
   /******** url de l'api coeur métier Estime ************/
   apiEstimeURL: 'http://localhost:8081/estime/v1/',
   [...]
   };

[Tests e2e] Cypress

Structuration des tests

Utilisation du pattern "Page Object".

• ./cypress/integration/integration : classes implémentant la logique des tests. Organisation par features et user stories
• ./cypress/integration-commun : classes Page Object
• ./ci : fichiers de configuration pour l'exécution des tests dans le pipeline de GitLab CI
• coverage.webpack.js : rapport de couverture du code avec istanbul-lib-instrument

Executer les tests e2e en local

1. Créer un fichier environment.ts à la racine du répertoire cypress

   Copier le contenu suivant en valorisant les paramètres :

   export const environment = {
      urlApplication: '%% à renseigner %%',
      peConnectUserAahIdentifiant: '%% à renseigner %%',
      peConnectUserAssIdentifiant: '%% à renseigner %%',
      peConnectUserRsaIdentifiant: '%% à renseigner %%',
      peConnectUserMotDePasse: '%% à renseigner %%'
   };

2. Lancer Cypress :

   foo@bar:~estime-frontend$ npm run cy:open

[Conteneurisation] Utilisation de Docker

• ./docker/local : fichiers de configuration pour lancer l'application en local avec Docker Compose
• ./docker/recette : fichiers de configuration pour l'environnement de recette et un déploiement sur un serveur Docker Swarm
• ./docker/production : fichiers de configuration pour l'environnement de production et un déploiement sur un serveur Docker Swarm
• ./docker/commun : fichiers de configuration communs (nginx, fail2ban, scripts shell)

Lancer l'application en local avec Docker Compose

Prérequis : installer Docker et Docker Compose.

1. Lancer le build de l'application :

   foo@bar:~estime-frontend$ npm run build:dev

2. Lancer le build de l'image Docker :

   foo@bar:~estime-frontend$ docker build . -f ./docker/local/docker-image/Dockerfile  -t estime-frontend

3. Créer un fichier docker-compose.yml, n'oubliez pas de valoriser les %% à renseigner %%

   version: '3.8'
   
   services:
      estime-frontend:
         image: estime-frontend
         ports:
            - 3000:8888
         environment:
            PE_CONNECT_CLIENT_ID: "%% à renseigner %%"
            PE_CONNECT_REDIRECT_URI: "%% à renseigner %%"
            PE_CONNECT_SCOPE: "%% à renseigner %%"
            PE_CONNECT_IDENTITY_SERVER_URL: "%% à renseigner %%"
            TAG_COMMANDER_SCRIPT_URL: ""
            TZ: "Europe/Paris"

4. Se positionner dans le répertoire de votre fichier docker-compose.yml et démarrer le conteneur :

   foo@bar:~docker-compose-directory$ docker-compose up -d

5. L'application devrait être accessible sur http://localhost:3000

[CI/CD] build et déploiement automatisés avec Gitlab CI

Voir le fichier ./.gitlab-ci.yml

[Qualimétrie] Suivi de la qualité du code source

Tableau de bord sous Sonarqube : https://sonarqube.beta.pole-emploi.fr/dashboard?id=estime-frontend

[Suivi opérationnel] Comment dépanner l'application sur un serveur Docker Swarm ?

• Vérifier que l'application fonctionne correctement :

  foo@bar:~$ docker container ls | grep estime-frontend

  Les conteneurs doivent être au statut UP et healthy.

• Consulter les logs :

  foo@bar:~$ docker service logs estime-frontend_estime-frontend

• Démarrer ou relancer le service

  • Se positionner dans le répertoire /home/docker/estime-frontend

  • Exécuter la commande suivante :

    foo@bar:/home/docker/estime-frontend$ docker stack deploy --with-registry-auth -c estime-frontend-stack.yml estime-frontend

• Stopper le service :

  foo@bar:~$ docker stack rm estime-frontend

Zero Downtime Deployment

Le service Docker a été configuré afin d'éviter un temps de coupure du service au redémarrage de l'application.

healthcheck:
   test: curl --fail http://localhost:8888/ || exit 1
   timeout: 30s
   interval: 1m
   retries: 10
   start_period: 180s
deploy:
   replicas: 2
   update_config:
      parallelism: 1
      order: start-first
      failure_action: rollback
      delay: 10s
   rollback_config:
      parallelism: 0
      order: stop-first
   restart_policy:
      condition: any
      delay: 5s
      max_attempts: 3
      window: 180s

Cette configuration permet une réplication du service avec 2 replicas. Lors d'un redémarrage, un service sera considéré opérationnel que si le test du healthcheck a réussi. Si un redémarrage est lancé, Docker va mettre à jour un premier service et s'assurer que le conteneur soit au statut healthy avant de mettre à jour le second service.

Limitation des ressources CPU et RAM

Afin de gérer au mieux les ressources du serveur, la quantité de ressources CPU et de mémoire que peut utliser un conteneur a été limitée :

resources:
   reser vations:
      cpus: '0.15'
      memory: 128Mi
   limits:
      cpus: '0.30'
      memory: 256Mi

Voir la consommation CPU et mémoire des conteneurs Docker :

foo@bar:~$ docker stats

Connaître la version de l'application déployée

Accéder à la version via https://estime.pole-emploi.fr/version.json

[npm] Scripts utiles

Lancer un script :

foo@bar:~estime-frontend$ npm run **nom_script**

Nom	Description
build:dev	build l'application avec le profil dev
build:prod	build l'application avec le profil prod
cy:open	lance l'utilitaire Cypress Test Runner
cy:run	lance les tests Cypress
start	lance l'application dans le navigateur sur 127.0.0.1:9001
start:ngx	lance l'application sur 127.0.0.1:9001 avec ngx-build-plus, utile pour remonter une couverture de code par les tests Cypress
stats:size	génération d'un rapport sur la taille du bundle (webpack-bundle-analyzer)

[Livraison] Livrer une nouvelle version en production

Une image Docker Nginx contenant le code source de l'application Angular est livrée sur les différents environnements (recette, production). Cette image est versionnée en release-candidate pour la recette et en release pour la production.

Procédure de build et de livraison d'une version release en production

Après s'être assuré du bon fonctionnement de l'application sur l'environnement de recette, voici les étapes à suivre pour livrer la version de l'application de recette en production.

La veille de la mise en prodction

• mettre à jour les informations de version du fichier src/version.json et la version du fichier package.json. Possibilité de vérifier la version actuelle en production via https://estime.pole-emploi.fr/version.json.

• commit les changements et livrer en recette (exemple message commit : "création version production v1.5.0").

• une fois la livraison en recette effectuée, lancer dans le pipeline GitLab CI, les jobs build-docker-image-production et generate-docker-stack-production

• poser un tag via GitLab dans Repository => Tags (exemple nommage du tag : v1.5.0-version-mise-en-prod)

Mise en production le lendemain

• lancer le job deploy_application_production

• se connecter sur la machine pour vérifier que tout se passe bien, voir section Suivi opérationnel

• envoyer une notification à l'équipe

[VS Code] Quelques plugins utiles

• Angular Language Service
• Angular Schematics
• Angular Snippets (Version 11)
• Angular template formatter
• HTMLHint
• HTML class snippets with Bootstrap4
• Bootstrap v4 Snippets
• SCSS Formatter
• TypeScript Hero
• vsc-organize-imports
• ESLint

[CLI] Liste des commandes

Commande	Description
npm start	Démarrer l'application sur localhost
npm run build:prod	Build l'application environnement production
npm run start:ngx	Lancer l'application avec ngx pour remonter couverture code par les tests Cypress
npm run cy:open	Lancer Cypress Test Runner
npm run cy:run	Lancer les tests Cypress
npx browserlist	Lister versions des navigateurs compatibles
npm run stats:size	Lancer l'analyse de la taille du bundle