xpeditis2.0/docs/testing/LOCAL_TESTING.md

🧪 Guide de Test Local avec Docker Compose

Ce guide explique comment tester les images Docker de production localement sur ton Mac.

📋 Prérequis

• Docker Desktop installé sur Mac
• Accès au Scaleway Container Registry (credentials)

🔐 Étape 1: Login au Registry Scaleway

# Login au registry Scaleway
docker login rg.fr-par.scw.cloud/weworkstudio
# Username: nologin
# Password: <TON_REGISTRY_TOKEN>

🚀 Étape 2: Lancer la Stack

# Depuis la racine du projet
cd /Users/david/Documents/xpeditis/dev/xpeditis2.0

# Lancer tous les services
docker-compose -f docker-compose.local.yml up -d

# Suivre les logs
docker-compose -f docker-compose.local.yml logs -f

# Suivre les logs d'un service spécifique
docker-compose -f docker-compose.local.yml logs -f backend
docker-compose -f docker-compose.local.yml logs -f frontend

🔍 Étape 3: Vérifier que Tout Fonctionne

Vérifier les services

# Voir l'état de tous les conteneurs
docker-compose -f docker-compose.local.yml ps

# Devrait afficher:
# NAME                        STATUS    PORTS
# xpeditis-backend-local      Up        0.0.0.0:4000->4000/tcp
# xpeditis-frontend-local     Up        0.0.0.0:3000->3000/tcp
# xpeditis-postgres-local     Up        0.0.0.0:5432->5432/tcp
# xpeditis-redis-local        Up        0.0.0.0:6379->6379/tcp
# xpeditis-minio-local        Up        0.0.0.0:9000-9001->9000-9001/tcp

Tester les endpoints

# Backend Health Check
curl http://localhost:4000/health
# Devrait retourner: {"status":"ok"}

# Frontend
open http://localhost:3000
# Devrait ouvrir l'application dans le navigateur

# Backend API Docs
open http://localhost:4000/api/docs
# Devrait ouvrir Swagger UI

# MinIO Console
open http://localhost:9001
# Login: minioadmin / minioadmin

🛠️ Étape 4: Créer le Bucket MinIO

1. Ouvre MinIO Console: http://localhost:9001
2. Login:
   • Username: minioadmin
   • Password: minioadmin
3. Créer le bucket:
   • Clique sur Buckets → Create Bucket
   • Nom: xpeditis-csv-rates
   • Access Policy: Private
   • Create Bucket

🗄️ Étape 5: Initialiser la Base de Données

# Exécuter les migrations
docker-compose -f docker-compose.local.yml exec backend npm run migration:run

# Ou se connecter à PostgreSQL directement
docker-compose -f docker-compose.local.yml exec postgres psql -U xpeditis -d xpeditis_dev

📊 Étape 6: Tester les Fonctionnalités

1. Créer un compte utilisateur

curl -X POST http://localhost:4000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Test1234!@#$",
    "firstName": "Test",
    "lastName": "User"
  }'

2. Se connecter

curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Test1234!@#$"
  }'

# Récupère le token JWT de la réponse

3. Tester l'upload CSV (avec token)

TOKEN="<ton_jwt_token>"

curl -X POST http://localhost:4000/api/v1/admin/csv-rates/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/your/file.csv" \
  -F "companyName=Test Company" \
  -F "companyEmail=test@company.com"

4. Vérifier que le CSV est dans MinIO

1. Ouvre http://localhost:9001
2. Va dans Buckets → xpeditis-csv-rates
3. Tu devrais voir le fichier dans csv-rates/test-company.csv

🔄 Commandes Utiles

Redémarrer un service

docker-compose -f docker-compose.local.yml restart backend
docker-compose -f docker-compose.local.yml restart frontend

Voir les logs en temps réel

# Tous les services
docker-compose -f docker-compose.local.yml logs -f

# Backend uniquement
docker-compose -f docker-compose.local.yml logs -f backend

# 100 dernières lignes
docker-compose -f docker-compose.local.yml logs --tail=100 backend

Accéder à un conteneur

# Shell dans le backend
docker-compose -f docker-compose.local.yml exec backend sh

# Shell dans PostgreSQL
docker-compose -f docker-compose.local.yml exec postgres psql -U xpeditis -d xpeditis_dev

# Shell dans Redis
docker-compose -f docker-compose.local.yml exec redis redis-cli -a xpeditis_redis_password

Mettre à jour les images

# Pull les dernières images depuis Scaleway
docker-compose -f docker-compose.local.yml pull

# Redémarre avec les nouvelles images
docker-compose -f docker-compose.local.yml up -d

Nettoyer complètement

# Arrêter et supprimer les conteneurs
docker-compose -f docker-compose.local.yml down

# Supprimer AUSSI les volumes (⚠️ EFFACE LES DONNÉES)
docker-compose -f docker-compose.local.yml down -v

# Nettoyer les images inutilisées
docker system prune -a

🐛 Debugging

Le backend ne démarre pas

# Voir les logs détaillés
docker-compose -f docker-compose.local.yml logs backend

# Erreurs communes:
# - "Cannot connect to database" → Attends que PostgreSQL soit prêt
# - "Redis connection failed" → Vérifie le password Redis
# - "Port already in use" → Change le port dans docker-compose.local.yml

Le frontend ne se connecte pas au backend

# Vérifie les variables d'environnement
docker-compose -f docker-compose.local.yml exec frontend env | grep NEXT_PUBLIC

# Devrait afficher:
# NEXT_PUBLIC_API_URL=http://localhost:4000
# NEXT_PUBLIC_WS_URL=ws://localhost:4000

PostgreSQL ne démarre pas

# Voir les logs
docker-compose -f docker-compose.local.yml logs postgres

# Si "database system is shut down", supprime le volume:
docker-compose -f docker-compose.local.yml down -v
docker-compose -f docker-compose.local.yml up -d postgres

MinIO ne démarre pas

# Voir les logs
docker-compose -f docker-compose.local.yml logs minio

# Redémarre MinIO
docker-compose -f docker-compose.local.yml restart minio

📝 Variables d'Environnement

Backend

Variable	Valeur Locale	Description
DATABASE_HOST	postgres	Nom du service PostgreSQL
DATABASE_PORT	5432	Port PostgreSQL
DATABASE_USER	xpeditis	User PostgreSQL
DATABASE_PASSWORD	xpeditis_dev_password	Password PostgreSQL
DATABASE_NAME	xpeditis_dev	Nom de la DB
REDIS_HOST	redis	Nom du service Redis
REDIS_PASSWORD	xpeditis_redis_password	Password Redis
AWS_S3_ENDPOINT	http://minio:9000	URL MinIO
AWS_ACCESS_KEY_ID	minioadmin	User MinIO
AWS_SECRET_ACCESS_KEY	minioadmin	Password MinIO
AWS_S3_BUCKET	xpeditis-csv-rates	Bucket CSV

Frontend

Variable	Valeur Locale	Description
NEXT_PUBLIC_API_URL	http://localhost:4000	URL du backend
NEXT_PUBLIC_WS_URL	ws://localhost:4000	WebSocket URL

🎯 Workflow de Test Complet

1. Login au registry:

   docker login rg.fr-par.scw.cloud/weworkstudio
   

2. Lancer la stack:

   docker-compose -f docker-compose.local.yml up -d
   

3. Attendre que tout démarre (~30 secondes):

   docker-compose -f docker-compose.local.yml ps
   

4. Créer le bucket MinIO via http://localhost:9001

5. Exécuter les migrations:

   docker-compose -f docker-compose.local.yml exec backend npm run migration:run
   

6. Tester l'application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:4000/api/docs
   • MinIO: http://localhost:9001

7. Arrêter quand fini:

   docker-compose -f docker-compose.local.yml down
   

🚀 Comparer avec la Production

Cette stack locale utilise EXACTEMENT les mêmes images Docker que la production:

• ✅ rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
• ✅ rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod

Différences avec la production:

• ❌ Pas de Traefik (accès direct aux ports)
• ❌ Pas de SSL/HTTPS
• ❌ Credentials simplifiés (minioadmin au lieu de secrets forts)
• ✅ Mais le code applicatif est IDENTIQUE

📊 Monitoring

Ressources utilisées

# Voir la consommation CPU/RAM
docker stats

# Devrait afficher quelque chose comme:
# CONTAINER              CPU %     MEM USAGE / LIMIT     MEM %
# xpeditis-backend       2.5%      180MiB / 7.77GiB     2.26%
# xpeditis-frontend      1.2%      85MiB / 7.77GiB      1.07%
# xpeditis-postgres      0.5%      25MiB / 7.77GiB      0.31%

Vérifier les health checks

docker-compose -f docker-compose.local.yml ps

# La colonne STATUS devrait afficher "Up (healthy)"

🔧 Problèmes Connus

Port déjà utilisé

Si tu as déjà des services qui tournent en local:

# Changer les ports dans docker-compose.local.yml:
# Backend: "4001:4000" au lieu de "4000:4000"
# Frontend: "3001:3000" au lieu de "3000:3000"
# PostgreSQL: "5433:5432" au lieu de "5432:5432"

Erreur "pull access denied"

Tu n'es pas login au registry Scaleway:

docker login rg.fr-par.scw.cloud/weworkstudio

Images trop anciennes

Force le pull des dernières images:

docker-compose -f docker-compose.local.yml pull
docker-compose -f docker-compose.local.yml up -d --force-recreate

📞 Besoin d'Aide?

• Logs backend: docker-compose -f docker-compose.local.yml logs backend
• Logs frontend: docker-compose -f docker-compose.local.yml logs frontend
• Status: docker-compose -f docker-compose.local.yml ps
• Ressources: docker stats