xpeditis2.0/docs/deployment/PORTAINER_DEBUG.md

# 🔍 Debug Portainer - Images ARM64 Disponibles Mais Ne Montent Pas

## ✅ Vérifications Effectuées

### 1. Images Multi-Architecture Présentes dans Registry ✅

**Backend** :
```json
{
  "manifests": [
    { "platform": { "architecture": "amd64", "os": "linux" } },
    { "platform": { "architecture": "arm64", "os": "linux" } }
  ]
}
```

**Frontend** :
```json
{
  "manifests": [
    { "platform": { "architecture": "amd64", "os": "linux" } },
    { "platform": { "architecture": "arm64", "os": "linux" } }
  ]
}
```

✅ **Conclusion** : Les images ARM64 existent bien dans le registry Scaleway.

### 2. Stack Portainer Correctement Configuré ✅

```yaml
xpeditis-backend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
  # ✅ Tag correct

xpeditis-frontend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod
  # ✅ Tag correct
```

### 3. Dockerfiles ARM64-Compatible ✅

Les deux Dockerfiles utilisent `node:20-alpine` qui supporte ARM64 nativement.

## 🚨 Causes Possibles du Problème

### Cause #1 : Registry Credentials Manquants dans Portainer (PROBABLE)

**Symptôme** : Portainer ne peut pas pull les images privées depuis Scaleway.

**Erreur typique** :
```
Error response from daemon: pull access denied for rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend, repository does not exist or may require 'docker login'
```

**Solution** : Ajouter les credentials du registry Scaleway dans Portainer.

#### Étape 1 : Obtenir les Credentials Scaleway

1. Aller sur [Scaleway Console](https://console.scaleway.com/registry/namespaces)
2. Container Registry → `weworkstudio`
3. **Push/Pull credentials** → Créer ou copier le token
4. Copier :
   - **Username** : `nologin`
   - **Password** : `[le token Scaleway]`

#### Étape 2 : Ajouter Registry dans Portainer

**Option A : Via Interface Portainer**

1. Portainer → **Registries**
2. **Add registry**
3. Remplir :
   - **Name** : `Scaleway Registry`
   - **Registry URL** : `rg.fr-par.scw.cloud/weworkstudio`
   - **Authentication** : ✅ Activer
   - **Username** : `nologin`
   - **Password** : `[token Scaleway]`
4. **Add registry**

**Option B : Via Docker Swarm Secret (Plus sécurisé)**

```bash
# Sur le serveur Portainer
docker login rg.fr-par.scw.cloud/weworkstudio
# Username: nologin
# Password: [token]

# Vérifier que ça marche
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
```

#### Étape 3 : Update le Stack Portainer

1. Aller sur Portainer → **Stacks** → Votre stack
2. **Editor**
3. Cocher **"Re-pull image and redeploy"**
4. **Update the stack**

---

### Cause #2 : Docker Swarm Mode Issues

**Symptôme** : Le stack utilise `deploy.placement.constraints` (ligne 22-25), ce qui signifie que vous êtes en **Docker Swarm mode**.

**Problème connu** : Dans Swarm, les nodes doivent avoir accès au registry individuellement.

**Solution** :

```bash
# Sur CHAQUE node du Swarm
docker login rg.fr-par.scw.cloud/weworkstudio
# Username: nologin
# Password: [token]
```

**Vérifier les nodes Swarm** :

```bash
# Sur le manager
docker node ls

# Devrait montrer tous les nodes READY
```

---

### Cause #3 : Problème de Platform Selection

**Symptôme** : Docker pull la mauvaise architecture (AMD64 au lieu de ARM64).

**Solution** : Forcer la plateforme ARM64 dans le stack Portainer.

**Modifier `portainer-stack.yml`** :

```yaml
xpeditis-backend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
  platform: linux/arm64  # ← Ajouter cette ligne
  restart: unless-stopped
  # ...

xpeditis-frontend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod
  platform: linux/arm64  # ← Ajouter cette ligne
  restart: unless-stopped
  # ...
```

**Note** : Normalement Docker détecte automatiquement l'architecture, mais forcer `platform` garantit le bon choix.

---

### Cause #4 : Problème de Réseau Portainer → Registry

**Symptôme** : Portainer ne peut pas atteindre Scaleway registry depuis le serveur ARM.

**Test** :

```bash
# Sur le serveur Portainer
curl -I https://rg.fr-par.scw.cloud/v2/

# Devrait retourner :
# HTTP/2 401 (Unauthorized est OK, ça signifie que le registry est accessible)
```

Si erreur de connexion :
- Vérifier firewall
- Vérifier DNS
- Vérifier proxy

---

### Cause #5 : Erreur de Build CI/CD (ARM64 Cassé)

**Test** : Vérifier que l'image ARM64 fonctionne en la testant localement.

```bash
# Sur votre Mac (Apple Silicon = ARM64)
docker pull --platform linux/arm64 rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

docker run --rm --platform linux/arm64 \
  -e DATABASE_HOST=test \
  -e DATABASE_PORT=5432 \
  -e DATABASE_USER=test \
  -e DATABASE_PASSWORD=test \
  -e DATABASE_NAME=test \
  -e REDIS_HOST=test \
  -e REDIS_PORT=6379 \
  -e JWT_SECRET=test \
  rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod \
  node -e "console.log('ARM64 works!')"

# Devrait afficher "ARM64 works!" sans erreur
```

Si erreur de build :
- Vérifier les logs GitHub Actions
- Vérifier que buildx a bien compilé ARM64

---

## 🎯 Diagnostic Rapide

### Commandes à Exécuter sur le Serveur Portainer (ARM64)

```bash
# 1. Vérifier architecture du serveur
uname -m
# Devrait afficher : aarch64 ou arm64

# 2. Vérifier que Docker peut voir le registry
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# 3. Tester le pull manuel (SANS login)
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
# Si erreur "access denied" → C'est un problème de credentials ✅

# 4. Login et retry
docker login rg.fr-par.scw.cloud/weworkstudio
# Username: nologin
# Password: [token]

docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
# Devrait maintenant réussir ✅

# 5. Vérifier que c'est bien ARM64
docker image inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod | grep Architecture
# Devrait afficher : "Architecture": "arm64"
```

---

## 📋 Checklist de Résolution

- [ ] **Vérifier que le serveur est bien ARM64** : `uname -m`
- [ ] **Tester pull manuel SANS login** → Si erreur "access denied" = problème credentials
- [ ] **Ajouter registry dans Portainer** : Registries → Add registry → Scaleway
- [ ] **Login Docker sur le serveur** : `docker login rg.fr-par.scw.cloud/weworkstudio`
- [ ] **Si Swarm mode** : Login sur TOUS les nodes
- [ ] **Forcer platform ARM64** : Ajouter `platform: linux/arm64` dans stack
- [ ] **Tester pull manuel AVEC login** → Devrait réussir
- [ ] **Update stack Portainer** avec "Re-pull image and redeploy"
- [ ] **Vérifier logs des conteneurs** : Portainer → Containers → Logs

---

## 🔧 Solution la Plus Probable

**90% du temps, c'est un problème de registry credentials manquants.**

### Solution Rapide (5 minutes)

```bash
# 1. SSH sur le serveur Portainer
ssh votre-serveur

# 2. Login Docker
docker login rg.fr-par.scw.cloud/weworkstudio
# Username: nologin
# Password: [copier le token depuis Scaleway Console]

# 3. Test pull
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# Si ça marche, retourner sur Portainer et update le stack
```

**Ensuite dans Portainer** :
1. Stacks → Votre stack
2. Editor
3. ✅ Cocher "Re-pull image and redeploy"
4. Update the stack

Les conteneurs devraient maintenant démarrer ! 🎉

---

## 📊 Tableau de Diagnostic

| Symptôme | Cause Probable | Solution |
|----------|----------------|----------|
| `access denied` ou `authentication required` | Credentials manquants | Ajouter registry dans Portainer |
| `manifest unknown` | Image n'existe pas | Vérifier tag (`:preprod`) |
| `no matching manifest for linux/arm64` | Image AMD64 uniquement | Rebuild avec ARM64 (déjà fait ✅) |
| Pull réussit mais container crash | Erreur applicative | Vérifier logs container |
| Stuck à "Preparing" | Réseau lent ou proxy | Vérifier connexion Scaleway |

---

**Date** : 2025-11-19
**Status** : 🔍 Diagnostic complet - Attente test sur serveur Portainer
**Action Suivante** : Exécuter les commandes de diagnostic sur le serveur ARM64