Démarrer en local

Six commandes séparent un dépôt fraîchement cloné d'une application qui tourne. Elles sont détaillées ci-dessous, mais la séquence tient en un bloc :

pnpm install     # dépendances + client Prisma
pnpm docker:up   # PostgreSQL, Redis, pgAdmin
pnpm db:push     # le schéma en base
pnpm db:seed     # les données de référence
pnpm dev         # les 7 services

L'étape manquante avant celles-là est le .env : sans lui, db:push ne sait pas quelle base viser.

Prérequis

Outil	Version	Pourquoi cette version
Node	≥ 22.22	Exigée par React Router 8 ; le seed s'appuie sur son typage natif des .ts
pnpm	11.18.0 exactement	Épinglée par packageManager — une autre version rejoue une résolution différente
Docker	daemon démarré	PostgreSQL 18.4 et Redis 8.8 tournent en conteneur
python3	3.x	Seulement pour sonder le corpus ; sans lui, db:seed charge l'instantané SQL

Un script les vérifie et sort en erreur au premier manquement, en nommant la version trouvée :

pnpm check:prerequisites

Le fichier .env

Il vit à la racine du dépôt, et nulle part ailleurs : prisma.config.ts, le seed et les commandes db:* le lisent tous à cet endroit. Une variable déjà posée dans le shell reste prioritaire.

cp .env.example .env

Les valeurs par défaut correspondent aux conteneurs de pnpm docker:up — en développement, il n'y a rien à modifier.

Variable	Rôle
DATABASE_URL	PostgreSQL, partagé par les cinq backends via packages/database
REDIS_URL	Redis : files BullMQ et pub/sub temps réel
REDIS_QUEUE_PREFIX	Préfixe des files — isole dev et preprod, qui partagent une instance
SESSION_SECRET	Signature des cookies de session du frontend

Le fichier porte aussi les ports des services et les URLs que le frontend utilise pour joindre les backends. Ils sont figés : les modifier casse les tests de contrat.

Les six commandes

pnpm install

Installe les dépendances des 12 workspaces. Le postinstall de packages/database génère le client Prisma dans la foulée.

pnpm docker:up

Démarre PostgreSQL 18.4, Redis 8.8 et pgAdmin. Les applications, elles, ne sont pas conteneurisées : elles tournent via pnpm dev et se connectent sur localhost.

pnpm docker:logs suit les journaux, pnpm docker:down arrête tout sans perdre les volumes.

pnpm db:push

Fait converger la base vers schema.prisma sans passer par une migration, puis régénère le client — Prisma enchaîne generate de lui-même.

db:push est réservé au développement

La commande altère le schéma en place, sans confirmation. Elle refuse de démarrer si DATABASE_URL ne pointe pas sur localhost : un .env recopié de .env.preprod ne peut donc pas retoucher le schéma de preprod. Passer outre demande un ALLOW_REMOTE_RESET=1 explicite. Hors développement, la mise à jour du schéma passe par prisma migrate.

pnpm db:seed

Charge les données de référence : technologies, messages types, templates et datasets. La commande construit d'abord les packages dont l'import dépend, puis lance l'import — l'ordre compte, et c'est elle qui s'en souvient.

Elle est rejouable : tout passe par des upsert, un second passage ne duplique rien. Ce qu'elle importe, ce qu'elle déduit et ce qu'elle écarte est détaillé dans Importer le corpus.

Le corpus est hors dépôt

Les données viennent de _source-oldproject/, qui est dans le .gitignore — il contient les clés d'intake de production. Le chemin peut être passé en argument : pnpm db:seed ../ailleurs/_source-oldproject. Si le dossier manque, la commande ne s'arrête pas : elle charge l'instantané SQL versionné dans le dépôt — c'est aussi ainsi que la CI et les environnements déployés reçoivent le corpus.

pnpm dev

Démarre les sept services en parallèle. Le premier lancement construit les packages partagés, ce qui prend une trentaine de secondes avant que les ports répondent.

Vérifier que tout tourne

Adresse	Ce qu'on y voit
http://localhost:3000	Le dashboard : santé des cinq backends, en temps réel
http://localhost:3001/api	Le Swagger de l'API de configuration
http://localhost:3005	Cette documentation
http://localhost:5050	pgAdmin (admin@sekoiacraft.com / sekoia)

Deux scripts répondent sans ouvrir de navigateur :

pnpm smoke:health   # les sondes /health des cinq backends
pnpm smoke:dev      # les sept services répondent-ils sur leur port

Repartir de zéro

Quand la base a dérivé — schéma modifié à la main, données de test incohérentes — une commande efface et recharge d'un coup :

pnpm db:reset [chemin-du-corpus] [--overwrite-templates]

Elle enchaîne le drop de la base, le push du schéma, la purge des files BullMQ et le rechargement du corpus. Le détail de chaque étape est dans Importer le corpus.

Quand ça coince

Symptôme	Cause	Geste
db:push : « n'est pas local »	Le .env vise une base distante	Le recopier depuis .env.example
db:push : P1001, connexion refusée	PostgreSQL n'est pas démarré, ou pas encore prêt	pnpm docker:up, puis réessayer
db:snapshot : « corpus introuvable »	_source-oldproject/ absent	Le déposer à la racine, ou passer son chemin en argument
db:seed : python3: command not found	L'import lit le registre en exécutant la source	Installer Python 3
pnpm dev : un backend sort sur DATABASE_URL is not defined	.env absent	cp .env.example .env
Le dashboard affiche un backend rouge	Postgres ou Redis est tombé	pnpm docker:logs pour lire lequel