flashcards/docs/MOD_OP.md

MOD_OP — Mode opératoire (lancement et exploitation)

Procédure pas à pas pour lancer, vérifier, développer et arrêter l'application flashcards (web + MySQL + MongoDB en conteneurs Docker).

1. Prérequis

• Docker + Docker Compose installés et démarrés.
• Node.js >= 20.19.0 et pnpm >= 9 (uniquement pour le mode dev local, étape 5).

2. Démarrage complet (production-like)

Depuis la racine du projet :

docker compose up -d --build

• --build : construit l'image du service web (nécessaire à la première exécution).
• Le service web attend que mysql et mongo soient healthy (depends_on + healthchecks).

Résultat attendu (3 conteneurs up) :

Service	Conteneur	Image	Port hôte	Port interne
web	flashcards-web	(build .)	4000	3000
mysql	flashcards-mysql	mysql:8.4	13306	3306
mongo	flashcards-mongo	mongo:8.2	27018	27017

Attention : le port hôte 4000 a été retenu car 3000/3001 sont souvent occupés par d'autres processus. Le web écoute donc sur http://localhost:4000.

3. Vérifications

docker compose ps                 # 3 services "running" (mysql/mongo "healthy")
curl http://localhost:4000/api/themes
curl http://localhost:4000/api/cards

• La liste des thèmes doit répondre ["docker","git","javascript","react","typescript"] (seed).
• Ouvrir http://localhost:4000 : accueil, puis /play (tirage de cartes), /cards et /cards/new (CRUD).

4. Choisir l'implémentation SGBD (DB_IMPL)

L'application est branchée sur une couche générique : MySQL (mysql, défaut) ou MongoDB (mongo).

docker compose stop web
DB_IMPL=mongo docker compose up -d web      # bascule sur MongoDB
DB_IMPL=mysql docker compose up -d web      # retour sur MySQL (défaut)

5. Mode développement local (hot reload)

Les bases restent en Docker, l'appli tourne en local :

cp .env.example .env
docker compose up -d mysql mongo             # bases seules
pnpm install
pnpm dev                                     # http://localhost:3000

Le .env pointe vers les ports exposés des conteneurs (localhost:13306, localhost:27018) et DB_IMPL=mysql par défaut.

6. Ré-initialiser le seed

Les scripts docker/init/* ne s'exécutent qu'à la première création des volumes (y compris l'encodage UTF-8 forcé par 02-seed.sh). Pour repartir d'un état vierge :

docker compose down -v     # ⚠️ supprime les données des volumes nommés
docker compose up -d

7. Arrêt / redémarrage / nettoyage

docker compose stop        # arrêt (données conservées)
docker compose start       # redémarrage
docker compose restart web # redémarrage du web seul
docker compose down        # arrêt + suppression des conteneurs (volumes conservés)
docker compose down -v     # arrêt + suppression des conteneurs ET des volumes

8. Dépannage rapide

Symptôme	Action
Le web ne démarre pas	docker compose logs web (il attend le healthy des bases)
Authentication failed (Mongo)	Vérifier ?authSource=admin dans MONGODB_URI
Caractères accentués illisibles (MySQL)	Seed importé sans utf8mb4 → réinitialiser via l'étape 6
Port déjà utilisé	Le web est sur le port hôte 4000 (modifiable dans docker-compose.yml)