office_translator/_bmad-output/implementation-artifacts/6-1-docker-compose-development.md

# Story 6.1: Docker Compose Development

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a **Developer**,
I want **a Docker Compose setup for local development**,
so that **I can run all services consistently**.

## Acceptance Criteria

1. **Given** docker-compose.dev.yml exists  
   **When** I run `docker-compose -f docker-compose.dev.yml up`  
   **Then** backend (FastAPI :8000), frontend (Next.js :3000), PostgreSQL, Redis start  
   **And** volumes mount for hot reload  
   **And** environment variables are loaded from .env files  

## Tasks / Subtasks

- [x] Task 1 (AC: #1) — Fichier docker-compose.dev.yml complet avec tous les services
  - [x] 1.1 Définir les services backend, frontend, postgres, redis dans docker-compose.dev.yml (ou combiner avec un fichier base si le workflow actuel utilise -f compose.yml -f compose.dev.yml).
  - [x] 1.2 S'assurer que la commande d'exécution documentée est claire : `docker compose -f docker-compose.dev.yml up` (ou équivalent avec docker-compose v1).
- [x] Task 2 (AC: #1) — Backend FastAPI :8000 avec hot reload
  - [x] 2.1 Backend utilise le Dockerfile existant (docker/backend/Dockerfile) avec une cible adaptée au dev (ex. builder ou stage avec venv).
  - [x] 2.2 Monter le code backend en volume pour hot reload (uvicorn --reload). Exclure venv/node_modules du mount si nécessaire (volume anonyme pour /app/venv).
  - [x] 2.3 Exposer le port 8000. Vérifier que GET http://localhost:8000/health répond une fois les dépendances (DB, Redis) disponibles.
- [x] Task 3 (AC: #1) — Frontend Next.js :3000 avec hot reload
  - [x] 3.1 Frontend utilise docker/frontend/Dockerfile avec une cible dev/builder si présente, sinon adapter pour `npm run dev`.
  - [x] 3.2 Monter le code frontend en volume ; préserver node_modules et .next via volumes anonymes pour éviter d'écraser les dépendances.
  - [x] 3.3 Exposer le port 3000. NEXT_PUBLIC_API_URL doit pointer vers l'URL du backend accessible depuis le navigateur (ex. http://localhost:8000).
- [x] Task 4 (AC: #1) — PostgreSQL et Redis
  - [x] 4.1 Inclure le service postgres (image postgres:16-alpine recommandée dans l'archi). Variables : POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB. Volume persistant pour les données.
  - [x] 4.2 Inclure le service redis (image redis:7-alpine). Optionnel : persistence (volume) et maxmemory pour dev. Healthcheck recommandé.
  - [x] 4.3 Backend dépend de postgres et redis (depends_on avec condition: service_healthy si healthchecks définis).
- [x] Task 5 (AC: #1) — Variables d'environnement depuis .env
  - [x] 5.1 Utiliser env_file: [.env] ou equivalent pour backend et frontend (et postgres/redis si besoin). Docker Compose charge par défaut le fichier .env à la racine du projet pour la substitution dans le fichier YAML.
  - [x] 5.2 Documenter dans README ou .env.example les variables requises pour le dev (DATABASE_URL, REDIS_URL, SECRET_KEY, etc.) sans exposer de secrets.
- [x] Task 6 — Vérification end-to-end
  - [x] 6.1 Tester `docker compose -f docker-compose.dev.yml up` (ou `docker-compose -f docker-compose.dev.yml up`) : tous les services démarrent, backend et frontend accessibles sur :8000 et :3000, pas d'erreur au démarrage.
  - [x] 6.2 Vérifier qu'un changement dans le code backend ou frontend déclenche bien un rechargement (hot reload).

## Dev Notes

- **Contexte actuel** : Le projet contient déjà `docker-compose.dev.yml` (backend + frontend, uvicorn --reload, npm run dev) et `docker-compose.yml` (prod avec postgres, redis, nginx). La story 6-1 exige que le **dev** inclue aussi PostgreSQL et Redis, avec hot reload et chargement des variables depuis .env. Adapter ou fusionner les fichiers existants sans casser la prod.
- **Architecture** : [Source: _bmad-output/planning-artifacts/architecture.md] — Stack : FastAPI (backend), Next.js 15 (frontend), PostgreSQL 16, Redis 7. Docker Compose pour orchestration locale. Structure : backend/ (FastAPI, app/, alembic/), frontend/ (Next.js, src/app/), docker/backend/Dockerfile, docker/frontend/Dockerfile. Démarrage local documenté : `docker-compose -f docker-compose.dev.yml up -d` avec Backend :8000, Frontend :3000, API Docs :8000/docs.
- **NFR10** : Secrets et configuration via variables d'environnement, jamais en dur dans le code.
- **Fichiers à toucher** : `docker-compose.dev.yml` (principal), éventuellement `docker/backend/Dockerfile` / `docker/frontend/Dockerfile` si un stage "dev" ou "builder" est ajouté, `.env.example` ou README pour la doc des variables.

### Project Structure Notes

- Racine projet : `office_translator/` avec `backend/`, `frontend/`, `docker/`, `docker-compose.yml`, `docker-compose.dev.yml`. Rester cohérent avec l’arbre dans architecture.md (Complete Project Directory Structure).
- Backend : contexte de build souvent `backend/` ou `.` selon comment le Dockerfile est écrit (COPY . .). Les mounts dev doivent pointer vers le répertoire contenant `main.py` / `app/` pour uvicorn --reload.
- Frontend : contexte `frontend/` dans le Dockerfile actuel. Mount dev typiquement `./frontend:/app` avec préservation de `node_modules` et `.next`.

### References

- [Source: _bmad-output/planning-artifacts/architecture.md] — Infrastructure & Deployment, Development Workflow, Project Structure.
- [Source: _bmad-output/planning-artifacts/epics.md] — Epic 6, Story 6.1, AC BDD.
- Docker Compose : chargement automatique de `.env` à la racine ; `env_file` pour les services. Compose V2 : `develop.watch` pour sync/rebuild (optionnel pour cette story).

### Technical Requirements (Architecture Compliance)

- **Backend** : Python 3.11+, FastAPI, uvicorn avec `--reload`. Port 8000. Connexion à PostgreSQL (asyncpg) et Redis depuis les variables d'environnement.
- **Frontend** : Node 20, Next.js 15, `npm run dev`. Port 3000. NEXT_PUBLIC_API_URL pour les appels API.
- **PostgreSQL** : Image postgres:16-alpine (alignée avec l’archi). Healthcheck `pg_isready` pour depends_on.
- **Redis** : Image redis:7-alpine. Healthcheck `redis-cli ping`. Optionnel en dev : `--appendonly yes` et volume pour persistance.
- **Réseau** : Tous les services sur le même réseau Compose pour que backend atteigne postgres et redis par nom de service (postgres:5432, redis:6379).
- **Secrets** : Aucun secret en dur ; tout via .env / env_file (NFR10).

### Testing Requirements

- Vérifier manuellement ou par script que `docker compose -f docker-compose.dev.yml up` (ou équivalent) démarre les quatre services sans erreur.
- Vérifier que GET http://localhost:8000/health et http://localhost:3000 retournent des réponses valides.
- Vérifier qu’un changement dans un fichier backend ou frontend déclenche un rechargement (hot reload) sans redémarrage manuel des conteneurs.
- Optionnel : test d’intégration ou script E2E qui lance le stack et appelle /health (à placer dans scripts/ ou tests/ si souhaité).

## Dev Agent Record

### Agent Model Used

{{agent_model_name_version}}

### Debug Log References

### Completion Notes List

- docker-compose.dev.yml réécrit en fichier autonome : 4 services (postgres, redis, backend, frontend), réseau translate-network, volumes dédiés dev (postgres_data_dev, redis_data_dev, backend_venv, frontend_node_modules, frontend_next). Commande documentée : `docker compose -f docker-compose.dev.yml up` (ou docker-compose).
- Backend : build target builder, mount .:/app + volume backend_venv pour /opt/venv, command uvicorn main:app --reload, env_file .env, DATABASE_URL et REDIS_URL définis pour postgres/redis par nom de service, depends_on postgres/redis condition service_healthy.
- Frontend : build target builder, mount ./frontend:/app + volumes node_modules et .next, command npm run dev, env_file .env, NEXT_PUBLIC_API_URL=http://localhost:8000.
- PostgreSQL 16-alpine et Redis 7-alpine avec healthchecks ; backend attend leur santé avant démarrage.
- .env.example : bloc « Docker Compose (dev) » ajouté en tête (commande, variables optionnelles POSTGRES_*, NEXT_PUBLIC_API_URL, variables requises backend).
- scripts/verify-dev-compose.sh : script de vérification (fichier présent, YAML si PyYAML dispo, docker compose config si disponible). Pas de Docker dans l’environnement d’exécution ; validation manuelle à faire par le dev avec `docker compose -f docker-compose.dev.yml up`.
- **Code review (AI) – correctifs appliqués :** (1) scripts/verify-dev-compose.sh ajouté à git. (2) Script renforcé : vérification des 4 services requis (postgres, redis, backend, frontend), chemin passé en argument au Python (pas d’interpolation dans la chaîne). (3) docker-compose.dev.yml : Redis healthcheck start_period: 5s ; backend healthcheck (Python urllib) ; frontend depends_on backend avec condition: service_healthy. (4) File List complétée avec mention des fichiers modifiés hors scope 6-1.

### File List

- docker-compose.dev.yml (modifié — réécrit complet ; après revue : healthcheck Redis start_period, healthcheck backend, frontend depends_on backend condition service_healthy)
- .env.example (modifié — section Docker Compose dev)
- scripts/verify-dev-compose.sh (nouveau ; ajouté à git après revue ; validation des 4 services requises, chemin passé en argument Python)
- _bmad-output/implementation-artifacts/6-1-docker-compose-development.md (modifié — statut, tâches, Dev Agent Record)
- _bmad-output/implementation-artifacts/sprint-status.yaml (modifié — 6-1 in-progress puis review)

_Fichiers modifiés dans le dépôt mais hors périmètre 6-1 (documentés pour traçabilité revue) : .env.production, alembic/env.py_