diff --git a/IA_agents/README.md b/IA_agents/README.md index 44d3ce1..7cab5fe 100644 --- a/IA_agents/README.md +++ b/IA_agents/README.md @@ -1,202 +1,193 @@ -# Documentation IA_agents - LeCoffre Node +# Documentation IA Agents - LeCoffre Node -## Vue d'ensemble +## 📋 Vue d'ensemble -Ce dossier contient toute la documentation nĂ©cessaire pour les agents IA qui dĂ©ploient et gĂšrent l'architecture LeCoffre Node. La documentation est organisĂ©e en plusieurs sections pour faciliter la navigation et l'utilisation. +Ce rĂ©pertoire contient toute la documentation nĂ©cessaire pour les agents IA travaillant sur le projet LeCoffre Node. Cette documentation est **OBLIGATOIRE** et doit ĂȘtre consultĂ©e avant tout dĂ©ploiement. -## Structure de la Documentation +## 📚 Documents Obligatoires -### 📋 ProcĂ©dures de DĂ©ploiement +### **1. Documents de Contexte (À lire AVANT tout dĂ©ploiement)** +- [`context.md`](context.md) - Contexte technique du projet +- [`flux.md`](flux.md) - Architecture des services et flux +- [`deploy.md`](deploy.md) - ProcĂ©dures de dĂ©ploiement dĂ©taillĂ©es -- **[deploy.md](deploy.md)** : ProcĂ©dure gĂ©nĂ©rale de dĂ©ploiement -- **[prompts/prompt-deploy.md](prompts/prompt-deploy.md)** : Prompt de dĂ©ploiement pour les agents IA +### **2. Documents de Processus** +- [`CI_TRIGGER_PROCESS.md`](CI_TRIGGER_PROCESS.md) - Processus de dĂ©clenchement des CI +- [`monitoring-progress.md`](monitoring-progress.md) - SystĂšme de monitoring et progression +- [`quick-reference-monitoring.md`](quick-reference-monitoring.md) - Guide de rĂ©fĂ©rence rapide -### 🔧 Monitoring et Progression +### **3. Documents d'Architecture (NOUVEAU)** +- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de dĂ©ploiement par phases +- [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions -- **[monitoring-progress.md](monitoring-progress.md)** : Documentation complĂšte du systĂšme de monitoring -- **[quick-reference-monitoring.md](quick-reference-monitoring.md)** : Guide de rĂ©fĂ©rence rapide -- **[troubleshooting-monitoring.md](troubleshooting-monitoring.md)** : Guide de dĂ©pannage +### **4. Documents de DĂ©ploiement** +- [`prompts/prompt-deploy.md`](prompts/prompt-deploy.md) - Prompt de dĂ©ploiement complet -### 📚 Documentation Technique - -- **[context.md](context.md)** : Contexte technique du projet -- **[flux.md](flux.md)** : Architecture des services -- **[CI_TRIGGER_PROCESS.md](CI_TRIGGER_PROCESS.md)** : Processus CI/CD - -## Utilisation Rapide - -### Pour un DĂ©ploiement Complet - -1. **Consulter le prompt de dĂ©ploiement** : `prompts/prompt-deploy.md` -2. **Suivre la procĂ©dure gĂ©nĂ©rale** : `deploy.md` -3. **Utiliser les outils de monitoring** : `monitoring-progress.md` - -### Pour le Monitoring et la Surveillance - -1. **Guide de rĂ©fĂ©rence rapide** : `quick-reference-monitoring.md` -2. **Documentation complĂšte** : `monitoring-progress.md` -3. **DĂ©pannage** : `troubleshooting-monitoring.md` - -## Scripts de Monitoring Disponibles - -### Scripts Principaux - -- `./scripts/monitor-progress.sh` : Aperçu complet de tous les services -- `./scripts/watch-progress.sh` : Surveillance en temps rĂ©el -- `./scripts/logs-with-progress.sh` : Logs avec informations de progression -- `./scripts/start-with-progress.sh` : DĂ©marrage ordonnĂ© avec suivi - -### Utilisation +## 🚹 RÈGLES CRITIQUES +### **đŸš« INTERDICTIONS ABSOLUES** ```bash -# Surveillance gĂ©nĂ©rale -./scripts/monitor-progress.sh - -# Surveillance en temps rĂ©el -./scripts/watch-progress.sh - -# Logs avec progression -./scripts/logs-with-progress.sh bitcoin -p -f - -# DĂ©marrage avec suivi -./scripts/start-with-progress.sh -``` - -## Services et Ports - -| Service | Port | Description | -|---------|------|-------------| -| Tor | 9050 | Proxy SOCKS | -| Bitcoin | 8332 | NƓud Bitcoin Signet | -| BlindBit | 8000 | Oracle BlindBit | -| SDK Storage | 8081 | Stockage SDK | -| SDK Relay | 8090-8091 | Relay WebSocket | -| SDK Signer | 3001 | Service de signature | -| LeCoffre Backend | 8080 | API Backend | -| LeCoffre Frontend | 3000 | Interface utilisateur | -| IHM Client | 3003 | Client IHM | -| Grafana | 3005 | Dashboard | -| Loki | 3100 | AgrĂ©gation de logs | -| Promtail | 9080 | Collection de logs | -| Status API | 3006 | API de statut | - -## URLs de Test - -### Services Locaux -- Bitcoin RPC : `http://localhost:8332` -- BlindBit : `http://localhost:8000` -- SDK Storage : `http://localhost:8081` -- SDK Relay : `http://localhost:8091` -- SDK Signer : `http://localhost:3001` -- IHM Client : `http://localhost:3003` -- Grafana : `http://localhost:3005` -- Loki : `http://localhost:3100` -- Status API : `http://localhost:3006` - -### Services Externes -- Page de statut : `https://dev4.4nkweb.com/status/` -- API de statut : `https://dev4.4nkweb.com/status/api` -- Grafana : `https://dev4.4nkweb.com/grafana/` -- IHM Client : `https://dev4.4nkweb.com/` -- Application LeCoffre : `https://dev4.4nkweb.com/lecoffre/` -- WebSocket Relay : `https://dev4.4nkweb.com/ws/` - -## Ordre de DĂ©marrage Critique - -1. **Tor** → 2. **Bitcoin** → 3. **BlindBit** → 4. **SDK Storage** → 5. **SDK Relay** → 6. **SDK Signer** → 7. **IHM Client** → 8. **LeCoffre Backend** → 9. **LeCoffre Frontend** → 10. **Services de monitoring** - -## Variables d'Environnement - -### Fichier .env.master -- `SDK_RELAY_*` : Configuration du service relay -- `SIGNER_*` : Configuration du service signer -- `VITE_*` : Configuration des applications frontend -- `IDNOT_*` : Configuration des APIs notaires -- `STRIPE_*` : Configuration des paiements -- `MAILCHIMP_*` : Configuration des emails -- `OVH_*` : Configuration des SMS - -### Utilisation -```bash -# Toujours utiliser le fichier .env.master +# ❌ JAMAIS utiliser ces commandes docker compose --env-file .env.master up -d +docker compose up -d +docker compose start ``` -## Codes de Statut - -### Symboles -- `✓` : Service prĂȘt et fonctionnel -- `⚠` : Service en cours de traitement -- `⏳` : Service en cours de dĂ©marrage -- `✗` : Service arrĂȘtĂ© ou en erreur -- `â„č` : Service en cours d'exĂ©cution - -### États de Healthcheck -- `healthy` : Service prĂȘt -- `unhealthy` : Service en cours de traitement -- `starting` : Service en cours de dĂ©marrage -- `no-healthcheck` : Pas de healthcheck dĂ©fini - -## Progression des Services - -### Bitcoin IBD -- **Message** : `Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%` -- **Condition de santĂ©** : `blocks == headers && blocks > 0` -- **Temps estimĂ©** : Variable selon la vitesse de tĂ©lĂ©chargement - -### BlindBit Oracle -- **États** : Starting → Scanning → Ready -- **Codes HTTP** : 000 (non prĂȘt), 404 (scan), 200 (prĂȘt) -- **Message de santĂ©** : `BlindBit ready: Oracle service responding` - -### SDK Relay -- **DĂ©pendance** : Bitcoin synchronisĂ© -- **États** : IBD → WebSocket Ready -- **Message de santĂ©** : `SDK Relay ready: WebSocket server responding` - -## DĂ©pannage Rapide - -### Commandes Essentielles +### **✅ OBLIGATIONS ABSOLUES** ```bash -# Statut de tous les services -docker compose --env-file .env.master ps - -# Logs d'un service -docker logs --tail 50 - -# Healthcheck d'un service -docker inspect --format='{{.State.Health.Status}}' - -# Surveillance gĂ©nĂ©rale -./scripts/monitor-progress.sh +# ✅ Utiliser UNIQUEMENT ces scripts +./scripts/start-with-progress.sh # Services applicatifs +./scripts/start-monitoring.sh # Services de monitoring +./scripts/monitor-progress.sh # Surveillance ``` -### ProblĂšmes Courants -1. **Service en Ă©tat "unhealthy"** : VĂ©rifier les logs avec `docker logs ` -2. **Progression bloquĂ©e** : VĂ©rifier la connectivitĂ© rĂ©seau et les dĂ©pendances -3. **Services en attente** : VĂ©rifier que les services de dĂ©pendance sont "healthy" +## đŸ—ïž Architecture de DĂ©ploiement -## Bonnes Pratiques +### **Principe Fondamental** +Les services sont organisĂ©s en **5 phases** pour optimiser le dĂ©marrage et Ă©viter les dĂ©pendances inutiles : -1. **Utiliser les scripts** plutĂŽt que les commandes Docker directes -2. **Surveiller la progression** pendant les dĂ©ploiements -3. **VĂ©rifier les dĂ©pendances** avant de dĂ©marrer les services -4. **Consulter les logs** en cas de problĂšme -5. **Utiliser les variables centralisĂ©es** du fichier `.env.master` -6. **Tester l'accĂšs externe** aprĂšs le dĂ©ploiement -7. **VĂ©rifier la santĂ© des services** rĂ©guliĂšrement +1. **Services applicatifs** : Fonctionnent indĂ©pendamment du monitoring +2. **Services de monitoring** : Observent sans impacter les applications +3. **DĂ©pendances** : Seules les dĂ©pendances mĂ©tier sont respectĂ©es -## Mise Ă  Jour de la Documentation +### **Ordre par Phases** +``` +Phase 1: Services de Base (ParallĂšle) +├── tor, sdk_storage, sdk_signer, status-api -Cette documentation est mise Ă  jour rĂ©guliĂšrement pour reflĂ©ter les amĂ©liorations et les nouvelles fonctionnalitĂ©s. Les agents IA doivent consulter cette documentation avant chaque dĂ©ploiement pour s'assurer d'utiliser les derniĂšres procĂ©dures et outils. +Phase 2: Services Blockchain (SĂ©quentiel) +├── bitcoin → blindbit → sdk_relay -## Support +Phase 3: Services Applicatifs (SĂ©quentiel) +├── lecoffre-back → lecoffre-front, ihm_client -En cas de problĂšme ou de question, consulter : -1. **Guide de dĂ©pannage** : `troubleshooting-monitoring.md` -2. **Guide de rĂ©fĂ©rence rapide** : `quick-reference-monitoring.md` -3. **Documentation complĂšte** : `monitoring-progress.md` +Phase 4: Services de Monitoring (SĂ©quentiel, IndĂ©pendant) +├── loki → promtail → grafana + +Phase 5: Services Utilitaires +└── watchtower +``` + +## 🔧 Scripts de DĂ©ploiement + +### **Scripts OBLIGATOIRES** +| Script | Usage | Phases | +|--------|-------|--------| +| `start-with-progress.sh` | DĂ©marrage complet avec phases | 1, 2, 3, 5 | +| `start-monitoring.sh` | DĂ©marrage monitoring indĂ©pendant | 4 | +| `monitor-progress.sh` | Aperçu des services | Toutes | +| `watch-progress.sh` | Surveillance temps rĂ©el | Toutes | +| `logs-with-progress.sh` | Logs avec progression | Toutes | + +### **Scripts INTERDITS** +- `docker compose up -d` (toute variante) +- Commandes Docker Compose directes + +## 📊 Avantages de cette Architecture + +### **1. Robustesse** +- **Isolation** : Pannes de monitoring n'impactent pas les applications +- **RĂ©cupĂ©ration** : RedĂ©marrage sĂ©lectif possible +- **StabilitĂ©** : Services applicatifs fonctionnent mĂȘme sans monitoring + +### **2. Performance** +- **DĂ©marrage optimisĂ©** : Services parallĂšles quand possible +- **DĂ©pendances respectĂ©es** : ChaĂźne de dĂ©marrage optimale +- **Monitoring indĂ©pendant** : Ne ralentit pas les applications + +### **3. Maintenance** +- **RedĂ©marrage sĂ©lectif** : Monitoring ou applications sĂ©parĂ©ment +- **Diagnostic facilitĂ©** : Scripts spĂ©cialisĂ©s par fonction +- **Surveillance continue** : Progression visible en temps rĂ©el + +## 🎯 Workflow de DĂ©ploiement + +### **Étape 1: PrĂ©paration** +1. Lire tous les documents de contexte +2. VĂ©rifier la branche `ext` +3. Mettre Ă  jour les dĂ©pendances +4. Synchroniser les configurations + +### **Étape 2: DĂ©ploiement** +1. **Services applicatifs** : `./scripts/start-with-progress.sh` +2. **Services de monitoring** : `./scripts/start-monitoring.sh` +3. **Surveillance** : `./scripts/monitor-progress.sh` + +### **Étape 3: Validation** +1. Tests des URLs publiques +2. VĂ©rification des dashboards Grafana +3. Validation des flux fonctionnels +4. Documentation du retour d'expĂ©rience + +## 📝 Documents de Retour d'ExpĂ©rience + +### **Format des REX** +- **Date** : Format ISO (YYYY-MM-DD) +- **Agent** : Nom de l'agent IA +- **Objectif** : But du dĂ©ploiement +- **Statut** : SuccĂšs/Échec/Partiel +- **ProblĂšmes** : DifficultĂ©s rencontrĂ©es +- **Solutions** : Actions correctives +- **Leçons** : Apprentissages + +### **Exemple de REX** +- [`REX_Deploiement_2025-09-21.md`](REX_Deploiement_2025-09-21.md) + +## 🔍 Points d'Attention + +### **DĂ©pendances Critiques** +1. **bitcoin** → **blindbit** → **sdk_relay** : ChaĂźne blockchain +2. **sdk_relay** → **lecoffre-back** → **lecoffre-front** : ChaĂźne applicative +3. **loki** → **promtail** → **grafana** : ChaĂźne monitoring + +### **Healthchecks** +- Tous les services ont des healthchecks informatifs +- Les dĂ©pendances attendent que les services soient "healthy" +- Timeouts adaptĂ©s selon la criticitĂ© + +### **Variables d'Environnement** +- Configuration centralisĂ©e dans `.env.master` +- Tous les scripts utilisent `--env-file .env.master` +- Pas de fichiers `.env` dispersĂ©s + +## 🚹 Signaux d'Alerte + +### **Si vous voyez ces commandes, c'est une ERREUR :** +```bash +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +``` + +### **Si vous voyez ces comportements, c'est une ERREUR :** +- Services de monitoring qui bloquent les applications +- DĂ©marrage de tous les services en parallĂšle +- Absence de suivi de progression +- Logs sans informations de progression + +### **Si vous voyez ces rĂ©sultats, c'est CORRECT :** +- Phases de dĂ©marrage visibles +- Progression Bitcoin IBD affichĂ©e +- Services de monitoring indĂ©pendants +- Surveillance continue opĂ©rationnelle + +## 📞 Support + +### **En cas de problĂšme :** +1. Consulter les documents de contexte +2. VĂ©rifier les bonnes pratiques +3. Utiliser les scripts de diagnostic +4. Documenter le problĂšme et la solution + +### **Pour amĂ©liorer :** +1. Proposer des amĂ©liorations dans les REX +2. Mettre Ă  jour la documentation +3. Tester les nouvelles approches +4. Valider avec l'Ă©quipe --- -**Note** : Cette documentation est basĂ©e sur les meilleures pratiques du projet LeCoffre Node et est mise Ă  jour en continu pour reflĂ©ter les amĂ©liorations et les nouvelles fonctionnalitĂ©s. +**Document créé le 2025-09-21** +**Version** : 1.0 +**Usage** : Obligatoire pour tous les agents IA +**Mise Ă  jour** : À chaque dĂ©ploiement \ No newline at end of file diff --git a/IA_agents/best-practices-deployment.md b/IA_agents/best-practices-deployment.md new file mode 100644 index 0000000..ee43d05 --- /dev/null +++ b/IA_agents/best-practices-deployment.md @@ -0,0 +1,247 @@ +# Bonnes Pratiques de DĂ©ploiement LeCoffre Node + +## đŸš« INTERDICTIONS ABSOLUES + +### **Commandes Docker Compose Interdites** +```bash +# ❌ JAMAIS utiliser ces commandes +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +docker compose restart +``` + +### **Pourquoi ces commandes sont interdites ?** +1. **Pas de phases** : DĂ©marrent tous les services en parallĂšle +2. **DĂ©pendances ignorĂ©es** : Ne respectent pas l'ordre critique +3. **Monitoring bloquĂ©** : Services de monitoring dĂ©pendent des applications +4. **Diagnostic difficile** : Pas de suivi de progression +5. **Échecs cachĂ©s** : Erreurs non visibles + +## ✅ OBLIGATIONS ABSOLUES + +### **Scripts OBLIGATOIRES** +```bash +# ✅ DĂ©marrage complet avec phases +./scripts/start-with-progress.sh + +# ✅ DĂ©marrage monitoring indĂ©pendant +./scripts/start-monitoring.sh + +# ✅ Surveillance +./scripts/monitor-progress.sh +./scripts/watch-progress.sh +./scripts/logs-with-progress.sh +``` + +### **Pourquoi ces scripts sont obligatoires ?** +1. **Phases respectĂ©es** : Ordre de dĂ©marrage optimisĂ© +2. **DĂ©pendances gĂ©rĂ©es** : Attente des services critiques +3. **Monitoring indĂ©pendant** : Ne bloque pas les applications +4. **Progression visible** : Suivi en temps rĂ©el +5. **Diagnostic facilitĂ©** : Logs et statuts dĂ©taillĂ©s + +## đŸ—ïž Architecture de DĂ©ploiement + +### **Principe Fondamental** +``` +Services Applicatifs ←→ Services de Monitoring + ↓ ↓ + Fonctionnent Observent sans + indĂ©pendamment impacter +``` + +### **Ordre par Phases** + +#### **Phase 1: Services de Base (ParallĂšle)** +```bash +# Ces services peuvent dĂ©marrer en parallĂšle +tor + sdk_storage + sdk_signer + status-api +``` + +#### **Phase 2: Services Blockchain (SĂ©quentiel)** +```bash +# ChaĂźne de dĂ©pendances blockchain +tor → bitcoin → blindbit → sdk_relay +``` + +#### **Phase 3: Services Applicatifs (SĂ©quentiel)** +```bash +# ChaĂźne de dĂ©pendances applicatives +sdk_relay → lecoffre-back → lecoffre-front +sdk_relay + sdk_storage → ihm_client +``` + +#### **Phase 4: Services de Monitoring (SĂ©quentiel, IndĂ©pendant)** +```bash +# ChaĂźne de dĂ©pendances monitoring +loki → promtail → grafana +``` + +#### **Phase 5: Services Utilitaires** +```bash +# Services de maintenance +watchtower +``` + +## 🔧 Utilisation des Scripts + +### **DĂ©ploiement Complet** +```bash +# 1. DĂ©marrage services applicatifs +./scripts/start-with-progress.sh + +# 2. DĂ©marrage monitoring indĂ©pendant +./scripts/start-monitoring.sh + +# 3. Surveillance +./scripts/monitor-progress.sh +``` + +### **RedĂ©marrage Monitoring Seul** +```bash +# RedĂ©marrage monitoring sans impacter les applications +./scripts/start-monitoring.sh +``` + +### **Diagnostic et Surveillance** +```bash +# Aperçu gĂ©nĂ©ral +./scripts/monitor-progress.sh + +# Surveillance temps rĂ©el +./scripts/watch-progress.sh + +# Logs avec progression +./scripts/logs-with-progress.sh bitcoin -p -f +``` + +## 📊 Avantages de cette Architecture + +### **1. Robustesse** +- **Isolation** : Pannes de monitoring n'impactent pas les applications +- **RĂ©cupĂ©ration** : RedĂ©marrage sĂ©lectif possible +- **StabilitĂ©** : Services applicatifs fonctionnent mĂȘme sans monitoring + +### **2. Performance** +- **DĂ©marrage optimisĂ©** : Services parallĂšles quand possible +- **DĂ©pendances respectĂ©es** : ChaĂźne de dĂ©marrage optimale +- **Monitoring indĂ©pendant** : Ne ralentit pas les applications + +### **3. Maintenance** +- **RedĂ©marrage sĂ©lectif** : Monitoring ou applications sĂ©parĂ©ment +- **Diagnostic facilitĂ©** : Scripts spĂ©cialisĂ©s par fonction +- **Surveillance continue** : Progression visible en temps rĂ©el + +### **4. DĂ©veloppement** +- **Tests isolĂ©s** : Applications testables sans monitoring +- **DĂ©bogage facilitĂ©** : Logs et progression dĂ©taillĂ©s +- **DĂ©ploiement progressif** : Phases de validation + +## 🎯 RĂšgles d'Or pour les Agents IA + +### **RĂšgle 1: Toujours utiliser les scripts spĂ©cialisĂ©s** +```bash +# ✅ CORRECT +./scripts/start-with-progress.sh +./scripts/start-monitoring.sh + +# ❌ INCORRECT +docker compose up -d +``` + +### **RĂšgle 2: Respecter l'ordre par phases** +```bash +# ✅ CORRECT : Phases sĂ©parĂ©es +Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 + +# ❌ INCORRECT : Tout en parallĂšle +tous_les_services_en_mĂȘme_temps +``` + +### **RĂšgle 3: Monitoring indĂ©pendant** +```bash +# ✅ CORRECT : Monitoring sĂ©parĂ© +./scripts/start-with-progress.sh # Applications +./scripts/start-monitoring.sh # Monitoring + +# ❌ INCORRECT : Monitoring dĂ©pendant +applications_dĂ©pendent_de_monitoring +``` + +### **RĂšgle 4: Surveillance continue** +```bash +# ✅ CORRECT : Suivi de progression +./scripts/monitor-progress.sh +./scripts/watch-progress.sh + +# ❌ INCORRECT : DĂ©marrage sans suivi +docker_compose_up_et_oublier +``` + +### **RĂšgle 5: Diagnostic facilitĂ©** +```bash +# ✅ CORRECT : Logs avec progression +./scripts/logs-with-progress.sh bitcoin -p -f + +# ❌ INCORRECT : Logs bruts +docker logs bitcoin +``` + +## 🔍 Points d'Attention + +### **DĂ©pendances Critiques** +1. **bitcoin** → **blindbit** → **sdk_relay** : ChaĂźne blockchain +2. **sdk_relay** → **lecoffre-back** → **lecoffre-front** : ChaĂźne applicative +3. **loki** → **promtail** → **grafana** : ChaĂźne monitoring + +### **Healthchecks** +- Tous les services ont des healthchecks informatifs +- Les dĂ©pendances attendent que les services soient "healthy" +- Timeouts adaptĂ©s selon la criticitĂ© + +### **Variables d'Environnement** +- Configuration centralisĂ©e dans `.env.master` +- Tous les scripts utilisent `--env-file .env.master` +- Pas de fichiers `.env` dispersĂ©s + +## 📝 Validation et Tests + +### **Tests de DĂ©ploiement** +1. **Services applicatifs** : URLs publiques accessibles +2. **Services de monitoring** : Dashboards Grafana alimentĂ©s +3. **DĂ©pendances** : ChaĂźne de dĂ©marrage respectĂ©e +4. **Performance** : Temps de dĂ©marrage optimisĂ© + +### **Tests de Maintenance** +1. **RedĂ©marrage monitoring** : Applications non impactĂ©es +2. **RedĂ©marrage applications** : Monitoring non impactĂ© +3. **Pannes sĂ©lectives** : RĂ©cupĂ©ration isolĂ©e +4. **Surveillance** : DĂ©tection et diagnostic facilitĂ©s + +## 🚹 Signaux d'Alerte + +### **Si vous voyez ces commandes, c'est une ERREUR :** +```bash +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +``` + +### **Si vous voyez ces comportements, c'est une ERREUR :** +- Services de monitoring qui bloquent les applications +- DĂ©marrage de tous les services en parallĂšle +- Absence de suivi de progression +- Logs sans informations de progression + +### **Si vous voyez ces rĂ©sultats, c'est CORRECT :** +- Phases de dĂ©marrage visibles +- Progression Bitcoin IBD affichĂ©e +- Services de monitoring indĂ©pendants +- Surveillance continue opĂ©rationnelle + +--- + +**Document créé le 2025-09-21** +**Version** : 1.0 +**Usage** : Obligatoire pour tous les agents IA diff --git a/IA_agents/deployment-architecture.md b/IA_agents/deployment-architecture.md new file mode 100644 index 0000000..38d0923 --- /dev/null +++ b/IA_agents/deployment-architecture.md @@ -0,0 +1,181 @@ +# Architecture de DĂ©ploiement LeCoffre Node + +## 📋 Vue d'ensemble + +Ce document dĂ©finit l'architecture de dĂ©ploiement optimale pour LeCoffre Node, basĂ©e sur le principe de sĂ©paration des responsabilitĂ©s et l'ordre de dĂ©marrage par phases. + +## đŸ—ïž Architecture par Phases + +### **Principe Fondamental** +Les services sont organisĂ©s en phases pour optimiser le dĂ©marrage et Ă©viter les dĂ©pendances inutiles : + +1. **Services applicatifs** : Fonctionnent indĂ©pendamment du monitoring +2. **Services de monitoring** : Observent sans impacter les applications +3. **DĂ©pendances** : Seules les dĂ©pendances mĂ©tier sont respectĂ©es + +### **Phase 1: Services de Base (ParallĂšle)** +Ces services peuvent dĂ©marrer en parallĂšle car ils sont indĂ©pendants : + +| Service | Port | DĂ©pendance | Script | +|---------|------|------------|--------| +| **tor** | 9050 | Aucune | `start-with-progress.sh` | +| **sdk_storage** | 8081 | Aucune | `start-with-progress.sh` | +| **sdk_signer** | 3001 | Aucune | `start-with-progress.sh` | +| **status-api** | 3006 | Aucune | `start-with-progress.sh` | + +### **Phase 2: Services Blockchain (SĂ©quentiel)** +Ces services suivent la chaĂźne blockchain : + +| Service | Port | DĂ©pendance | Script | +|---------|------|------------|--------| +| **bitcoin** | 8332 | tor (healthy) | `start-with-progress.sh` | +| **blindbit** | 8000 | bitcoin (healthy) | `start-with-progress.sh` | +| **sdk_relay** | 8090-8091 | blindbit (healthy) | `start-with-progress.sh` | + +### **Phase 3: Services Applicatifs (SĂ©quentiel)** +Ces services suivent la chaĂźne applicative : + +| Service | Port | DĂ©pendance | Script | +|---------|------|------------|--------| +| **lecoffre-back** | 8080 | sdk_relay (healthy) | `start-with-progress.sh` | +| **lecoffre-front** | 3004 | lecoffre-back (healthy) | `start-with-progress.sh` | +| **ihm_client** | 3003 | sdk_relay + sdk_storage | `start-with-progress.sh` | + +### **Phase 4: Services de Monitoring (SĂ©quentiel, IndĂ©pendant)** +Ces services sont indĂ©pendants des applications : + +| Service | Port | DĂ©pendance | Script | +|---------|------|------------|--------| +| **loki** | 3100 | Aucune | `start-monitoring.sh` | +| **promtail** | 9080 | loki (healthy) | `start-monitoring.sh` | +| **grafana** | 3005 | loki + promtail (healthy) | `start-monitoring.sh` | + +### **Phase 5: Services Utilitaires** +Services de maintenance et surveillance : + +| Service | Port | DĂ©pendance | Script | +|---------|------|------------|--------| +| **watchtower** | 8080 | Aucune | `start-with-progress.sh` | + +## 🔧 Scripts de DĂ©ploiement + +### **Scripts OBLIGATOIRES** + +#### `./scripts/start-with-progress.sh` +**Usage** : DĂ©marrage complet avec phases +**Fonction** : DĂ©marre les services applicatifs dans l'ordre correct +**Phases** : 1, 2, 3, 5 + +#### `./scripts/start-monitoring.sh` +**Usage** : DĂ©marrage monitoring indĂ©pendant +**Fonction** : DĂ©marre les services de monitoring dans l'ordre correct +**Phases** : 4 uniquement + +#### `./scripts/monitor-progress.sh` +**Usage** : Aperçu des services +**Fonction** : Affiche le statut de tous les services + +#### `./scripts/watch-progress.sh` +**Usage** : Surveillance temps rĂ©el +**Fonction** : Surveillance continue avec rafraĂźchissement + +#### `./scripts/logs-with-progress.sh` +**Usage** : Logs avec progression +**Fonction** : Affiche les logs avec informations de progression + +### **Scripts INTERDITS** +```bash +# ❌ JAMAIS utiliser directement +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +``` + +## 📊 Flux de DĂ©ploiement + +### **DĂ©ploiement Complet** +```bash +# 1. DĂ©marrage services applicatifs +./scripts/start-with-progress.sh + +# 2. DĂ©marrage monitoring indĂ©pendant +./scripts/start-monitoring.sh + +# 3. Surveillance +./scripts/monitor-progress.sh +``` + +### **DĂ©ploiement Monitoring Seul** +```bash +# RedĂ©marrage monitoring sans impacter les applications +./scripts/start-monitoring.sh +``` + +### **Surveillance Continue** +```bash +# Surveillance temps rĂ©el +./scripts/watch-progress.sh + +# Logs avec progression +./scripts/logs-with-progress.sh bitcoin -p -f +``` + +## 🎯 Avantages de cette Architecture + +### **1. SĂ©paration des ResponsabilitĂ©s** +- **Services applicatifs** : Fonctionnent mĂȘme sans monitoring +- **Services de monitoring** : Peuvent ĂȘtre redĂ©marrĂ©s sans impact +- **DĂ©pendances claires** : Seules les dĂ©pendances mĂ©tier + +### **2. Optimisation du DĂ©marrage** +- **Phase 1** : Services indĂ©pendants en parallĂšle +- **Phases 2-3** : ChaĂźne de dĂ©pendances respectĂ©e +- **Phase 4** : Monitoring indĂ©pendant +- **Phase 5** : Services utilitaires + +### **3. Maintenance FacilitĂ©e** +- **RedĂ©marrage monitoring** : Sans impact sur les applications +- **RedĂ©marrage applications** : Sans impact sur le monitoring +- **Diagnostic** : Scripts spĂ©cialisĂ©s par fonction + +### **4. Robustesse** +- **Isolation** : Pannes de monitoring n'impactent pas les applications +- **RĂ©cupĂ©ration** : RedĂ©marrage sĂ©lectif possible +- **Monitoring** : Surveillance continue et dĂ©taillĂ©e + +## 🔍 Points d'Attention + +### **DĂ©pendances Critiques** +1. **bitcoin** → **blindbit** → **sdk_relay** : ChaĂźne blockchain +2. **sdk_relay** → **lecoffre-back** → **lecoffre-front** : ChaĂźne applicative +3. **loki** → **promtail** → **grafana** : ChaĂźne monitoring + +### **Healthchecks** +- Tous les services ont des healthchecks informatifs +- Les dĂ©pendances attendent que les services soient "healthy" +- Timeouts adaptĂ©s selon la criticitĂ© + +### **Variables d'Environnement** +- Configuration centralisĂ©e dans `.env.master` +- Tous les scripts utilisent `--env-file .env.master` +- Pas de fichiers `.env` dispersĂ©s + +## 📝 Validation + +### **Tests de DĂ©ploiement** +1. **Services applicatifs** : URLs publiques accessibles +2. **Services de monitoring** : Dashboards Grafana alimentĂ©s +3. **DĂ©pendances** : ChaĂźne de dĂ©marrage respectĂ©e +4. **Performance** : Temps de dĂ©marrage optimisĂ© + +### **Tests de Maintenance** +1. **RedĂ©marrage monitoring** : Applications non impactĂ©es +2. **RedĂ©marrage applications** : Monitoring non impactĂ© +3. **Pannes sĂ©lectives** : RĂ©cupĂ©ration isolĂ©e +4. **Surveillance** : DĂ©tection et diagnostic facilitĂ©s + +--- + +**Document créé le 2025-09-21** +**Version** : 1.0 +**Architecture** : LeCoffre Node Deployment diff --git a/IA_agents/monitoring-progress.md b/IA_agents/monitoring-progress.md index b689d75..fab2f20 100644 --- a/IA_agents/monitoring-progress.md +++ b/IA_agents/monitoring-progress.md @@ -260,8 +260,14 @@ docker inspect --format='{{.State.Health.Status}}' bitcoin-signet # ArrĂȘter tous les services docker compose --env-file .env.master down -# DĂ©marrer avec suivi de progression +# ✅ DĂ©marrage services applicatifs avec phases ./scripts/start-with-progress.sh + +# ✅ DĂ©marrage monitoring indĂ©pendant +./scripts/start-monitoring.sh + +# ❌ JAMAIS utiliser directement +# docker compose --env-file .env.master up -d ``` ### VĂ©rification Rapide diff --git a/IA_agents/prompts/prompt-deploy.md b/IA_agents/prompts/prompt-deploy.md index f455022..07d2943 100644 --- a/IA_agents/prompts/prompt-deploy.md +++ b/IA_agents/prompts/prompt-deploy.md @@ -66,13 +66,23 @@ A mettre dans ta TODO (vĂ©rifie que tout est fait Ă  la fin): - [ ] Corriger Ă  nouveau si nĂ©cessaire (jusqu'Ă  l'absence totale d'erreurs) ### Phase 7: DĂ©ploiement des services -- [ ] Lancer tous les services de `lecoffre_node/docker-compose.yml` via les scripts -- [ ] Utiliser la configuration centralisĂ©e: `docker compose --env-file .env.master up` -- [ ] **Utiliser le systĂšme de monitoring et progression** : - - [ ] Utiliser `./scripts/start-with-progress.sh` pour le dĂ©marrage ordonnĂ© avec suivi - - [ ] Utiliser `./scripts/monitor-progress.sh` pour l'aperçu des services - - [ ] Utiliser `./scripts/watch-progress.sh` pour la surveillance en temps rĂ©el - - [ ] Utiliser `./scripts/logs-with-progress.sh` pour les logs avec progression +- [ ] **IMPORTANT** : Utiliser UNIQUEMENT les scripts spĂ©cialisĂ©s, JAMAIS docker compose directement +- [ ] **Ordre de dĂ©ploiement OBLIGATOIRE** : + - [ ] **Phase 1** : Services de base (parallĂšle) avec `./scripts/start-with-progress.sh` + - [ ] **Phase 2** : Services blockchain (sĂ©quentiel) avec `./scripts/start-with-progress.sh` + - [ ] **Phase 3** : Services applicatifs (sĂ©quentiel) avec `./scripts/start-with-progress.sh` + - [ ] **Phase 4** : Services de monitoring (indĂ©pendant) avec `./scripts/start-monitoring.sh` + - [ ] **Phase 5** : Services utilitaires avec `./scripts/start-with-progress.sh` +- [ ] **Scripts OBLIGATOIRES Ă  utiliser** : + - [ ] `./scripts/start-with-progress.sh` : DĂ©marrage complet avec phases + - [ ] `./scripts/start-monitoring.sh` : DĂ©marrage monitoring indĂ©pendant + - [ ] `./scripts/monitor-progress.sh` : Aperçu des services + - [ ] `./scripts/watch-progress.sh` : Surveillance temps rĂ©el + - [ ] `./scripts/logs-with-progress.sh` : Logs avec progression +- [ ] **Architecture de dĂ©ploiement** : + - [ ] **Services applicatifs** : DĂ©marrent indĂ©pendamment des services de monitoring + - [ ] **Services de monitoring** : Loki → Promtail → Grafana (sĂ©quentiel) + - [ ] **DĂ©pendances** : Seules les dĂ©pendances mĂ©tier sont respectĂ©es - [ ] **Surveiller la progression des services critiques** : - [ ] **Bitcoin IBD** : Suivre la progression des blocs tĂ©lĂ©chargĂ©s - [ ] **BlindBit** : Surveiller l'Ă©tat du scan des blocs @@ -128,13 +138,23 @@ Variables disponibles : 4. **Services HTTP(S)** : Test spĂ©cifique des services HTTP(S) ## Commandes essentielles -```bash -# DĂ©marrage avec variables centralisĂ©es -docker compose --env-file .env.master up -d -# DĂ©marrage avec suivi de progression +### đŸš« INTERDIT - Ne jamais utiliser ces commandes +```bash +# ❌ JAMAIS utiliser directement +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +``` + +### ✅ OBLIGATOIRE - Utiliser uniquement ces scripts +```bash +# DĂ©marrage complet avec phases (OBLIGATOIRE) ./scripts/start-with-progress.sh +# DĂ©marrage monitoring indĂ©pendant (OBLIGATOIRE) +./scripts/start-monitoring.sh + # Surveillance gĂ©nĂ©rale ./scripts/monitor-progress.sh @@ -167,19 +187,38 @@ docker compose --env-file .env.master up -d - **Attends la synchronisation Bitcoin** avant de dĂ©marrer SDK Relay - **VĂ©rifie les dĂ©pendances** avant de dĂ©marrer les services LeCoffre -## Ordre de dĂ©marrage des services (CRITIQUE) +## Architecture de dĂ©ploiement (CRITIQUE) + +### đŸ—ïž Ordre de dĂ©marrage par phases +**Phase 1: Services de base (parallĂšle)** 1. tor -2. bitcoin -3. blindbit -4. sdk_storage -5. sdk_relay -6. sdk_signer -7. ihm_client -8. lecoffre-back -9. lecoffre-front -10. loki -11. promtail -12. grafana +2. sdk_storage +3. sdk_signer +4. status-api + +**Phase 2: Services blockchain (sĂ©quentiel)** +5. bitcoin (attend tor) +6. blindbit (attend bitcoin) +7. sdk_relay (attend blindbit) + +**Phase 3: Services applicatifs (sĂ©quentiel)** +8. lecoffre-back (attend sdk_relay) +9. lecoffre-front (attend lecoffre-back) +10. ihm_client (attend sdk_relay + sdk_storage) + +**Phase 4: Services de monitoring (sĂ©quentiel, indĂ©pendant)** +11. loki (base de donnĂ©es logs) +12. promtail (collecte logs → dĂ©pend de loki) +13. grafana (visualisation → dĂ©pend de loki + promtail) + +**Phase 5: Services utilitaires** +14. watchtower + +### 🔧 Principe architectural +- **Services applicatifs** : Fonctionnent indĂ©pendamment du monitoring +- **Services de monitoring** : Observent sans impacter les applications +- **DĂ©pendances** : Seules les dĂ©pendances mĂ©tier sont respectĂ©es +- **Scripts spĂ©cialisĂ©s** : Chaque phase utilise le script appropriĂ© ## Validation finale - [ ] Tous les services dĂ©marrĂ©s et fonctionnels diff --git a/IA_agents/quick-reference-monitoring.md b/IA_agents/quick-reference-monitoring.md index 2db303b..86e7b5d 100644 --- a/IA_agents/quick-reference-monitoring.md +++ b/IA_agents/quick-reference-monitoring.md @@ -16,9 +16,16 @@ ### DĂ©marrage et ArrĂȘt ```bash -# DĂ©marrage avec suivi de progression +# ✅ DĂ©marrage complet avec phases (OBLIGATOIRE) ./scripts/start-with-progress.sh +# ✅ DĂ©marrage monitoring indĂ©pendant (OBLIGATOIRE) +./scripts/start-monitoring.sh + +# ❌ JAMAIS utiliser directement +# docker compose --env-file .env.master up -d +# docker compose --env-file .env.master down + # ArrĂȘt de tous les services docker compose --env-file .env.master down @@ -88,9 +95,26 @@ docker inspect --format='{{.State.Health.Status}}' - **États** : IBD → WebSocket Ready - **Message de santĂ©** : `SDK Relay ready: WebSocket server responding` -## Ordre de DĂ©marrage +## Architecture de DĂ©ploiement par Phases -1. **Tor** → 2. **Bitcoin** → 3. **BlindBit** → 4. **SDK Storage** → 5. **SDK Relay** → 6. **SDK Signer** → 7. **IHM Client** → 8. **LeCoffre Backend** → 9. **LeCoffre Frontend** → 10. **Services de monitoring** +### **Phase 1: Services de Base (ParallĂšle)** +1. **Tor** → 2. **SDK Storage** → 3. **SDK Signer** → 4. **Status API** + +### **Phase 2: Services Blockchain (SĂ©quentiel)** +5. **Bitcoin** → 6. **BlindBit** → 7. **SDK Relay** + +### **Phase 3: Services Applicatifs (SĂ©quentiel)** +8. **LeCoffre Backend** → 9. **LeCoffre Frontend** → 10. **IHM Client** + +### **Phase 4: Services de Monitoring (SĂ©quentiel, IndĂ©pendant)** +11. **Loki** → 12. **Promtail** → 13. **Grafana** + +### **Phase 5: Services Utilitaires** +14. **Watchtower** + +### **Scripts par Phase** +- **Phases 1, 2, 3, 5** : `./scripts/start-with-progress.sh` +- **Phase 4** : `./scripts/start-monitoring.sh` ## URLs de Test