J1 — Le dépôt tourne

L’objectif du jour : l’application répond sur votre machine, et vous savez quoi regarder quand elle ne répond pas.

Durée réaliste	2 heures, dont l’essentiel à télécharger des images et des dépendances
Prérequis	le dépôt cloné, et rien d’autre d’installé

Ce qu’il faut installer, et où la version est fixée

Aucune version n’est recopiée ici : chacune vit dans un fichier du dépôt, et c’est ce fichier qui fait foi.

Outil	Où la version est fixée	Ce qui casse sans lui
Bun	le champ packageManager du package.json racine — la CI épingle la même valeur dans .github/workflows/ci.yml	tout : c’est le gestionnaire de paquets et le lanceur de scripts
Node	engines.node du package.json racine, et .nvmrc	les apps (Vite, NestJS)
Docker	les images sont dans docker-compose.yml — PostgreSQL et Redis	la base, la file d’attente, le solveur
JDK	apps/solver/app/build.gradle.kts — toolchain 21, comme les images du Dockerfile	rien, sauf si vous construisez le solveur en local

Le JDK est optionnel et le reste. Le solveur se construit dans Docker ; un développeur qui ne touche pas au moteur d’optimisation n’a pas besoin de Java. Et si vous en avez besoin, la version installée sur votre poste importe peu : la construction Gradle déclare une toolchain 21 et télécharge le JDK qui manque. Notez au passage que le README.md racine annonce encore « Java 17+ » : c’est la seule version du dépôt à ne pas être alignée sur ce que le solveur exige.

Dans quel ordre

bun install                     # jamais npm ni pnpm : le lockfile est bun.lock
cp .env.example .env
docker compose up -d            # postgres, redis, solver
bun run dev

Quatre choses à savoir sur ces quatre lignes :

1. bun install, jamais autre chose. Le dépôt est un workspace Bun ; un npm install fabrique un second arbre de dépendances et un lockfile concurrent.
2. .env porte deux connexions à la base, et elles ne sont pas interchangeables — voir le piège plus bas.
3. docker compose up -d démarre trois services : PostgreSQL (5432), Redis (6379) et le solveur (8082). Il ne démarre pas l’API ni le web, qui sont derrière le profil full et tournent en local par bun run dev. L’en-tête du fichier docker-compose.yml annonce encore « PostgreSQL and Redis only » : le solveur a rejoint le profil par défaut après.
4. Les migrations partent toutes seules : l’API les applique au démarrage en développement, avec la connexion propriétaire. Pour les jouer à la main : bun run --filter @beemyschool/db db:migrate.

Le raccourci du pro

bun run dev démarre toutes les applications du dépôt à la fois — c’est bruyant. Au quotidien, ciblez : bun run --filter web dev, bun run --filter api dev. Le filtre prend le nom du package.json, pas le chemin.

Une variable optionnelle, et ce qu’elle allume

.env.example déclare VITE_DOCS_URL sans valeur. Elle porte l’origine de ce site de documentation, et c’est elle qui fait apparaître le bouton « Aide sur cet écran » dans l’en-tête de l’application — celui qui ouvre la page de référence de l’écran courant.

Laissée vide, le bouton n’existe pas. C’est le bon défaut : un lien d’aide vers un site que personne n’a démarré coûte un clic et de la confiance. Pour l’allumer en local, lancez la documentation (bun run --filter docs dev, port 4322) et posez VITE_DOCS_URL=http://localhost:4322 dans votre .env.

Comment savoir que c’est bon

Ce que vous ouvrez	Ce que vous devez obtenir
http://localhost:3000	l’application web
http://localhost:3001/docs	l’OpenAPI de l’API, en interactif
http://localhost:3001/health	l’état de l’API, que la page d’accueil du web interroge aussi
curl http://localhost:8082/q/health/ready	la sonde du solveur

Les ports du dépôt : web 3000, API 3001, atelier de données 3100, ce site de documentation 4322, solveur 8082 — et PostgreSQL 5432, Redis 6379. La table de référence est sur le gabarit de recette. Si vous croisez 5173 quelque part, c’est l’ancien défaut de Vite : rien n’écoute dessus.

Le piège du jour

Les deux connexions à la base ne font pas la même chose

.env.example en déclare deux, et les confondre est le meilleur moyen de perdre une journée à déboguer une isolation qui fonctionne très bien.

• DATABASE_URL porte le rôle beemyschool_app, non-superutilisateur, créé par la migration 0000. Le Row-Level Security s’applique à toutes ses requêtes. C’est la connexion du code applicatif, et la seule.
• DATABASE_ADMIN_URL porte le rôle propriétaire beemyschool. Il contourne le RLS, et ne sert qu’aux migrations et aux seeds.

Les deux symptômes, opposés et également déroutants : du code applicatif branché par erreur sur la connexion propriétaire voit toutes les données de tous les établissements sans que rien ne le signale ; un script de seed branché sur la connexion applicative n’écrit rien et échoue sur des lignes qui devraient passer.

Le sujet complet est en J4 — c’est le cœur du modèle multi-tenant, et le piège n°1 du projet.

Ce qui doit exister à la fin de la journée

• bun install passe sans avertissement de version
• Le fichier .env existe, copié depuis .env.example
• docker compose ps montre postgres, redis et solver démarrés
• L’application répond sur http://localhost:3000
• L’OpenAPI s’affiche sur http://localhost:3001/docs
• La sonde du solveur répond sur http://localhost:8082/q/health/ready
• Vous savez dire lequel des deux DATABASE_* sert à quoi

Demain

J2 — Les données existent : une application qui répond sur une base vide ne montre rien. Vous allez la peupler — et découvrir qu’il y a trois façons de le faire, pour trois besoins différents.