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

```bash
# 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

```bash
# 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** :

```yaml
# 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)

```bash
# 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** :

- [x] **xpeditis-db** - Status: healthy
- [x] **xpeditis-redis** - Status: running
- [x] **xpeditis-minio** - Status: running
- [x] **xpeditis-backend** - Status: healthy
- [x] **xpeditis-frontend** - Status: running

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

### 3.3 - Test API Backend

```bash
# 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

```bash
# 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

```sql
-- 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

```sql
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

```bash
# 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

```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```bash
# 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** :
```yaml
# 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** :
```bash
# 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

```bash
# 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

```bash
# 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