Carbure

Traçabilité et durabilité des biocarburants, de la production à la distribution

Prérequis

• docker
• docker-compose
• python3
• pipenv
• mysql@8.0 => voir les précisions d'installation ci-dessous
• node
• scalingo curl -O https://cli-dl.scalingo.com/install && bash install

Installation de mysql@8.0

Attention, uniquement la version 8.0 de MYSQL fonctionne sur notre configuration

• supprimez toute autres versions brew uninstall mysql.

• reinstallez la bonne version brew install mysql@8.0.

• mysql risque de s'installer avec dans le dossier /opt/homebrew/opt/mysql@8.0 au lieu de /opt/homebrew/opt/mysql. Depuis le dossier d'installation /opt/homebrew/opt créez un lien symbolique : ln -s mysql@8.0 mysql

• Ajouter le binaire au PATH export PATH="/opt/homebrew/opt/mysql/bin:$PATH"

• /!\ Ne pas start mysql sur la machine (ou alors changer les ports si besoin) Si vous rencontrez cette erreur lors de l'importation de la bdd NameError: name '_mysql' is not defined ou mysql: [Warning] Using a password on the command line interface can be insecure. ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: YES) c'est que mysql est lancé en local sur votre ordinateur. Vous pouvez vérifier avec brew services, puis fermez-le avec : brew services stop mysql@8.0

Configuration et Installation

• Clonez le repository: git clone https://github.com/MTES-MCT/carbure.git
• Créez un fichier .env à la racine du dépôt en vous basant sur le fichier .env.example disponible dans le dossier.
• Tu peux retrouver la plupart des valeurs dans la section "Environnement" de carbure-prod sur scalingo https://dashboard.scalingo.com/apps/osc-secnum-fr1/carbure-prod/environment.

A savoir : Une fois les accès scalingo obtenus, il faut créer un compte avec ton adresse scalingo, et contacter scalingo via le tchat du site en leur indiquant que tu travailles sur un projet gouvernemental et que tu as besoin d'être whitelisté pour avoir accès à la région osc-secnum-fr1.

• Liste des variables nécessaires à récupérer : SECRET_KEY, SCALINGO_MYSQL_UUID, METABASE_SECRET_KEY, SENTRY_DSN, EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS
• créer un accès ssh à ton compte Scalingo (https://dashboard.scalingo.com/account/keys) et un API token (dans ton profile scalingo https://dashboard.scalingo.com/account/tokens)
• remplir SCALINGO_TOKEN=le token que tu as créé dans tom compte

Installation de pipenv :

• ajouter export PIPENV_VENV_IN_PROJECT=1 au ~/.bashrc (ou ~/zshrc, etc...)

Ensuite, créez un environnement virtuel pour python 3.10:

• pipenv install --dev

• Dans le dossier /front, téléchargez les modules npm install

• Vous pouvez désormais builder les images docker et lancer le projet: docker-compose build docker-compose up -d

Se placer dans l'environnement python dédié au projet

• Lancer pipenv shell pour vous placer dans l'environnement python dédié au projet

Raccourci : Je recommande de créer un alias pour charger l'environnement de développement : alias carbure='cd /path/du/repository; pipenv shell;'

Alimenter la base de données de dev

• se connecter à scalingo scalingo login --api-token $SCALINGO_TOKEN
• Lancer sh scripts/database/restore_db.sh pour télécharger un dump contenant des données utilisables en local

Création d'un nom de domaine local personnalisé

• Aller dans le fichier /etc/hosts (sur linux et mac)
• Ajouter la ligne 127.0.0.1 carbure.local
• Vous pouvez maintenant accéder à votre version locale de carbure à l'adresse http://carbure.local:8090/

Configurer l'accès à la base de donnée depuis le terminal

• Dans le fichier .env, éditer les variables DATABASE_URL et REDIS_URL et y mettre une valeur qui pointe vers les containers MySQL et Redis
• DATABASE_URL=mysql://{root_user}:{root_password}@0.0.0.0:3306/carbure-db
• REDIS_URL=redis://0.0.0.0:6379
• Une fois le container MySQL lancé, dans le pipenv shell, exécuter python web/manage.py dbshell
• S'il n'y a pas d'erreur, c'est ok
• Si cette étape ne marche pas du tout, on peut passer par le container Django pour exécuter manage.py
• docker exec -it carbure_app python3 web/manage.py dbshell fonctionne à tous les coups

Authentification à Carbure

• Bien vérifier que la variable d'environnement IMAGE_TAG est à local afin de désactiver la vérification de token CSRF.
• Pour ajouter un nouveau super utilisateur à la db locale, taper python3 web/manage.py createsuperuser
• Ensuite aller sur http://carbure.local:8090/auth/login
• Utiliser les informations renseignées à l'étape 1 puis valider l'authentification
• Carbure demande d'entrer un code envoyé par email
• Dans la version de dev ce code sera uniquement affiché dans les logs de django, visibles en tapant docker logs carbure_appRun all the tests

Effectuer une migration

Lorsque des changement sont effectué sur la base de donnée : 1 une fois les model ou champs ajouté, pour créer le fichier de migration - python web/manage.py makemigrations 2 pour appliquer la migration sur la DB - python web/manage.py migrate

Annuler une migration

il faut revenir à la migration precedent. Par exemple si veux annuler doublecount.0014_change_something python web/manage.py migrate doublecount 0013_remove_doublecountingapplication_dgddi_validated_and_more

Analyser les performances des requêtes

Lorsqu'un endpoint de l'API est lent, c'est 9 fois sur 10 à cause de problèmes avec la base de données: trop de requêtes successives, trop de résultats en une seule fois, etc.

Pour pouvoir analyser ces problèmes, l'outil silk a été mis en place sur le serveur. On peut y accéder uniquement en local à l'adresse http://carbure.local:8090/silk.

La dashboard à cette adresse liste toutes les requêtes envoyées au serveur, et tout une série de métriques comprenant les différentes requêtes envoyées à la base de données ainsi que leur performance.

Pour plus d'information sur silk, une documentation est disponible à l'adresse https://github.com/jazzband/django-silk

Lancer les tests backend

• Run all the tests in the api.v5.saf module python web/manage.py test api.v5.saf
• Run just one test python web/manage.py test api.v5.saf.airline.tests.tests_ticket_details.SafTicketDetailsTest
• Pour éviter de reconstruire la db de test à chaque fois, on peut ajouter l'option --keepdb à la fin de la commande

Utiliser la console scalingo

scalingo -a carbure-[dev/prod/staging] run bash scalingo -a carbure-prod run bash python web/manage.py shell

example :

>>> from core.models import Entity
>>> entities = Entity.objects.filter(registered_address__isnull=False)
>>> entities.count()

-for v4 docker exec -e TEST=1 carbure_app python3 web/manage.py test api.v4.tests_lots_flow

Executer un patch en local (script)

-Créer un fichier xxx.py dans le dossier scripts/batches/ puis entrer dans le shell : python web/manage.py shell -et copier le code du script

./scripts/database/reload_iscc_certifs.sh contenant un script pouvant etre lancé (ex https://gitlab.com/la-fabrique-numerique/biocarburants/-/blob/master/web/carbure/scripts/update_iscc_certificates.py?ref_type=heads#L272) : python3 web/carbure/scripts/update_iscc_certificates.py

Executer un script gourmand en ressource en prod

scalingo -a carbure-prod run python scripts/patches/2024-01-16_update_feedstock.py --id=77 --name="Ethanol\ pur\ de\ marc\ de\ raisin" --code="ETHANOL_PUR_MARC_RAISIN"

En lançant un one-off container (https://doc.scalingo.com/platform/app/tasks) scalingo --app carbure-prod run --size XXL python web/carbure/scripts/update_iscc_certificates.py

Étapes spécifiques pour windows

• setup wsl2: https://docs.microsoft.com/en-us/windows/wsl/install-win10
• installer docker desktop avec les libs WSL extra
• installer ubuntu 20.04: https://www.microsoft.com/fr-fr/p/ubuntu-2004-lts/9n6svws3rx71?activetab=pivot:overviewtab
• installer windows terminal: https://www.microsoft.com/fr-fr/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab
• activer ubuntu dans les options de docker desktop (resources > wsl)
• ouvrir ubuntu dans le windows terminal puis taper:
• sudo apt-get update
• sudo apt-get install python3 python3-dev python3-pip default-libmysqlclient-dev build-essential
• pip install --user pipenv

Ensuite, setup normalement le projet:

• ajouter les clé ssh https://docs.gitlab.com/ee/ssh/#generate-an-ssh-key-pair
• dans le terminal ubuntu, taper:
• git clone git@gitlab.com:la-fabrique-numerique/biocarburants.git carbure
• cd carbure
• pipenv install
• (cd front; npm install)
• docker-compose up --build -d
• code .

Double comptage : comment ajouter un biocarburant ou une matière premère

1 - Modifier le fichier biocarburant.csv ou matierespremieres.csv en ajoutant les données concernées 2 - mettre à jour le fichier excel_to_carbure_convertor.py en ajoutant dans les tableaux au moins une instance puis les variations de dénominations