ci: docker_tag=ext - Implement optimal deployment architecture with phase-based startup

- 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
2025-09-21 22:36:27 +00:00 · 2025-09-21 22:36:27 +00:00 · 823aab62d8
commit 823aab62d8
parent 3259feeca8
6 changed files with 692 additions and 204 deletions
--- 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 <service> --tail 50
-
-# Healthcheck d'un service
-docker inspect --format='{{.State.Health.Status}}' <service>
-
-# 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 <service>`
-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
--- a/IA_agents/best-practices-deployment.md
+++ 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
--- a/IA_agents/deployment-architecture.md
+++ 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
--- 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
--- 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
--- 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}}' <service>
 - **É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