From 823aab62d8a9741fc464a15a717d2ba2c109dcb5 Mon Sep 17 00:00:00 2001 From: LeCoffre Deployment Date: Sun, 21 Sep 2025 22:36:27 +0000 Subject: [PATCH] ci: docker_tag=ext - Implement optimal deployment architecture with phase-based startup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add deployment architecture with 5 phases (base, blockchain, apps, monitoring, utils) - Create start-monitoring.sh for independent monitoring services startup - Update start-with-progress.sh with phase-based deployment - Add deployment-architecture.md with complete architecture documentation - Add best-practices-deployment.md with mandatory rules and prohibitions - Update prompt-deploy.md with mandatory script usage and phase structure - Update quick-reference-monitoring.md with new architecture - Update monitoring-progress.md with correct startup procedures - Add comprehensive README.md for IA agents with all documentation - Enforce separation between application and monitoring services - Implement Loki → Promtail → Grafana sequential startup for monitoring - Prohibit direct docker compose usage, mandate specialized scripts --- IA_agents/README.md | 345 ++++++++++++------------ IA_agents/best-practices-deployment.md | 247 +++++++++++++++++ IA_agents/deployment-architecture.md | 181 +++++++++++++ IA_agents/monitoring-progress.md | 8 +- IA_agents/prompts/prompt-deploy.md | 85 ++++-- IA_agents/quick-reference-monitoring.md | 30 ++- 6 files changed, 692 insertions(+), 204 deletions(-) create mode 100644 IA_agents/best-practices-deployment.md create mode 100644 IA_agents/deployment-architecture.md 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