xpeditis2.0/docs/deployment/PORTAINER_REGISTRY_NAMING.md

# 📋 Portainer Registry - Naming des Images

## 🎯 Question : Comment Nommer les Images dans le Stack ?

Quand vous ajoutez un registry dans Portainer, il y a **3 façons** de référencer les images dans votre stack.

---

## Option 1 : Chemin Complet (✅ RECOMMANDÉ - Fonctionne Toujours)

**Dans le stack** :
```yaml
xpeditis-backend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

xpeditis-frontend:
  image: rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod
```

**Avantages** :
- ✅ Fonctionne peu importe la configuration du registry dans Portainer
- ✅ Explicite et clair
- ✅ Pas d'ambiguïté

**Configuration Registry Portainer** (n'importe laquelle) :
- Name : `Scaleway`
- Registry URL : `rg.fr-par.scw.cloud` **OU** `rg.fr-par.scw.cloud/weworkstudio`
- Username : `nologin`
- Password : `[token]`

---

## Option 2 : Nom Court avec Namespace

**Configuration Registry Portainer** :
- Name : `Scaleway`
- Registry URL : `rg.fr-par.scw.cloud/weworkstudio` (avec le namespace)
- Username : `nologin`
- Password : `[token]`

**Dans le stack** :
```yaml
xpeditis-backend:
  image: xpeditis-backend:preprod

xpeditis-frontend:
  image: xpeditis-frontend:preprod
```

Portainer va automatiquement préfixer avec `rg.fr-par.scw.cloud/weworkstudio/`.

---

## Option 3 : Nom avec Namespace Partiel

**Configuration Registry Portainer** :
- Name : `Scaleway`
- Registry URL : `rg.fr-par.scw.cloud` (sans le namespace)
- Username : `nologin`
- Password : `[token]`

**Dans le stack** :
```yaml
xpeditis-backend:
  image: weworkstudio/xpeditis-backend:preprod

xpeditis-frontend:
  image: weworkstudio/xpeditis-frontend:preprod
```

Portainer va automatiquement préfixer avec `rg.fr-par.scw.cloud/`.

---

## 🔍 Comment Savoir Quelle Option Utiliser ?

### Méthode 1 : Vérifier la Configuration du Registry dans Portainer

1. **Portainer** → **Registries**
2. Trouver votre registry Scaleway
3. Regarder le champ **"Registry URL"**

**Si vous voyez** :
- `rg.fr-par.scw.cloud/weworkstudio` → Utilisez **Option 2** (nom court : `xpeditis-backend:preprod`)
- `rg.fr-par.scw.cloud` → Utilisez **Option 3** (avec namespace : `weworkstudio/xpeditis-backend:preprod`)
- Pas sûr ? → Utilisez **Option 1** (chemin complet, fonctionne toujours)

---

## 📊 Tableau de Décision

| Registry URL dans Portainer | Image dans Stack | Exemple |
|------------------------------|------------------|---------|
| `rg.fr-par.scw.cloud/weworkstudio` | `xpeditis-backend:preprod` | Option 2 |
| `rg.fr-par.scw.cloud` | `weworkstudio/xpeditis-backend:preprod` | Option 3 |
| N'importe lequel | `rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod` | Option 1 (recommandé) |

---

## ✅ Configuration Actuelle (Recommandée)

**Fichier** : `docker/portainer-stack.yml`

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

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

**Pourquoi ?** : Chemin complet, fonctionne peu importe la configuration du registry dans Portainer.

---

## 🧪 Test pour Vérifier

### Sur le Serveur Portainer

```bash
# Test avec le nom complet (devrait toujours marcher si registry configuré)
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# Si erreur "access denied" → Le registry n'est pas correctement configuré ou credentials invalides
# Si succès → Le registry fonctionne ✅
```

### Vérifier que Portainer Utilise le Registry

1. Update le stack avec le nouveau YAML
2. Regarder les logs de déploiement Portainer
3. Devrait voir :
   ```
   Pulling xpeditis-backend (rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod)...
   preprod: Pulling from weworkstudio/xpeditis-backend
   ...
   Status: Downloaded newer image
   ```

---

## ⚠️ Erreurs Courantes

### Erreur 1 : "repository does not exist or may require 'docker login'"

**Cause** : Registry credentials pas configurés ou invalides dans Portainer.

**Solution** :
1. Portainer → Registries → Votre registry Scaleway
2. Vérifier username (`nologin`) et password (token Scaleway)
3. Ou faire `docker login` sur le serveur

---

### Erreur 2 : "manifest unknown"

**Cause** : Le tag n'existe pas dans le registry.

**Vérification** :
```bash
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
```

Si erreur → Le tag n'existe pas, vérifier que la CI/CD a bien push les images.

---

### Erreur 3 : "no matching manifest for linux/arm64"

**Cause** : L'image existe mais pas en ARM64.

**Solution** : Vérifier que la CI/CD build bien en multi-architecture (déjà fait ✅).

---

## 🎯 Recommandation Finale

**Utilisez le chemin complet** : `rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod`

**Avantages** :
- ✅ Fonctionne toujours
- ✅ Pas besoin de deviner la configuration du registry
- ✅ Explicite et debuggable
- ✅ Portable entre environnements

---

**Date** : 2025-11-19
**Configuration Actuelle** : Chemin complet avec `platform: linux/arm64`
**Status** : ✅ Prêt pour déploiement