geo/app/FASTLANE.md

# 🚀 Guide Fastlane - Déploiement automatisé iOS/Android

**Date** : 22/10/2025
**Version actuelle** : 3.4.2 (Build 342)

---

## 📋 Objectif

Automatiser 100% du déploiement iOS et Android depuis Debian, sans écran ni manipulation manuelle sur le Mac mini.

**Avant** : Transfert manuel + Xcode GUI + 30 min de clics
**Après** : 1 commande SSH + 0 supervision

---

## 🎯 Installation

### 1️⃣ Sur le Mac mini (192.168.1.34) - Runtime uniquement

```bash
# Connexion SSH
ssh pierre@192.168.1.34

# Installer fastlane via Homebrew (recommandé)
brew install fastlane

# Vérifier l'installation
fastlane --version

# Activer le partage SSH (si pas déjà fait)
# Préférences Système > Partage > Session à distance
```

### 2️⃣ Sur Debian - Configuration du projet

```bash
# Installer Ruby (si pas déjà fait)
sudo apt install ruby-full build-essential

# Configurer Bundler pour installation locale
cd /home/pierre/dev/geosector/app
echo "source 'https://rubygems.org'" > Gemfile
echo "gem 'fastlane'" >> Gemfile
bundle config set --local path 'vendor/bundle'
bundle install

# Ajouter au .gitignore
echo "vendor/bundle" >> .gitignore

# Vérifier
bundle exec fastlane --version
```

**Important** : Cette installation est à faire **une seule fois par projet Flutter**. Le dossier `fastlane/` est versionné dans Git et transféré avec le code.

---

## ⚙️ Configuration initiale

### 1️⃣ Initialiser fastlane dans le projet (sur Debian)

```bash
cd /home/pierre/dev/geosector/app
bundle exec fastlane init

# Sélectionner :
# iOS : Option 2 (Automate beta distribution to TestFlight)
# Android : Option 2 (Automate deployment to Google Play)
```

### 2️⃣ Configurer les credentials

**Pour iOS (App Store Connect)** :
- Apple ID : votre compte développeur
- Team ID : `6WT84NWCTC`
- App Identifier : `fr.geosector.app`

**Pour Android (Google Play Console)** :
- JSON API Key : télécharger depuis Google Play Console > API Access
- Package name : `fr.geosector.app`
- Keystore : utiliser votre keystore existant

### 3️⃣ Créer le Fastfile

Créer `fastlane/Fastfile` avec les lanes iOS et Android :
- Lane iOS : clean + build + archive + upload TestFlight
- Lane Android : clean + build AAB + upload Play Store

### 4️⃣ Versionner dans Git

```bash
# Commit la configuration fastlane
git add Gemfile Gemfile.lock fastlane/ .gitignore
git commit -m "chore: add fastlane configuration"
git push
```

### 5️⃣ Tester localement

```bash
# Transférer vers Mac mini
rsync -avz --exclude 'build' --exclude '.dart_tool' . pierre@192.168.1.34:/Users/pierre/dev/geosector/app_342/

# Test iOS sur Mac mini
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector/app_342 && fastlane ios release"

# Test Android sur Mac mini
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector/app_342 && fastlane android release"
```

---

## 🚀 Utilisation depuis Debian

### Workflow simple

```bash
# 1. Transférer le code vers le Mac mini (crée app_342/)
cd /home/pierre/dev/geosector/app
rsync -avz --exclude 'build' --exclude '.dart_tool' --exclude 'vendor/bundle' . pierre@192.168.1.34:/Users/pierre/dev/geosector/app_342/

# 2. Lancer le build iOS à distance
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector/app_342 && fastlane ios release"

# 3. Lancer le build Android à distance
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector/app_342 && fastlane android release"

# 4. Archiver la version après succès
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector && zip -r app_342.zip app_342"
```

### Workflow parallèle (iOS + Android simultané)

```bash
# Transfert vers dossier versionné
rsync -avz --exclude 'build' --exclude 'vendor/bundle' . pierre@192.168.1.34:/Users/pierre/dev/geosector/app_342/

# Build iOS et Android en parallèle
ssh pierre@192.168.1.34 "cd /Users/pierre/dev/geosector/app_342 && fastlane ios release & fastlane android release"
```

### Créer un script de déploiement

Créer `deploy-all.sh` dans le projet :
- Étape 1 : rsync vers Mac mini
- Étape 2 : fastlane ios release
- Étape 3 : fastlane android release
- Étape 4 : notification de fin

Usage : `./deploy-all.sh`

---

## ⚡ CI/CD avec Gitea Actions

### Objectif

Automatiser le déploiement à chaque `git push` sur la branche `main` ou `release`.

### Architecture

```
Gitea (gitea.d6soft.fr)
    ↓ git push
Gitea Actions (workflow)
    ↓ SSH
Mac mini (self-hosted runner)
    ↓ fastlane
App Store Connect + Google Play Console
```

### Configuration

**1. Activer Gitea Actions**
- Gitea > Settings > Actions > Enable Actions
- Créer un runner sur le Mac mini

**2. Installer le runner sur le Mac mini**
- Télécharger act_runner depuis Gitea
- Enregistrer le runner avec le token Gitea
- Lancer le runner en service (launchd)

**3. Créer le workflow `.gitea/workflows/deploy.yml`**
- Trigger : `push` sur branche `main` ou tag `v*`
- Steps : checkout + flutter pub get + fastlane ios release + fastlane android release
- Runner : `runs-on: self-hosted`

**4. Sécuriser les secrets**
- Gitea > Settings > Secrets
- Ajouter : APPLE_ID, FASTLANE_PASSWORD, GOOGLE_PLAY_JSON_KEY
- Utiliser `${{ secrets.APPLE_ID }}` dans le workflow

### Résultat

```bash
# Sur Debian
cd /home/pierre/dev/geosector/app
git add .
git commit -m "feat: nouvelle fonctionnalité"
git push origin main

# 🤖 Gitea Actions détecte le push
# 🏗️ Mac mini build automatiquement
# 📤 Upload vers TestFlight + Play Store
# ✅ Notification par email/Slack
```

**Zéro action manuelle, déploiement automatique 24/7.**

---

## 📊 Checklist de migration

### Phase 1 : Installation de base
- [ ] Fastlane installé sur Mac mini
- [ ] Fastfile créé et testé pour iOS
- [ ] Fastfile créé et testé pour Android
- [ ] Credentials configurés (Apple ID, Google Play)
- [ ] Test manuel réussi : `fastlane ios release`
- [ ] Test manuel réussi : `fastlane android release`

### Phase 2 : Déploiement distant
- [ ] SSH sans mot de passe configuré (clé SSH)
- [ ] Script `deploy-all.sh` créé et testé
- [ ] Test de déploiement complet depuis Debian
- [ ] Validation sur TestFlight + Play Store

### Phase 3 : CI/CD (optionnel mais recommandé)
- [ ] Gitea Actions activé sur le dépôt
- [ ] Runner installé sur Mac mini
- [ ] Workflow `.gitea/workflows/deploy.yml` créé
- [ ] Secrets configurés dans Gitea
- [ ] Test de déploiement automatique sur `git push`
- [ ] Notifications configurées (email/Slack)

---

## 🎯 Gains de productivité

| Action | Avant | Après |
|--------|-------|-------|
| Build iOS | 30 min (manuel + VNC) | 1 commande SSH |
| Build Android | 20 min (manuel) | 1 commande SSH |
| Upload stores | 10 min (formulaires) | Automatique |
| Présence requise | 60 min | 0 min |
| Mac mini | Écran + clavier | Headless |
| Déploiement | À la demande | Automatique sur git push |

**Temps gagné par release : ~60 minutes → 0 minute**

---

## 📚 Ressources

- **Fastlane** : https://fastlane.tools
- **Gitea Actions** : https://docs.gitea.com/usage/actions/overview
- **App Store Connect** : https://appstoreconnect.apple.com
- **Google Play Console** : https://play.google.com/console

---

## 🔧 Troubleshooting

**Erreur "Could not find action"**
→ Vérifier que fastlane est dans le PATH du Mac mini

**Erreur de signature iOS**
→ Vérifier que les certificats sont bien installés sur le Mac mini (Xcode > Preferences > Accounts)

**Erreur Google Play API**
→ Vérifier que le JSON key a les bonnes permissions (Admin/Release Manager)

**Runner Gitea ne démarre pas**
→ Vérifier les logs : `journalctl -u gitea-runner -f`

---

✅ **Mac mini headless opérationnel !** 🎉