xpeditis2.0/ARM64_SUPPORT.md

# Support Multi-Architecture (ARM64 + AMD64)

## 🎯 Problème Résolu

Le serveur Portainer tourne sur architecture **ARM64**, mais la CI/CD buildait uniquement des images **AMD64**. Cela causait des erreurs de compatibilité lors du déploiement.

## ✅ Solution Implémentée

La CI/CD build maintenant des images **multi-architecture** compatibles ARM64 et AMD64.

### Modifications dans `.github/workflows/ci.yml`

**Backend (ligne 73)** :
```yaml
platforms: linux/amd64,linux/arm64
```

**Frontend (ligne 141)** :
```yaml
platforms: linux/amd64,linux/arm64
```

## 📦 Images Multi-Architecture

Lorsque la CI/CD push vers le registry Scaleway, elle crée des **manifests multi-architecture** :

```bash
# Backend
rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
  ├── linux/amd64
  └── linux/arm64

# Frontend
rg.fr-par.scw.cloud/weworkstudio/xpeditis-frontend:preprod
  ├── linux/amd64
  └── linux/arm64
```

Docker/Portainer sélectionne automatiquement l'architecture correcte lors du pull.

## ⚙️ Comment Ça Fonctionne

**Docker Buildx** utilise **QEMU emulation** sur GitHub Actions pour compiler les images ARM64 sur des runners AMD64 :

1. `docker/setup-buildx-action@v3` active Buildx
2. Buildx détecte les plateformes `linux/amd64,linux/arm64`
3. Compile nativement pour AMD64
4. Utilise QEMU pour cross-compiler vers ARM64
5. Crée un manifest avec les deux architectures
6. Push tout vers le registry

## 🚀 Déploiement

### Sur Serveur ARM64 (Portainer)

```bash
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
# ✅ Pull automatiquement l'image linux/arm64
```

### Sur Serveur AMD64 (Cloud classique)

```bash
docker pull rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod
# ✅ Pull automatiquement l'image linux/amd64
```

## 📊 Impact sur le Build Time

Le build multi-architecture prend environ **2x plus de temps** :
- Build AMD64 seul : ~5-7 min
- Build AMD64 + ARM64 : ~10-15 min

C'est normal car il compile deux fois l'image (une pour chaque architecture).

## 🔍 Vérifier l'Architecture d'une Image

```bash
# Voir les architectures disponibles
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# Output attendu :
# {
#   "manifests": [
#     { "platform": { "architecture": "amd64", "os": "linux" } },
#     { "platform": { "architecture": "arm64", "os": "linux" } }
#   ]
# }
```

## 📝 Checklist de Déploiement (Mise à Jour)

### 1. Configurer GitHub Secret `REGISTRY_TOKEN`
- Aller sur [Scaleway Console](https://console.scaleway.com/registry/namespaces)
- Container Registry → weworkstudio → Push/Pull credentials
- Copier le token
- GitHub → Settings → Secrets → Actions → New repository secret
- Nom : `REGISTRY_TOKEN`

### 2. Commit et Push vers `preprod`

```bash
git add .
git commit -m "feat: add ARM64 support for multi-architecture builds"
git push origin preprod
```

### 3. Vérifier le Build CI/CD

Aller sur [GitHub Actions](https://github.com/VOTRE_USERNAME/xpeditis/actions) et attendre :
- ✅ Backend - Build, Test & Push (10-15 min)
- ✅ Frontend - Build, Test & Push (10-15 min)

### 4. Vérifier les Images dans le Registry

```bash
# Lister les images
docker manifest inspect rg.fr-par.scw.cloud/weworkstudio/xpeditis-backend:preprod

# Devrait montrer linux/amd64 ET linux/arm64
```

### 5. Déployer sur Portainer (ARM64)

1. Copier le contenu de `docker/portainer-stack.yml`
2. Aller sur Portainer → Stacks → Update stack
3. Cocher "Re-pull image and redeploy"
4. Click "Update"

Portainer va automatiquement pull les images ARM64 compatibles ! 🎉

## 🛠️ Troubleshooting

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

**Cause** : L'image a été buildée avant l'ajout du support ARM64.

**Solution** : Re-trigger la CI/CD pour rebuild avec les deux architectures.

### Build Timeout sur GitHub Actions

**Cause** : Le build ARM64 via QEMU peut être lent.

**Solution** : Augmenter le timeout dans `.github/workflows/ci.yml` :

```yaml
jobs:
  backend:
    timeout-minutes: 30  # Défaut est 360, mais on peut réduire à 30
```

### Image ARM64 Trop Lente au Démarrage

**Cause** : C'est normal, QEMU émulation est plus lent que natif.

**Alternative** : Utiliser des runners ARM64 natifs (GitHub n'en propose pas gratuitement, mais Scaleway/AWS oui).

## 📚 Ressources

- [Docker Buildx Multi-Platform](https://docs.docker.com/build/building/multi-platform/)
- [GitHub Actions ARM64 Support](https://github.blog/changelog/2024-06-03-github-actions-arm64-linux-and-windows-runners-are-now-generally-available/)
- [Scaleway Container Registry](https://www.scaleway.com/en/docs/containers/container-registry/)

## ✅ Résumé

| Avant | Après |
|-------|-------|
| ❌ Build AMD64 uniquement | ✅ Build AMD64 + ARM64 |
| ❌ Incompatible avec serveur ARM | ✅ Compatible tous serveurs |
| ⚡ Build rapide (~7 min) | 🐢 Build plus lent (~15 min) |
| 📦 1 image par tag | 📦 2 images par tag (manifest) |

---

**Date** : 2025-01-19
**Status** : ✅ Implémenté et prêt pour déploiement