Variables d'environnement

Cette page est la référence des variables lues par le backend. Le tableau est généré à la construction de la documentation depuis backend/src/config/env.config.ts : type, valeur par défaut et contraintes viennent directement du schéma Zod, il ne peut donc pas diverger du code. Le chargement, la validation et les règles propres à la production sont expliqués sur la page Configuration.

Les mêmes variables servent aux deux process, l'API (server.ts) et le worker (worker.ts). Une valeur incohérente entre les deux, par exemple deux REDIS_KEY_PREFIX différents, casse le relais Socket.IO et l'idempotence. Dans la stack Docker, l'ancre x-backend-env de docker-compose.yml garantit qu'ils reçoivent les mêmes valeurs.

#Générer les secrets

Quatre variables sont des secrets refusés en production s'ils gardent leur valeur de développement. Les commandes suivantes utilisent Node, déjà requis par le projet. La dernière s'exécute depuis backend/, où ethers est installé.

Changer JWT_SECRET invalide toutes les sessions ouvertes : c'est un moyen radical de déconnecter tout le monde. Changer WEBHOOK_SECRET impose de mettre à jour l'émetteur du webhook en même temps.

#Valeurs selon l'environnement

#Développement local

cp .env.example .env suffit. Les valeurs visent l'infrastructure lancée par docker compose up -d --wait depuis la racine du dépôt.

Après un redémarrage du nœud Hardhat, la chaîne repart du bloc 0 alors que la base garde son curseur d'indexation : l'indexeur journalise alors que le curseur dépasse la tête de chaîne. Il faut réinitialiser la base avec npm run prisma:reset, comme décrit dans Blockchain locale.

#Stack Docker

Le fichier docker-compose.yml fixe déjà les variables d'infrastructure dans l'ancre x-backend-env : NODE_ENV=production, DATABASE_URL sur postgres:5432, REDIS_URL sur redis:6379, BLOCKCHAIN_MODE=onchain, RPC_URL=http://blockchain:8545, CHAIN_ID=31337, les deux adresses de contrats, SMTP_HOST=mailpit et les origines CORS. Le service backend y ajoute RUN_WORKERS=false ; le service worker démarre dist/src/worker.js.

Comme la stack tourne en production, les règles de production s'appliquent. Les cinq secrets sont lus depuis un fichier .env placé à la racine du dépôt, lu par Docker Compose pour l'interpolation :

JWT_SECRET=valeur-generee
ENCRYPTION_KEY=64-caracteres-hexadecimaux
RELAYER_PRIVATE_KEY=0x64-caracteres-hexadecimaux
WEBHOOK_SECRET=valeur-generee
METRICS_TOKEN=valeur-generee

Si l'une manque, backend et worker s'arrêtent au démarrage avec Configuration invalide. La même RELAYER_PRIVATE_KEY est transmise au conteneur blockchain sous le nom OPERATOR_PRIVATE_KEY pour habiliter ce compte sur les contrats déployés. Le détail est sur la page Stack complète en conteneurs.

#Sepolia

Pour brancher le backend sur le déploiement public, reprendre les valeurs du fichier smart-contract/deployments/sepolia.json écrit par npm run deploy:sepolia (voir Déploiement sur Sepolia).

POST /admin/treasury/withdraw appelle setTreasury sur le contrat quand l'adresse demandée diffère de la trésorerie actuelle. Cette fonction exige DEFAULT_ADMIN_ROLE. Sur Sepolia, le script de déploiement réserve ce rôle au multisig MAIRIE_ADMIN_ADDRESS : l'opérateur ne l'a pas, et seul un retrait vers la trésorerie configurée (MAIRIE_TREASURY_ADDRESS) fonctionne ; changer de trésorerie passe par le multisig. En local, deploy-local.ts laisse ce rôle à l'opérateur, sauf avec LOCAL_STRICT_ROLES=true.

#Référence

Le schéma de configuration compte 59 variables, lues et validées au démarrage par backend/src/config/env.config.ts. Une valeur invalide arrête le processus avec la liste des erreurs.

#Serveur HTTP

#Observabilité

#Base de données

#Redis

#Sécurité et sessions

#Email

#Blockchain

#Workers

#Stockage S3

#Frontend et CORS

#Fonctionnalités