Effi/docs/WORKFLOW.md

🔄 Workflow de Gestion - Guide Pratique

Objectif

Ce guide t'aide à gérer les modifications de ton infrastructure Effi sans stress, tout en maintenant ton dépôt Gitea à jour.

---

🎯 Le Workflow Recommandé (KISS)

Principe : Toujours deux sources de vérité cohérentes

• Production (effi-server) : Fait tourner les services
• Gitea (dépôt) : Archive et documente la config

┌─────────────────┐         ┌─────────────────┐
│   effi-server   │  ←────→ │     Gitea       │
│   (Production)  │  sync   │   (Archive)     │
└────────┬────────┘         └─────────────────┘
         │
    ┌────┴────┐
    │  Test   │  ← Tu fais tes tests ici
    └────┬────┘
         │
    ┌────┴────┐
    │  Push   │  ← Quand ça marche, tu pousses
    └─────────┘

---

📋 Procédure Standard

Quand tu veux faire une modification :

ÉTAPE 1 : Sauvegarde (30 secondes)

cd ~/effi
docker compose down  # Optionnel, mais plus sûr
cd ..
cp -r Effi Effi-BACKUP-$(date +%Y%m%d)
cd Effi

💡 Pourquoi ? Si tu casses quelque chose, tu peux revenir en arrière en 10 secondes.

ÉTAPE 2 : Modification (5-30 minutes)

Fais tes changements sur effi-server :

# Exemple: Ajouter un service
nano docker-compose.yml

# Tester
docker compose up -d

# Vérifier que ça marche
docker compose ps
docker logs [nom-du-service]

ÉTAPE 3 : Audit (1 minute)

./scripts/audit-production.sh

Note les différences affichées.

ÉTAPE 4 : Synchronisation avec Gitea (2 minutes)

Sur ton PC (pas sur effi-server) :

cd ~/Documents/OpenCode/Projets/Effi

# 1. Récupérer les fichiers depuis effi-server
scp effi@192.168.1.27:~/effi/docker-compose.yml .
scp effi@192.168.1.27:~/effi/.env .env.production  # Si nouvelles variables

# 2. Comparer avec git diff
git diff

# 3. Si c'est bon, commiter
git add .
git commit -m "Ajout service XXX - [date]"

# 4. Pousser
git push

ÉTAPE 5 : Documentation (optionnel, 5 minutes)

Si tu as ajouté un service important, mets à jour la doc :

# Modifier docs/02-configuration/...
nano docs/02-configuration/nouveau-service.md

git add .
git commit -m "Documentation: Ajout service XXX"
git push

---

🆘 En Cas de Problème

Si tu as cassé quelque chose :

# 1. Retour arrière rapide
cd ~/effi
docker compose down
cd ..
rm -rf Effi
cp -r Effi-BACKUP-YYYYMMDD Effi  # Date de ta dernière sauvegarde
cd Effi
docker compose up -d

# 2. C'est réparé !

Si tu as oublié de sauvegarder :

# Récupérer la dernière version stable depuis Gitea
cd ~/effi
docker compose down
cd ..
rm -rf Effi
git clone https://gitea.folzocorp.fr/Folzo/effi.git
cd effi
cp .env.example .env  # Recréer le .env
# Éditer .env avec tes vraies valeurs
docker compose up -d

---

📝 Checklist Avant Modification

Avant chaque changement, vérifie :

• Sauvegarde créée (cp -r Effi Effi-BACKUP-...)
• Services actuels notés (docker compose ps)
• Espace disque suffisant (df -h)
• Connexion à folzo-Corp OK (ping 192.168.1.11)

---

🔄 Fréquence de Synchronisation

Situation	Action
Modification mineure (port, variable)	Sync immédiate
Nouveau service testé	Sync quand stable (après 24-48h)
Correction bug	Sync immédiate avec message explicite
Grosse refonte	Sync par étapes, avec commits intermédiaires
Rien ne marche plus	Restore backup, ne pas sync la config cassée

---

🎓 Exemple Concret

Scénario : Tu veux ajouter un service de monitoring (Uptime Kuma)

# 1. Backup
cd ~/effi/..
cp -r Effi Effi-BACKUP-$(date +%Y%m%d)

# 2. Modification
cd ~/effi
nano docker-compose.yml
# Ajouter le service uptime-kuma...

# 3. Test
docker compose up -d uptime-kuma
docker compose ps  # Vérifier qu'il démarre
curl http://192.168.1.27:3001  # Vérifier l'interface

# 4. Attendre 24h pour être sûr que c'est stable

# 5. Sync avec Gitea (sur ton PC)
scp effi@192.168.1.27:~/effi/docker-compose.yml ~/Documents/OpenCode/Projets/Effi/
cd ~/Documents/OpenCode/Projets/Effi
git add .
git commit -m "Ajout Uptime Kuma pour monitoring (port 3001)"
git push

---

💡 Bonnes Pratiques

1. Commits atomiques

Un commit = une modification logique

# ❌ Mauvais
git commit -m "Modifications diverses"

# ✅ Bon
git commit -m "Ajout service Watchtower (màj auto containers)"
git commit -m "Fix: Correction port CouchDB 5984->5985"

2. Messages descriptifs

git commit -m "Ajout: Service n8n pour automatisation (port 5678)"
git commit -m "Update: Upgrade Qdrant v1.8 -> v1.9"
git commit -m "Fix: Résolution conflit port 8200"

3. Tester avant de synchroniser

Jamais de sync direct sans test !

4. Garder l'historique

# Voir ce qui a changé
git log --oneline -10

# Comparer avec une version ancienne
git diff HEAD~5 docker-compose.yml

---

🔧 Commandes Essentielles (à garder sous la main)

# Sur effi-server
~/effi/scripts/audit-production.sh    # Audit complet
docker compose ps                      # Voir les services
docker compose logs -f [service]       # Voir les logs
docker compose down && docker compose up -d  # Redémarrer propre

# Sur ton PC (synchronisation)
git status                             # Voir les changements
git diff                               # Voir les différences
git add . && git commit -m "message"   # Commiter
git push                               # Pousser sur Gitea
git pull                               # Récupérer depuis Gitea

---

📚 Ressources

• Dépôt Gitea : https://gitea.folzocorp.fr/Folzo/effi
• Audit : ~/effi/scripts/audit-production.sh
• Documentation : ~/Documents/OpenCode/Projets/Effi/docs/

---

Dernière mise à jour : Avril 2026