Ecobalyse

Accélerer la mise en place de l’affichage environnemental

L’application est accessible à cette adresse.

Note: le projet Ecobalyse s’appellait initialement Wikicarbone.

Socle technique et prérequis

Le frontend de cette application est écrit en Elm. Vous devez disposer d’un environnement NodeJS 22+ et npm. Pour le backend vous devez disposer d’un environnement python >=3.12, uv et gettext sur votre machine. Certains fichiers d’impacts détaillés nécessitent de configurer transcrypt pour les lire en local.

docker est également une dépendance requise pour lancer la suite de tests.

Configuration

Les variables d’environnement décrites ci-dessous doivent être définies. En développement, copiez le fichier .env.sample, renommez-le .env, et mettez à jour les valeurs qu’il contient ; le serveur de développement chargera les variables en conséquences.

Variables partagées

• SENTRY_DSN : le DSN Sentry à utiliser pour les rapports d’erreur front et back

Frontend (npm & node)

• ENABLE_FOOD_SECTION : affichage ou non de la section dédiée à l’alimentaire (valeur True ou False, par défaut False)
• ENABLE_OBJECTS_SECTION : affichage ou non de la section expérimentale dédiée aux objets génériques (valeur True ou False, par défaut False
• ENABLE_VELI_SECTION : affichage ou non de la section expérimentale dédiée aux véhicules intermédiaires (valeur True ou False, par défaut False)
• ENCRYPTION_KEY : la clé utilisée par les scripts npm run encrypt et npm run decrypt pour chiffrer/déchiffrer les fichiers d’impacts détaillés inclus dans chaque archive de release. Pour générer une nouvelle clé, vous pouvez utiliser le script bin/generate-crypto-key
• MATOMO_HOST : le domaine de l’instance Matomo permettant le suivi d’audience du produit (typiquement stats.beta.gouv.fr)
• MATOMO_SITE_ID : l’identifiant du site Ecobalyse sur l’instance Matomo permettant le suivi d’audience du produit
• MATOMO_TOKEN : le token Matomo permettant le suivi d’audience du produit
• NODE_ENV : l’environnement d’exécution nodejs (par défaut, development)
• PLAUSIBLE_HOST : le domaine du serveur Plausible (optionnel)
• RATELIMIT_MAX_RPM : le nombre de requêtes maximum par minute et par ip (par défaut: 5000)
• RATELIMIT_WHITELIST : liste des adresses IP non soumises au rate-limiting, séparées par des virgules
• SECRET_KEY : le secret 32bits pour le backend ; vous pouvez en générer une avec openssl rand -hex 32
• TRANSCRYPT_KEY : la clé utilisée et autogénérée par transcrypt et disponible dans https://vaultwarden.incubateur.net
• VERSION_POLL_SECONDS : le nombre de secondes entre deux appels HTTP pour récupérer la dernière version de l’application (/version.json, défaut: 300)

Backend

• DATABASE_URL : DSN de la base de données

  Pour utiliser un serveur PostgreSQL spécifique, configurez la variable DATABASE_URL comme ceci :

  DATABASE_URL=postgresql+asyncpg://<username>:<pw>@localhost:5432/<nom de la bdd>)
  

  Sinon, une base de données par défaut dans un conteneur Docker sera utilisée.

• EMAIL_FROM : l’adresse email de l’expéditeur des emails du backend

• EMAIL_SERVER_HOST : serveur SMTP (localhost permet de bénéficier d’une instance maildev)

• EMAIL_SERVER_PASSWORD : le mot de passe du serveur SMTP

• EMAIL_SERVER_PORT : numéro de port du serveur SMTP (1025 permet de bénéficier d’une instance maildev)

• EMAIL_SERVER_USER : nom d’utilisateur SMTP

• EMAIL_SERVER_USE_TLS : utilisation de TLS (par defaut à True, positionner à False pour utiliser l’instance maildev)

Déploiement

• BACKEND_ADMINS : la liste des emails, le prénome et le nom des administrateurs initiaux, utilisés pour charger les utilisateurs par défaut lors du déploiement Scalingo. Le format doit être de ce type : email1@test.com/Prénom1/Nom1,email2@test.com/Prénom2/Nom2.

Installation

Frontend

• Installation des dépendances

  npm ci --ignore-scripts
  

• Déchiffrage du fichier des impacts détaillés. Attention, la variable d’environnement TRANSCRYPT_KEY documentée plus haut doit être renseignée et exportée auparavant.

  export TRANSCRYPT_KEY="<clé de déchiffrement>"
  ./bin/run-transcrypt.sh
  

Backend

• Installation des dépendances

  uv sync
  

Le framework utilisé est Litestar.

Environnement de développement local

Lancer le serveur de développement

Le serveur local de développement se lance au moyen des deux commandes suivantes :

npm start:dev

Trois instances de développement sont alors accessibles :

• localhost:8002 sert le backend Litestar utilisé pour l’authentification, et sert aussi les fichiers statiques de ELM.
• localhost:8001 sert l’API publique Ecobalyse.
• localhost:1234 est l’URL à utiliser en développement pour tester l’intégration des trois composants (le front, l’API et le Django) car un proxy Parcel renvoie certaines requêtes vers le port 8001 ou 8002 (voir .proxyrc.json). Le frontend est servi en mode hot-reload, pour recharger l’interface Web à chaque modification du code frontend.

Migrer la base de données

uv run backend database upgrade --no-prompt

Réinitialiser la BDD et charger les données de fixtures

./bin/reset-docker-db.sh

Sans docker :

uv run backend database upgrade --no-prompt
uv run backend fixtures load-processes public/data/processes_impacts.json
uv run backend fixtures load-components public/data/object/components.json

Créer un super-utilisateur

uv run backend users create-user --email foo@bar.org --first-name Foo --last-name Bar --superuser

Utiliser la ligne de commandes backend

Obtenir la liste des commandes possibles

uv run backend --help

Afficher l’aide d’une commande spécifique

uv run backend users --help

Auto-hébergement avec Docker

Vous trouverez dans ./docker des scripts permettant d’héberger une version publiée d’Ecobalyse en local en utilisant docker. Vous pouvez éditez le Dockerfile pour spécifier la version que vous souhaitez lancer, puis la lancer en utilisant docker compose :

docker compose -f docker/compose.yaml up --build

Un server express sera lancé sur http://localhost:8001. À noter qu’actuellement, vous ne pouvez pas avoir accès aux impacts détailés de cette façon.

Hooks Git avec pre-commit et Formatage de Code avec Prettier et Ruff

Ce projet utilise https://pre-commit.com/ pour gérer les hooks Git ainsi que Prettier et Ruff pour le formatage automatique du code.
Le build sur le CI échouera si les fichiers python, javascript et json ne sont pas proprement formattés.

Vérification Automatique avant chaque Commit

Pour installer les hooks pre-commit, exécutez la commande suivante :

uv run pre-commit install

Un hook de pre-commit sera alors configuré pour vérifier que le code est bien formaté avant de permettre le commit. Le hook corrigera les erreurs dans la mesure du possible. Il vous suffira alors d’ajouter les modifications à votre staging, git puis à refaire votre commit.

Il est possible de lancer la vérification du formatage à la main grâce à la commande suivante :

npm run lint:all

Si vous voulez lancer la correction automatique de tous les problèmes détectés, lancez :

npm run fix:all

Si vous ne souhaitez pas que la vérification se fasse de manière automatique, vous pouvez désinstaller pre-commit et les hooks associés :

uv run pre-commit uninstall

Débogage des emails

Une instance maildev est lancé en même temps que le serveur de développement, elle est accessible à l’adresse http://localhost:1081.

Compilation

Pour compiler la partie client de l’application :

npm run build

Les fichiers sont alors générés dans le répertoire dist à la racine du projet, qui peut être servi de façon statique.

Déploiement

L’application est déployée automatiquement sur la plateforme Scalingo à chaque mise à jour de la branche master sur le dépôt.

Chaque Pull Request effectuée sur le dépôt est également automatiquement déployée sur une instance de revue spécifique, par exemple https://ecobalyse-pr44.osc-fr1.scalingo.io/ pour la pull request #44. Ces instances de recette restent actives 72 heures, puis sont automatiquement décommisionnées passé ce délai ou si la pull request correspondante est mergée.

Ajout d’une variable d’environnement

Pour ajouter une variable d’environnement sur une application, il est recommandé d’utiliser le CLI scalingo qui permet d’ajouter des valeurs qui contiennent plusieurs lignes (à la différence de l’interface graphique qui ne le permet pas) :

scalingo --app ecobalyse env-set "MY_VAR=$(cat fichier.key)"

Fichiers d’impacts détaillés

Les fichiers d’impacts détaillés sont chiffrés à l’aide de transcrypt sur le dépôt public Github. En revanche, la version locale est une version décryptée par transcrypt. Vous pouvez donc utiliser, localement, les commandes git habituelles pour voir les différences dans ces fichiers, par exemple :

git diff master HEAD public/data/textile/processes_impacts.json

Des commandes supplémentaires sont disponibles pour chiffrer et déchiffrer les fichiers manuellement au besoin (débogage par exemple). Notez que ces commandes requièrent la présence de la variable d’environnement ENCRYPTION_KEY pour fonctionner correctement :

npm run encrypt public/data/textile/processes_impacts.json dist/processes_impacts_textile.json.enc
npm run decrypt dist/processes_impacts.json.enc dist/processes_impacts_textile.json

Points d’attention

Serveur de production

Variables d’environnement

Les variables d’environnement doivent être positionnées via l’interface de configuration Scalingo (voir la section Configuration).

Lancement du serveur

Pour lancer le serveur applicatif complet (frontend + backend), par exemple depuis un environnement de production, la démarche est la suivante :

npm run build
npm run server:start

L’application est alors servie sur le port 1234.

Ecobalyse data

Le dépôt ecobalyse-data contient les scripts (principalement Python) utilisés pour
importer et exporter les données du projet Ecobalyse.

Version statique et autonome

Vous pouvez générer une version statique de l’application en utilisant le script suivant :

BUILD_CURRENT_VERSION=1 ./bin/build-specific-app-version.sh name

Un fichier nommé name-dist.tar.gz sera créé contenant une version statique du site.