xpeditis2.0/docs/deployment/PORTAINER_DEPLOY_FINAL.md

# 🚀 Déploiement Portainer - Guide Final

## ✅ Configuration Finale Optimisée

La stack Portainer a été optimisée pour fonctionner parfaitement sur ARM64.

### Modifications Appliquées

1. ✅ **Retiré `platform: linux/arm64`** (non supporté par Compose v3.8)
2. ✅ **Images multi-architecture** (AMD64 + ARM64) dans le registry
3. ✅ **Variables d'environnement** toutes en strings
4. ✅ **Configuration Traefik** complète avec HTTPS
5. ✅ **Healthchecks** pour PostgreSQL et Redis
6. ✅ **Migrations automatiques** au démarrage backend

---

## 📋 Prérequis

### 1. Registry Scaleway Configuré dans Portainer

**Portainer → Registries → Add registry** :

- **Name** : `Scaleway` (ou n'importe quel nom)
- **Registry URL** : `rg.fr-par.scw.cloud/weworkstudio`
- **Authentication** : ✅ Activé
- **Username** : `nologin`
- **Password** : `[votre token Scaleway]`

**Comment obtenir le token** :
1. [Scaleway Console](https://console.scaleway.com/registry/namespaces)
2. Container Registry → `weworkstudio`
3. Push/Pull credentials → Copier le token

### 2. Network Traefik Créé

Le stack utilise un réseau externe `traefik_network` pour Traefik reverse proxy.

**Vérifier** :
```bash
docker network ls | grep traefik
```

**Si absent, créer** :
```bash
docker network create traefik_network
```

### 3. Images Disponibles dans Registry

Vérifier que les images existent :
```bash
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod
```

Devrait afficher les manifests avec `"architecture": "arm64"` ✅

---

## 🚀 Déploiement Étape par Étape

### Étape 1 : Créer le Stack dans Portainer

1. **Portainer** → **Stacks** → **Add stack**
2. **Name** : `xpeditis-preprod`
3. **Build method** : `Web editor`
4. Copier tout le contenu de `docker/portainer-stack.yml`
5. **Deploy the stack**

### Étape 2 : Vérifier le Déploiement

1. **Portainer** → **Stacks** → `xpeditis-preprod`
2. Vérifier que tous les services sont **"running"** :
   - ✅ `xpeditis-db` (PostgreSQL)
   - ✅ `xpeditis-redis` (Redis)
   - ✅ `xpeditis-minio` (MinIO S3)
   - ✅ `xpeditis-backend` (NestJS API)
   - ✅ `xpeditis-frontend` (Next.js)

### Étape 3 : Vérifier les Logs Backend

**Portainer** → **Containers** → `xpeditis-backend` → **Logs**

**Logs attendus** :
```
🚀 Starting Xpeditis Backend...
⏳ Waiting for PostgreSQL to be ready...
✅ PostgreSQL is ready
🔄 Running database migrations...
✅ DataSource initialized
✅ Successfully ran 10 migration(s):
   - CreateUsersTable1700000000000
   - CreateOrganizationsTable1700000001000
   - CreateBookingsTable1700000003000
   - CreateNotificationsTable1700000002000
   - CreateWebhooksTable1700000004000
   - CreateAuditLogsTable1700000001000
   - CreateShipmentsTable1700000005000
   - CreateContainersTable1700000006000
   - AddUserRoleEnum1700000007000
   - AddOrganizationForeignKey1700000008000
✅ Database migrations completed
🚀 Starting NestJS application...
[Nest] 1  - LOG [NestFactory] Starting Nest application...
[Nest] 1  - LOG [InstanceLoader] AppModule dependencies initialized
[Nest] 1  - LOG [RoutesResolver] AppController {/api/v1}:
[Nest] 1  - LOG Application is running on: http://0.0.0.0:4000
```

**Si erreur "relation does not exist"** : Les migrations n'ont pas tourné. Redémarrer le container.

### Étape 4 : Vérifier les Logs Frontend

**Portainer** → **Containers** → `xpeditis-frontend` → **Logs**

**Logs attendus** :
```
▲ Next.js 14.5.0
- Local:        http://localhost:3000
- Network:      http://0.0.0.0:3000

✓ Ready in 2.3s
```

### Étape 5 : Tester les Endpoints

**Backend API** :
```bash
curl https://api.preprod.xpeditis.com/api/v1/health

# Devrait retourner :
{"status":"ok","info":{"database":{"status":"up"},"redis":{"status":"up"}}}
```

**Frontend** :
```bash
curl -I https://app.preprod.xpeditis.com

# Devrait retourner :
HTTP/2 200
```

**MinIO Console** :
```bash
curl -I https://minio.preprod.xpeditis.com

# Devrait retourner :
HTTP/2 200
```

---

## 🔧 Configuration DNS (Si Pas Déjà Fait)

Assurez-vous que ces domaines pointent vers votre serveur :

| Domaine | Type | Valeur | Service |
|---------|------|--------|---------|
| `api.preprod.xpeditis.com` | A | `[IP serveur]` | Backend API |
| `app.preprod.xpeditis.com` | A | `[IP serveur]` | Frontend |
| `www.preprod.xpeditis.com` | CNAME | `app.preprod.xpeditis.com` | Frontend (alias) |
| `s3.preprod.xpeditis.com` | A | `[IP serveur]` | MinIO API |
| `minio.preprod.xpeditis.com` | A | `[IP serveur]` | MinIO Console |

---

## 🔐 Sécurité Post-Déploiement

### 1. Changer les Mots de Passe par Défaut

**PostgreSQL** (lignes 11-13) :
```yaml
POSTGRES_PASSWORD: 9Lc3M9qoPBeHLKHDXGUf1  # ← CHANGER
```

**Redis** (ligne 31) :
```yaml
command: redis-server --requirepass hXiy5GMPswMtxMZujjS2O  # ← CHANGER
```

**MinIO** (lignes 47-48) :
```yaml
MINIO_ROOT_USER: minioadmin_preprod_CHANGE_ME      # ← CHANGER
MINIO_ROOT_PASSWORD: RBJfD0QVXC5JDfAHCwdUW         # ← CHANGER
```

**JWT Secret** (ligne 104) :
```yaml
JWT_SECRET: 4C4tQC8qym/evv4zI5DaUE1yy3kilEnm6lApOGD0GgNBLA0BLm2tVyUr1Lr0mTnV  # ← CHANGER
```

### 2. Update le Stack avec les Nouveaux Secrets

1. **Portainer** → **Stacks** → `xpeditis-preprod`
2. **Editor** → Modifier les valeurs
3. ✅ **Cocher "Re-pull image and redeploy"**
4. **Update the stack**

---

## 📊 Monitoring et Logs

### Vérifier l'État des Services

**Portainer** → **Containers** :

| Container | État Attendu | Healthcheck |
|-----------|--------------|-------------|
| `xpeditis-db` | Running | Healthy (pg_isready) |
| `xpeditis-redis` | Running | - |
| `xpeditis-minio` | Running | - |
| `xpeditis-backend` | Running | Healthy (HTTP /health) |
| `xpeditis-frontend` | Running | Healthy (HTTP /) |

### Logs en Temps Réel

**Portainer** → **Containers** → Sélectionner container → **Logs** :
- ✅ Activer **"Auto-refresh logs"**
- ✅ Sélectionner **"Since" = "Last 100 lines"**

---

## 🔄 Mise à Jour des Images

Quand la CI/CD push de nouvelles images :

### Option 1 : Via Portainer Interface (Recommandé)

1. **Portainer** → **Stacks** → `xpeditis-preprod`
2. ✅ **Cocher "Re-pull image and redeploy"**
3. **Update the stack**

### Option 2 : Via CLI

```bash
# SSH sur le serveur
ssh votre-serveur

# Pull les nouvelles images
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod

# Redémarrer le stack dans Portainer
# (ou via docker stack deploy si en mode Swarm)
```

---

## ⚠️ Troubleshooting

### Erreur : "access denied" lors du pull

**Cause** : Registry credentials invalides ou manquants.

**Solution** :
1. Vérifier **Portainer → Registries** → Credentials Scaleway
2. Ou faire `docker login` sur le serveur :
   ```bash
   docker login rg.fr-par.scw.cloud/weworkstudio
   # Username: nologin
   # Password: [token]
   ```

### Erreur : "relation does not exist"

**Cause** : Migrations pas exécutées ou base de données corrompue.

**Solution** :
1. Vérifier les logs backend : migrations doivent s'exécuter au démarrage
2. Si nécessaire, supprimer le volume et recréer :
   ```bash
   docker volume rm xpeditis_db_data
   # Redéployer le stack → migrations créeront les tables
   ```

### Erreur : "network traefik_network not found"

**Cause** : Le réseau Traefik n'existe pas.

**Solution** :
```bash
docker network create traefik_network
```

### Backend reste en "Unhealthy"

**Cause** : L'application ne démarre pas ou le healthcheck échoue.

**Solution** :
1. Vérifier logs backend : `docker logs xpeditis-backend`
2. Vérifier que PostgreSQL et Redis sont accessibles
3. Tester manuellement le healthcheck :
   ```bash
   docker exec xpeditis-backend curl http://localhost:4000/api/v1/health
   ```

---

## ✅ Checklist de Déploiement

- [ ] Registry Scaleway configuré dans Portainer
- [ ] Network `traefik_network` créé
- [ ] Images ARM64 disponibles dans registry (`preprod` tag)
- [ ] DNS configurés (api, app, s3, minio)
- [ ] Stack créé dans Portainer
- [ ] Tous les services en état "running"
- [ ] Logs backend : migrations exécutées ✅
- [ ] Endpoint backend accessible : `https://api.preprod.xpeditis.com/api/v1/health`
- [ ] Frontend accessible : `https://app.preprod.xpeditis.com`
- [ ] MinIO accessible : `https://minio.preprod.xpeditis.com`
- [ ] Mots de passe par défaut changés
- [ ] Certificats HTTPS générés par Let's Encrypt

---

## 🎯 Résumé des URLs

| Service | URL | Login |
|---------|-----|-------|
| **Frontend** | https://app.preprod.xpeditis.com | - |
| **API Backend** | https://api.preprod.xpeditis.com/api/v1 | - |
| **API Docs (Swagger)** | https://api.preprod.xpeditis.com/api/docs | - |
| **MinIO Console** | https://minio.preprod.xpeditis.com | minioadmin_preprod / [password] |
| **Portainer** | https://portainer.votre-domaine.com | [vos credentials] |

---

**Date** : 2025-11-19
**Version Stack** : Finale optimisée pour Portainer ARM64
**Status** : ✅ Prêt pour production pre-prod