xpeditis2.0/DEPLOYMENT_CHECKLIST.md

🚀 Checklist de Déploiement Portainer - Xpeditis

📋 Vue d'ensemble

Ce document contient la checklist complète pour déployer Xpeditis sur Portainer avec les migrations automatiques et toutes les configurations nécessaires.

---

✅ Pré-requis

• Accès à Portainer (https://portainer.weworkstudio.com)
• Accès au registry Scaleway (rg.fr-par.scw.cloud/weworkstudio)
• Docker installé localement pour build et push des images
• Git branch preprod à jour avec les derniers changements

---

📦 Étape 1 : Build et Push des Images Docker

Backend

# 1. Se positionner dans le dossier backend
cd apps/backend

# 2. Build l'image avec les migrations automatiques
docker build -t rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod .

# 3. Login au registry Scaleway (si nécessaire)
docker login rg.fr-par.scw.cloud/weworkstudio

# 4. Push l'image
docker push rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# 5. Vérifier que l'image est bien pushed
echo "✅ Backend image pushed: preprod ($(date))"

Frontend

# 1. Se positionner dans le dossier frontend
cd apps/frontend

# 2. Build l'image avec Tailwind CSS compilé
docker build -t rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod .

# 3. Push l'image
docker push rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod

# 4. Vérifier que l'image est bien pushed
echo "✅ Frontend image pushed: preprod ($(date))"

⏱️ Temps estimé : 10-15 minutes

---

🔧 Étape 2 : Configuration Portainer

2.1 - Connexion à Portainer

1. Aller sur https://portainer.weworkstudio.com
2. Se connecter avec les identifiants admin
3. Sélectionner l'environnement local

2.2 - Mise à jour du Stack

1. Aller dans Stacks → Trouver xpeditis-preprod (ou créer si inexistant)
2. Cliquer sur Editor
3. Copier-coller le contenu de docker/portainer-stack.yml
4. Vérifier les variables d'environnement critiques :

# Backend - Variables critiques
DATABASE_PASSWORD: 9Lc3M9qoPBeHLKHDXGUf1  # ⚠️ CHANGER EN PRODUCTION
REDIS_PASSWORD: hXiy5GMPswMtxMZujjS2O     # ⚠️ CHANGER EN PRODUCTION
JWT_SECRET: 4C4tQC8qym/evv4zI5DaUE1yy3kilEnm6lApOGD0GgNBLA0BLm2tVyUr1Lr0mTnV  # ⚠️ CHANGER EN PRODUCTION

# CORS - Doit inclure tous les domaines
CORS_ORIGIN: https://app.preprod.xpeditis.com,https://www.preprod.xpeditis.com,https://api.preprod.xpeditis.com

5. Options de déploiement :

   • ✅ Cocher Re-pull image and redeploy
   • ✅ Cocher Prune services
   • ❌ Ne PAS cocher Force redeployment (sauf si nécessaire)

6. Cliquer sur Update the stack

⏱️ Temps estimé : 5 minutes

---

🧪 Étape 3 : Vérification du Déploiement

3.1 - Logs Backend (Migrations)

# Via Portainer UI
# Stacks → xpeditis-preprod → xpeditis-backend → Logs

# Ou via Docker CLI (sur le serveur)
docker logs xpeditis-backend -f --tail 200

# Ce que vous devez voir :
# ✅ 🚀 Starting Xpeditis Backend...
# ✅ ⏳ Waiting for PostgreSQL to be ready...
# ✅ ✅ PostgreSQL is ready
# ✅ 🔄 Running database migrations...
# ✅ ✅ DataSource initialized
# ✅ ✅ Successfully ran X migration(s):
# ✅    - CreateAuditLogsTable1700000001000
# ✅    - CreateNotificationsTable1700000002000
# ✅    - ...
# ✅ ✅ Database migrations completed
# ✅ 🚀 Starting NestJS application...
# ✅ [Nest] Application successfully started

3.2 - État des Containers

Dans Portainer, vérifier que tous les services sont running et healthy :

• xpeditis-db - Status: healthy
• xpeditis-redis - Status: running
• xpeditis-minio - Status: running
• xpeditis-backend - Status: healthy
• xpeditis-frontend - Status: running

⏱️ Temps d'attente : 1-2 minutes (temps de démarrage des migrations)

3.3 - Test API Backend

# Test health endpoint
curl https://api.preprod.xpeditis.com/health
# Expected: {"status":"ok","timestamp":"..."}

# Test authentication
curl -X POST https://api.preprod.xpeditis.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@xpeditis.com",
    "password": "AdminPassword123!"
  }'

# Expected: {"accessToken":"...", "refreshToken":"...", "user":{...}}

3.4 - Test Frontend

1. Ouvrir https://app.preprod.xpeditis.com
2. Vérifier que le CSS est chargé (page stylisée, pas de texte brut)
3. Se connecter avec :
   • Email : admin@xpeditis.com
   • Password : AdminPassword123!
4. Vérifier que le dashboard se charge sans erreur 500

✅ Si tout fonctionne : Déploiement réussi !

---

🗄️ Étape 4 : Vérification de la Base de Données

4.1 - Connexion à PostgreSQL

# Via Portainer UI
# Stacks → xpeditis-preprod → xpeditis-db → Console

# Ou via Docker CLI
docker exec -it xpeditis-db psql -U xpeditis -d xpeditis_preprod

# Commandes utiles :
\dt                          # Liste toutes les tables
\d+ users                    # Schéma de la table users
SELECT * FROM migrations;    # Migrations appliquées
SELECT COUNT(*) FROM ports;  # Nombre de ports (devrait être ~10k)
SELECT * FROM users;         # Liste des utilisateurs

4.2 - Vérifier les Tables Créées

-- Liste des tables essentielles
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

-- Expected tables:
-- ✅ audit_logs
-- ✅ bookings
-- ✅ carriers
-- ✅ containers
-- ✅ csv_bookings
-- ✅ csv_rate_configs
-- ✅ csv_rates
-- ✅ migrations
-- ✅ notifications
-- ✅ organizations
-- ✅ ports
-- ✅ rate_quotes
-- ✅ shipments
-- ✅ users
-- ✅ webhooks

4.3 - Vérifier les Utilisateurs de Test

SELECT email, role, is_active, created_at
FROM users
ORDER BY role DESC;

-- Expected:
-- admin@xpeditis.com    | ADMIN   | true
-- manager@xpeditis.com  | MANAGER | true
-- user@xpeditis.com     | USER    | true

⏱️ Temps estimé : 5 minutes

---

🧹 Étape 5 : Nettoyage (Optionnel)

5.1 - Supprimer les anciennes images

# Sur le serveur Portainer
docker image prune -a --filter "until=24h"

# Vérifier l'espace disque
docker system df

5.2 - Backup de la base de données

# Créer un backup avant déploiement majeur
docker exec xpeditis-db pg_dump -U xpeditis xpeditis_preprod > backup_$(date +%Y%m%d_%H%M%S).sql

# Ou avec Portainer Volumes → xpeditis_db_data → Backup

---

⚠️ Troubleshooting

Problème 1 : Backend crash en boucle

Symptômes :

• Container redémarre constamment
• Logs montrent "Failed to connect to PostgreSQL"

Solution :

# 1. Vérifier que PostgreSQL est healthy
docker ps | grep xpeditis-db

# 2. Vérifier les logs PostgreSQL
docker logs xpeditis-db --tail 50

# 3. Redémarrer PostgreSQL si nécessaire
docker restart xpeditis-db

# 4. Attendre 30s et redémarrer backend
sleep 30
docker restart xpeditis-backend

Problème 2 : Erreur "relation does not exist"

Symptômes :

• API retourne 500
• Logs montrent QueryFailedError: relation "notifications" does not exist

Solution :

# 1. Vérifier que les migrations ont été exécutées
docker logs xpeditis-backend | grep "Database migrations completed"

# 2. Si absent, redémarrer le backend pour forcer les migrations
docker restart xpeditis-backend

# 3. Vérifier les logs de migration
docker logs xpeditis-backend -f

Problème 3 : CSS ne se charge pas (Frontend)

Symptômes :

• Page affiche du texte brut sans style
• Fichier CSS contient @tailwind base;@tailwind components;

Solution :

# 1. Vérifier que le frontend a été rebuild APRÈS la correction du .dockerignore
cd apps/frontend
docker build -t rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod .
docker push rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod

# 2. Dans Portainer, forcer le redéploiement avec Re-pull image
# Stacks → xpeditis-preprod → Update → ✅ Re-pull image

Problème 4 : CORS errors dans le navigateur

Symptômes :

• Console navigateur : Access to XMLHttpRequest has been blocked by CORS policy
• Frontend ne peut pas appeler l'API

Solution :

# Dans portainer-stack.yml, vérifier :
CORS_ORIGIN: https://app.preprod.xpeditis.com,https://www.preprod.xpeditis.com,https://api.preprod.xpeditis.com

# S'assurer qu'il n'y a PAS d'espace après les virgules
# ❌ Mauvais : "https://app.com, https://api.com"
# ✅ Bon     : "https://app.com,https://api.com"

Problème 5 : Login échoue (401 Unauthorized)

Symptômes :

• Identifiants corrects mais login retourne 401
• Logs backend : "Invalid credentials"

Solution :

# 1. Vérifier que les utilisateurs existent
docker exec xpeditis-db psql -U xpeditis -d xpeditis_preprod -c "SELECT email, role FROM users;"

# 2. Si absent, vérifier que la migration SeedTestUsers a été exécutée
docker logs xpeditis-backend | grep "SeedTestUsers"

# 3. Réinitialiser le mot de passe admin manuellement si nécessaire
docker exec xpeditis-db psql -U xpeditis -d xpeditis_preprod -c "
  UPDATE users
  SET password_hash = '\$argon2id\$v=19\$m=65536,t=3,p=4\$...'
  WHERE email = 'admin@xpeditis.com';
"

---

📊 Métriques de Performance

Temps de Démarrage Attendus

Service	Premier démarrage	Redémarrage
PostgreSQL	5-10s	3-5s
Redis	2-3s	1-2s
MinIO	3-5s	2-3s
Backend (avec migrations)	30-60s	15-20s
Frontend	5-10s	3-5s

Healthchecks

Service	Interval	Timeout	Retries
PostgreSQL	10s	5s	5
Redis	10s	5s	5
Backend	30s	10s	3
Frontend	30s	10s	3

---

📝 Commandes Utiles

Portainer CLI

# Redémarrer un service spécifique
docker service scale xpeditis-preprod_xpeditis-backend=0
sleep 5
docker service scale xpeditis-preprod_xpeditis-backend=1

# Voir les logs en temps réel
docker service logs -f xpeditis-preprod_xpeditis-backend

# Inspecter un service
docker service inspect xpeditis-preprod_xpeditis-backend

# Voir l'état du stack
docker stack ps xpeditis-preprod

Base de Données

# Backup complet
docker exec xpeditis-db pg_dump -U xpeditis -F c xpeditis_preprod > backup.dump

# Restore depuis backup
docker exec -i xpeditis-db pg_restore -U xpeditis -d xpeditis_preprod < backup.dump

# Voir la taille de la DB
docker exec xpeditis-db psql -U xpeditis -d xpeditis_preprod -c "
  SELECT pg_size_pretty(pg_database_size('xpeditis_preprod'));
"

# Lister les connexions actives
docker exec xpeditis-db psql -U xpeditis -d xpeditis_preprod -c "
  SELECT count(*) FROM pg_stat_activity;
"

---

✅ Checklist Finale

Avant de considérer le déploiement comme réussi, vérifier :

Infrastructure

• Tous les containers sont running
• PostgreSQL est healthy
• Redis est running
• Backend est healthy (après migrations)
• Frontend est running

Base de Données

• Toutes les migrations sont exécutées
• Table migrations contient 10+ entrées
• Table users contient 3 utilisateurs de test
• Table ports contient ~10 000 entrées
• Table organizations contient des données

API Backend

• /health retourne 200 OK
• /api/v1/auth/login fonctionne avec admin@xpeditis.com
• /api/v1/notifications retourne 401 (normal sans token)
• Logs backend ne montrent pas d'erreurs critiques

Frontend

• Page d'accueil se charge avec CSS
• Login fonctionne
• Dashboard se charge sans erreur 500
• Notifications en temps réel fonctionnent (WebSocket)
• Recherche de tarifs fonctionne

Sécurité

• HTTPS activé sur tous les domaines
• Certificats Let's Encrypt valides
• CORS configuré correctement
• Variables d'environnement sensibles changées (production)
• Mots de passe par défaut changés (production)

---

📞 Contact & Support

En cas de problème lors du déploiement :

1. Vérifier les logs : Portainer → Stacks → xpeditis-preprod → Logs
2. Consulter ce document : Section Troubleshooting
3. Vérifier la documentation : PORTAINER_MIGRATION_AUTO.md

---

📅 Historique des Déploiements

Date	Version	Changements	Statut
2025-11-19	1.0	Migrations automatiques + CSS fix	✅ OK

---

Auteur : Claude Code Dernière mise à jour : 2025-11-19 Version : 1.0