xpeditis2.0/docs/deployment/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) :

platforms: linux/amd64,linux/arm64

Frontend (ligne 141) :

platforms: linux/amd64,linux/arm64

📦 Images Multi-Architecture

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

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

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

Sur Serveur AMD64 (Cloud classique)

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

# 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
• 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

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 et attendre :

• ✅ Backend - Build, Test & Push (10-15 min)
• ✅ Frontend - Build, Test & Push (10-15 min)

4. Vérifier les Images dans le Registry

# 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 :

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
• GitHub Actions ARM64 Support
• Scaleway 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