92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
# 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 :
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`).
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
docker compose down -v # ⚠️ supprime les données des volumes nommés
|
|
docker compose up -d
|
|
```
|
|
|
|
## 7. Arrêt / redémarrage / nettoyage
|
|
|
|
```bash
|
|
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`) |
|