Environnement de dev local

Toute la stack se lance avec un seul script : dev-up.sh, qui orchestre docker-compose.dev.yml.

Pré-requis

Docker + Docker Compose v2
Node 22 + pnpm 10 (pour reconstruire les bundles adapters si besoin)
Trois fichiers d’environnement présents (sinon le script s’arrête en vous le disant) :
- api/.env
- checkout-page/.env.local
- demo-shop/.env.local
Chacun se copie depuis son *.example puis se remplit (secrets PSP, clés…).

Lancer la stack

# build + up de tous les services, migration Firebird idempotente, données préservées
./dev-up.sh

# idem + crée super-admin, marchand de test, user marchand (pour se connecter aux consoles)
./dev-up.sh --seed

# WIPE des volumes (perte des données Firebird/MariaDB/PrestaShop) puis rebuild à neuf
./dev-up.sh --fresh

Ce que dev-up.sh enchaîne (voir dev-up.sh pour le détail) :

flowchart TD
  A[Vérifie api/.env, checkout-page/.env.local, demo-shop/.env.local] --> B[Build bundles adapters si dist manquant]
  B --> C[docker compose up -d --build]
  C --> D[Attend API /health OK]
  D --> E[Migration Firebird idempotente: api-migrate]
  E --> F{--seed ?}
  F -->|oui| G[keygen-admin-bootstrap + setup-test-merchant + seed-merchant-user]
  F -->|non| H[Récap URLs]
  G --> H

URLs & ports

Service	URL
API	`http://localhost:3000`
Checkout page	`http://localhost:3100`
Demo shop	`http://localhost:3200`
CDN adapters	`:3300` `:3301` `:3302`
Console admin	`http://localhost:3400`
Console merchant	`http://localhost:3500`
PrestaShop	`http://localhost:3600` (back-office sous `admin-titreo/`)

La carte complète et raisonnée est sur Carte des ports locaux.

Services du compose

docker-compose.dev.yml orchestre tous les projets en un stack unique :

Applicatif : api, worker-outbox, checkout-page, demo-shop, demo-shop-prestashop, console-admin, console-merchant, 3 CDN nginx servant les bundles adapters (adyen / stripe / titreo-gift).
Infra : redis, firebird, mariadb, cloudflared (tunnel public pour recevoir les webhooks Adyen en dev — l’URL *.trycloudflare.com change à chaque redémarrage).

Identifiants de seed (par défaut)

Le mode --seed crée des comptes de dev (surchargeables par variables d’environnement, voir l’en-tête de dev-up.sh) :

Compte	Identifiant	Mot de passe
Super-admin (console-admin)	`admin@titreo-epay.local`	`Admin-Dev-2026!`
Marchand (console-merchant)	`dev@titreo-epay.local`	`MerchantDev2026!`

Le marchand de test (merchant-demo, « Maison Générique ») est créé avec une API key, une config PSP (Stripe par défaut) et une URL de webhook pointant vers le demo-shop.

Travailler sur le backend seul

Hors Docker (si l’addon Firebird compile chez vous), les scripts utiles de api/package.json :

Commande	Effet
`pnpm dev`	Serveur HTTP en watch (`tsx watch src/http/server.ts`)
`pnpm db:migrate`	Applique les migrations Firebird
`pnpm worker:outbox`	Lance le worker outbox (traite les paiements asynchrones)
`pnpm worker:cleanup`	Lance le worker de nettoyage des sessions expirées
`pnpm test`	Tests Vitest
`pnpm test:integration`	Tests d’intégration (Firebird requis)
`pnpm gen:openapi`	Régénère `docs/openapi.json` depuis les schémas Zod

La liste complète des scripts de génération de clés et de seed est détaillée sur Scripts.

En cas de problème

API ne devient pas healthy : docker compose -f docker-compose.dev.yml logs api.
Webhooks Adyen : récupérer l’URL du tunnel avec docker compose -f docker-compose.dev.yml logs cloudflared | grep trycloudflare.
Seed PSP échoue : vérifier les credentials PSP dans api/.env.

Runbook détaillé d’intégration Adyen de bout en bout : E2E-ADYEN.md dans le dépôt.