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

Story 6.1: Docker Compose Development

Status: done

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

• Task 1 (AC: #1) — Fichier docker-compose.dev.yml complet avec tous les services
  • 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).
  • 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).
• Task 2 (AC: #1) — Backend FastAPI :8000 avec hot reload
  • 2.1 Backend utilise le Dockerfile existant (docker/backend/Dockerfile) avec une cible adaptée au dev (ex. builder ou stage avec venv).
  • 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).
  • 2.3 Exposer le port 8000. Vérifier que GET http://localhost:8000/health répond une fois les dépendances (DB, Redis) disponibles.
• Task 3 (AC: #1) — Frontend Next.js :3000 avec hot reload
  • 3.1 Frontend utilise docker/frontend/Dockerfile avec une cible dev/builder si présente, sinon adapter pour npm run dev.
  • 3.2 Monter le code frontend en volume ; préserver node_modules et .next via volumes anonymes pour éviter d'écraser les dépendances.
  • 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).
• Task 4 (AC: #1) — PostgreSQL et Redis
  • 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.
  • 4.2 Inclure le service redis (image redis:7-alpine). Optionnel : persistence (volume) et maxmemory pour dev. Healthcheck recommandé.
  • 4.3 Backend dépend de postgres et redis (depends_on avec condition: service_healthy si healthchecks définis).
• Task 5 (AC: #1) — Variables d'environnement depuis .env
  • 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.
  • 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.
• Task 6 — Vérification end-to-end
  • 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.
  • 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