veza/GUIDE_DEMARRAGE_INTEGRATION.md

🚀 Guide de Démarrage - Test Intégration Veza

Objectif: Lancer l'environnement complet pour tester l'intégration backend ↔ frontend dans le navigateur.

---

📋 État des Lieux

Infrastructure (Docker Compose)

• PostgreSQL: Port 5432 (user: veza, password: password, db: veza)
• Redis: Port 6379 (pour CSRF, cache, rate limiting)
• RabbitMQ: Ports 5672 (AMQP) et 15672 (Management UI)

Services

• Backend Go: Port 8080 (veza-backend-api/)
• Frontend React: Port 3000 (apps/web/) - configuré dans vite.config.ts
• Chat Server Rust: Port 8081 (optionnel pour tests)
• Stream Server Rust: Port 8082 (optionnel pour tests)

Commandes Disponibles

Makefile (Racine)

make help              # Affiche toutes les commandes
make setup             # Installation complète (deps + tools)
make infra-up          # Démarrer infrastructure Docker
make infra-down        # Arrêter infrastructure Docker
make db-migrate        # Exécuter migrations DB
make dev               # Démarrer TOUT (infra + backends + frontend)
make dev-backend       # Démarrer backends uniquement
make status            # Vérifier santé des services

Frontend (apps/web/)

npm run dev            # Démarrer Vite dev server (port 3000)
npm run build          # Build production
npm run typecheck      # Vérifier types TypeScript
npm run test           # Tests unitaires
npm run test:e2e       # Tests E2E Playwright

Backend (veza-backend-api/)

go run cmd/api/main.go # Démarrer serveur (port 8080)
make run               # Build + run
make dev               # Run en mode dev

---

🎯 Démarrage Rapide (Recommandé)

Option 1: Tout-en-un avec Makefile

# 1. Installation initiale (une seule fois)
make setup

# 2. Démarrer l'infrastructure Docker
make infra-up

# 3. Exécuter les migrations
make db-migrate

# 4. Démarrer TOUT (infra + backends + frontend)
make dev

Résultat:

• ✅ Infrastructure Docker démarrée
• ✅ Backend Go sur http://localhost:8080
• ✅ Frontend React sur http://localhost:3000
• ✅ Hot reload activé si outils installés (air, cargo-watch)

Accès:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080/api/v1
• Swagger: http://localhost:8080/docs
• RabbitMQ UI: http://localhost:15672 (veza/password)

---

Option 2: Démarrage Manuel (Plus de contrôle)

Étape 1: Infrastructure Docker

# Démarrer Postgres, Redis, RabbitMQ
make infra-up

# Vérifier que tout est prêt
make status

Étape 2: Migrations Base de Données

make db-migrate

Étape 3: Backend Go

cd veza-backend-api

# Créer fichier .env si inexistant
cat > .env << EOF
APP_ENV=development
JWT_SECRET=dev-secret-key-minimum-32-characters-long-for-testing
DATABASE_URL=postgres://veza:password@localhost:5432/veza?sslmode=disable
REDIS_URL=redis://localhost:6379
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
APP_PORT=8080
LOG_LEVEL=INFO
EOF

# Démarrer le serveur
go run cmd/api/main.go

# OU avec hot reload (si air installé)
air

Vérification Backend:

curl http://localhost:8080/health
# Devrait retourner: {"status":"ok"}

Étape 4: Frontend React

cd apps/web

# Installer dépendances (si pas déjà fait)
npm install

# Démarrer Vite dev server
npm run dev

Vérification Frontend:

• Ouvrir http://localhost:3000 dans le navigateur
• La page devrait se charger

---

⚙️ Configuration Requise

Variables d'Environnement Backend

Fichier: veza-backend-api/.env

# REQUIS
APP_ENV=development
JWT_SECRET=dev-secret-key-minimum-32-characters-long-for-testing
DATABASE_URL=postgres://veza:password@localhost:5432/veza?sslmode=disable

# REQUIS pour CSRF (en développement, Redis peut être optionnel)
REDIS_URL=redis://localhost:6379

# REQUIS pour CORS (en développement, defaults locaux OK)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Optionnel
APP_PORT=8080
LOG_LEVEL=INFO
UPLOAD_DIR=uploads

Variables d'Environnement Frontend

Fichier: apps/web/.env (optionnel, valeurs par défaut OK)

# Optionnel - Valeurs par défaut utilisées si non défini
VITE_API_URL=http://127.0.0.1:8080/api/v1
VITE_WS_URL=ws://127.0.0.1:8081/ws
VITE_STREAM_URL=ws://127.0.0.1:8082/stream
VITE_UPLOAD_URL=http://127.0.0.1:8080/upload

Note: Les valeurs par défaut dans apps/web/src/config/env.ts sont correctes pour le développement local.

---

🔍 Vérification de l'Intégration

1. Vérifier Backend

# Health check
curl http://localhost:8080/health

# Swagger UI
open http://localhost:8080/docs

# Test endpoint API
curl http://localhost:8080/api/v1/auth/check-username?username=test

2. Vérifier Frontend

# Ouvrir dans le navigateur
open http://localhost:3000

# Vérifier console navigateur (F12)
# Devrait voir: connexion API réussie

3. Test Complet d'Intégration

1. Ouvrir http://localhost:3000
2. Tester Register/Login:
   • Créer un compte
   • Se connecter
   • Vérifier que le token est stocké
3. Tester API:
   • Ouvrir DevTools → Network
   • Vérifier que les requêtes incluent Authorization: Bearer <token>
   • Vérifier que les mutations incluent X-CSRF-Token
4. Tester Upload Track:
   • Uploader un fichier audio
   • Vérifier progression
   • Vérifier que le track apparaît dans la liste

---

🐛 Dépannage

Problème: Port déjà utilisé

# Vérifier ports occupés
lsof -i :8080  # Backend
lsof -i :3000  # Frontend
lsof -i :5432  # Postgres
lsof -i :6379  # Redis

# Tuer processus si nécessaire
kill -9 <PID>

Problème: Backend ne démarre pas

# Vérifier variables d'environnement
cd veza-backend-api
cat .env

# Vérifier connexion DB
docker compose exec postgres psql -U veza -d veza -c "SELECT 1;"

# Vérifier connexion Redis
docker compose exec redis redis-cli ping

# Vérifier logs
go run cmd/api/main.go 2>&1 | tee backend.log

Problème: Frontend ne se connecte pas au backend

# Vérifier URL API dans frontend
cd apps/web
grep -r "VITE_API_URL" src/

# Vérifier CORS
curl -v -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: GET" \
     -X OPTIONS \
     http://localhost:8080/api/v1/auth/me

# Devrait retourner headers CORS

Problème: Erreur CSRF

# Vérifier que Redis est démarré
docker compose ps redis

# Vérifier connexion Redis depuis backend
docker compose exec redis redis-cli ping

# Si Redis down, backend devrait loguer un warning (en dev)
# En production, backend refuse de démarrer

Problème: Migrations échouent

# Réinitialiser DB (⚠️ DESTRUCTIF)
docker compose down -v
docker compose up -d postgres
make db-migrate

# OU manuellement
docker compose exec postgres psql -U veza -d veza -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
make db-migrate

---

📊 Commandes Utiles

Vérifier État des Services

# État Docker
docker compose ps

# Logs en temps réel
docker compose logs -f

# Logs d'un service spécifique
docker compose logs -f postgres
docker compose logs -f redis

# Santé des services
make status

Accès aux Bases de Données

# Postgres shell
make db-shell
# OU
docker compose exec postgres psql -U veza -d veza

# Redis shell
make redis-shell
# OU
docker compose exec redis redis-cli

Arrêter Tout

# Arrêter infrastructure Docker
make infra-down

# Arrêter tout (infra + apps)
# Ctrl+C dans le terminal où make dev tourne
# OU
pkill -f "go run\|vite\|cargo"
make infra-down

---

🎯 Workflow Recommandé

Première Installation

# 1. Installer dépendances système
make setup

# 2. Démarrer infrastructure
make infra-up

# 3. Migrations
make db-migrate

# 4. Vérifier
make status

Développement Quotidien

# Option A: Tout en un (recommandé)
make dev

# Option B: Séparé (plus de contrôle)
# Terminal 1: Infrastructure
make infra-up

# Terminal 2: Backend
cd veza-backend-api && go run cmd/api/main.go

# Terminal 3: Frontend
cd apps/web && npm run dev

Tests d'Intégration

# Backend + Frontend doivent tourner
# Puis dans apps/web:
npm run test:e2e

---

✅ Checklist de Vérification

Avant de tester l'intégration, vérifier:

• Infrastructure Docker démarrée (make infra-up)
• Migrations exécutées (make db-migrate)
• Backend Go démarré sur port 8080
• Frontend React démarré sur port 3000
• Variables d'environnement backend configurées (.env)
• CORS_ALLOWED_ORIGINS inclut http://localhost:3000
• Redis accessible (pour CSRF)
• Postgres accessible (pour données)

Test rapide:

# Backend
curl http://localhost:8080/health

# Frontend
curl http://localhost:3000

---

🎉 Prêt à Tester !

Une fois tout démarré:

1. Ouvrir http://localhost:3000 dans le navigateur
2. Tester le flow complet:
   • Register → Login → Upload Track → Créer Playlist
3. Vérifier DevTools → Network pour voir les requêtes API
4. Vérifier que CORS et CSRF fonctionnent correctement

Bon développement ! 🚀