align for IA agents + grafana

2025-09-21 22:08:02 +00:00 · 2025-09-21 22:08:02 +00:00 · 1c7e23152d
commit 1c7e23152d
parent d09901820b
5 changed files with 1001 additions and 11 deletions
--- a/IA_agents/deploy.md
+++ b/IA_agents/deploy.md
@ -98,17 +98,28 @@ Les configurations ngnix doivent toutes être cenralisées dans lecoffre_node/co
 ### Lancement des services

 30. Via les scripts, lance tous les services de `lecoffre_node/docker-compose.yml`.
-31. Corriger toutes les erreurs, petites et grosses, **sans désactivation**, **sans simplification**, **sans contournement**.
-32. Tester.
-33. Analyser de nouveau les logs.
-34. Vérifier que les logs ne contiennent pas de données personnelles ou sensibles.
-35. Corriger à nouveau si nécessaire (jusqu'à l'absence totale d'erreurs)
-36. Mettre à jour la documentation avec le **retour d’expérience** à chaque fois par une mise à jour de `docs/REX.md`.
-37. Recommencer si nécessaire pour obtenir un déploiement fluide et parfait.
-38. Assures toi d'être à jour pour le service grafana
-39. Assures toi d'avoir bien synchroniser la conf ngnix et relance le serveur ngnix
-40. Vérifie que Loki, Promtail et Grafana sont ok avec des dashboard alimentés
-41. Vérifie qu'il n'y a aucun conflit de ports
+31. **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
+32. **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
+    - **SDK Relay** : Attendre la synchronisation Bitcoin avant le démarrage
+    - **Services LeCoffre** : Vérifier les dépendances avant démarrage
+33. Corriger toutes les erreurs, petites et grosses, **sans désactivation**, **sans simplification**, **sans contournement**.
+34. Tester.
+35. Analyser de nouveau les logs avec les outils de monitoring.
+36. Vérifier que les logs ne contiennent pas de données personnelles ou sensibles.
+37. Corriger à nouveau si nécessaire (jusqu'à l'absence totale d'erreurs)
+38. Mettre à jour la documentation avec le **retour d'expérience** à chaque fois par une mise à jour de `docs/REX.md`.
+39. Recommencer si nécessaire pour obtenir un déploiement fluide et parfait.
+40. Assures toi d'être à jour pour le service grafana
+41. Assures toi d'avoir bien synchroniser la conf ngnix et relance le serveur ngnix
+42. Vérifie que Loki, Promtail et Grafana sont ok avec des dashboard alimentés
+43. Vérifie qu'il n'y a aucun conflit de ports
+44. **Tester l'accès externe** : Vérifier toutes les URLs publiques depuis l'extérieur

 ---

@ -222,6 +233,60 @@ docker compose --env-file .env.master up

 ---

+## Système de Monitoring et Progression
+
+### Healthchecks Informatifs
+
+Tous les services disposent maintenant de healthchecks qui affichent des informations de progression :
+
+- **Bitcoin** : `Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%`
+- **BlindBit** : `BlindBit ready: Oracle service responding`
+- **SDK Relay** : `SDK Relay IBD: Waiting for Bitcoin sync to complete`
+- **Autres services** : Messages clairs sur l'état de démarrage
+
+### Scripts de Monitoring
+
+**Scripts disponibles** :
+- `./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** :
+```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
+```
+
+### 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**
+
+### Progression des Services
+
+- **Bitcoin IBD** : Suivre la progression des blocs téléchargés
+- **BlindBit** : Surveiller l'état du scan des blocs
+- **SDK Relay** : Attendre la synchronisation Bitcoin
+- **Services LeCoffre** : Vérifier les dépendances
+
+### Documentation Complète
+
+Consulter les documents suivants pour plus de détails :
+- `IA_agents/monitoring-progress.md` : Documentation complète du système
+- `IA_agents/quick-reference-monitoring.md` : Guide de référence rapide
+- `IA_agents/troubleshooting-monitoring.md` : Guide de dépannage
+
+---
+
 ## Autres

 N'attend pas infiniment le résultat des curls.
@ -232,6 +297,8 @@ Vérifie que tous les imports sont présents.
 Déclanche les builds via CI.
 Vérifie les droits et le résultats de l'écriture sur les fichiers de conf ngninx et sur les fichiers de conf de Bitcoin.

+**Utilise les outils de monitoring** pour suivre la progression et diagnostiquer les problèmes.
+
 ---

 Met à jour ce document si tu détectes des incohérences ou pose des questions pour confirmer.
--- a/IA_agents/monitoring-progress.md
+++ b/IA_agents/monitoring-progress.md
@ -0,0 +1,313 @@
+# Documentation du Système de Monitoring et Progression
+
+## Vue d'ensemble
+
+Ce document décrit le système de monitoring et de progression mis en place pour le déploiement LeCoffre Node. Le système permet de suivre en temps réel la progression des différents processus (IBD Bitcoin, scans BlindBit, synchronisation SDK Relay, etc.) et d'afficher des informations détaillées sur l'état de tous les services.
+
+## Architecture du Système
+
+### 1. Healthchecks Informatifs dans docker-compose.yml
+
+Chaque service dispose maintenant d'un healthcheck qui affiche des informations de progression au lieu de simples codes de retour.
+
+#### Bitcoin Signet
+```yaml
+healthcheck:
+  test: ["CMD", "sh", "-c", "info=$(bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo 2>/dev/null || echo '{}'); blocks=$(echo \"$info\" | jq -r '.blocks // 0'); headers=$(echo \"$info\" | jq -r '.headers // 0'); if [ \"$blocks\" -eq \"$headers\" ] && [ \"$blocks\" -gt 0 ]; then echo \"Bitcoin sync complete: $blocks blocks\"; exit 0; else echo \"Bitcoin IBD: $blocks/$headers blocks ($(($headers - $blocks)) remaining)\"; exit 1; fi"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+**Messages affichés :**
+- `Bitcoin sync complete: 136548 blocks` (quand synchronisé)
+- `Bitcoin IBD: 34729/136548 blocks (101819 remaining)` (pendant la synchronisation)
+
+#### BlindBit Oracle
+```yaml
+healthcheck:
+  test: ["CMD", "sh", "-c", "code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/tweaks/1); if [ \"$code\" = \"200\" ]; then echo \"BlindBit ready: Oracle service responding\"; exit 0; elif [ \"$code\" = \"000\" ]; then echo \"BlindBit starting: Oracle service not yet ready\"; exit 1; else echo \"BlindBit scanning: Oracle responding with code $code\"; exit 1; fi"]
+  interval: 15s
+  timeout: 5s
+  retries: 10
+```
+
+**Messages affichés :**
+- `BlindBit ready: Oracle service responding` (prêt)
+- `BlindBit starting: Oracle service not yet ready` (démarrage)
+- `BlindBit scanning: Oracle responding with code 404` (scan en cours)
+
+#### SDK Relay
+```yaml
+healthcheck:
+  test: ["CMD", "sh", "-c", "if curl -f http://localhost:8091/ >/dev/null 2>&1; then echo 'SDK Relay ready: WebSocket server responding'; exit 0; else echo 'SDK Relay IBD: Waiting for Bitcoin sync to complete'; exit 1; fi"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+**Messages affichés :**
+- `SDK Relay ready: WebSocket server responding` (prêt)
+- `SDK Relay IBD: Waiting for Bitcoin sync to complete` (en attente)
+
+#### Autres Services
+Tous les autres services (SDK Storage, SDK Signer, LeCoffre Backend/Frontend, IHM Client, Grafana, Loki, Promtail, Status API) ont des healthchecks similaires avec des messages informatifs.
+
+### 2. Scripts de Monitoring
+
+#### monitor-progress.sh
+Script principal pour afficher un aperçu complet de tous les services.
+
+**Fonctionnalités :**
+- Statut de tous les services avec codes couleur
+- Progression Bitcoin avec pourcentage et barre de progression
+- Progression BlindBit avec état du scan
+- Progression SDK Relay avec état WebSocket
+- Statut des autres services
+
+**Utilisation :**
+```bash
+./scripts/monitor-progress.sh
+```
+
+**Exemple de sortie :**
+```
+========================================
+  LeCoffre Node - Monitoring Progress
+========================================
+
+Service Status:
+  ✓ Bitcoin Signet: Ready
+  ✓ BlindBit Oracle: Ready
+  ✓ SDK Storage: Ready
+  ⚠ SDK Relay: Starting/Processing
+  ✗ LeCoffre Backend: Stopped
+  ✗ LeCoffre Frontend: Stopped
+  ✓ IHM Client: Ready
+
+Bitcoin Progress:
+  ⏳ Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%
+
+BlindBit Progress:
+  ✓ BlindBit ready: Oracle service responding
+
+SDK Relay Progress:
+  ⏳ SDK Relay starting: WebSocket server not yet ready
+
+Other Services Progress:
+  ✓ SDK Storage ready: API responding
+  ✓ SDK Signer ready: WebSocket server responding
+  ✓ IHM Client ready: Vite dev server responding
+  ✓ Grafana ready: Dashboard service responding
+```
+
+#### watch-progress.sh
+Script de surveillance en temps réel avec rafraîchissement automatique.
+
+**Fonctionnalités :**
+- Mise à jour automatique toutes les 10 secondes
+- Barre de progression Bitcoin
+- Statut des services en temps réel
+- Services en attente de dépendances
+
+**Utilisation :**
+```bash
+./scripts/watch-progress.sh
+```
+
+**Contrôles :**
+- `Ctrl+C` pour arrêter la surveillance
+
+#### logs-with-progress.sh
+Script pour afficher les logs des services avec informations de progression.
+
+**Fonctionnalités :**
+- Logs en temps réel ou statiques
+- Informations de progression selon le service
+- Support de tous les services
+- Options de personnalisation
+
+**Utilisation :**
+```bash
+# Logs Bitcoin avec progression
+./scripts/logs-with-progress.sh bitcoin -p -n 10
+
+# Logs SDK Relay avec progression
+./scripts/logs-with-progress.sh sdk_relay -p -f
+
+# Logs BlindBit avec progression
+./scripts/logs-with-progress.sh blindbit -p -n 50
+```
+
+**Options :**
+- `-f, --follow` : Suivre les logs en temps réel
+- `-n, --lines N` : Afficher les N dernières lignes
+- `-p, --progress` : Afficher la progression
+- `-h, --help` : Aide
+
+#### start-with-progress.sh
+Script de démarrage ordonné avec suivi de progression.
+
+**Fonctionnalités :**
+- Démarrage des services dans l'ordre correct
+- Attente de la santé de chaque service
+- Affichage de la progression pendant l'attente
+- Test de l'accès externe à la fin
+
+**Utilisation :**
+```bash
+./scripts/start-with-progress.sh
+```
+
+**Ordre de démarrage :**
+1. Tor
+2. Bitcoin (avec suivi IBD)
+3. BlindBit (avec suivi scan)
+4. SDK Storage
+5. SDK Relay (avec suivi IBD)
+6. SDK Signer
+7. IHM Client
+8. LeCoffre Backend
+9. LeCoffre Frontend
+10. Services de monitoring
+
+## Codes Couleur et Symboles
+
+### Symboles de Statut
+- `✓` : 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 (pas de healthcheck)
+
+### Codes Couleur
+- **Vert** : Service prêt et fonctionnel
+- **Jaune** : Service en cours de traitement/démarrage
+- **Rouge** : Service arrêté ou en erreur
+- **Bleu** : Informations générales
+- **Cyan** : Progression spécifique
+- **Violet** : En-têtes de sections
+
+## Progression des Services
+
+### Bitcoin IBD (Initial Block Download)
+- **Affichage** : `Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%`
+- **Barre de progression** : `[████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 25%`
+- **Condition de santé** : `blocks == headers && blocks > 0`
+
+### BlindBit Oracle
+- **États** : Starting → Scanning → Ready
+- **Codes HTTP** : 000 (non prêt), 404 (scan), 200 (prêt)
+- **Messages** : État du scan et réponse du service
+
+### SDK Relay
+- **Dépendance** : Bitcoin synchronisé
+- **États** : IBD → WebSocket Ready
+- **Messages** : Progression du scan et état WebSocket
+
+## Intégration avec Docker Compose
+
+### Variables d'Environnement
+Le système utilise les variables du fichier `.env.master` :
+- `SDK_RELAY_*` : Configuration du service relay
+- `SIGNER_*` : Configuration du service signer
+- `VITE_*` : Configuration des applications frontend
+
+### Commandes Docker Compose
+```bash
+# Démarrage avec variables centralisées
+docker compose --env-file .env.master up -d
+
+# Redémarrage d'un service
+docker compose --env-file .env.master restart bitcoin
+
+# Arrêt de tous les services
+docker compose --env-file .env.master down
+```
+
+## Surveillance et Maintenance
+
+### Vérification de l'État
+```bash
+# Statut de tous les services
+docker compose --env-file .env.master ps
+
+# Logs d'un service spécifique
+docker logs bitcoin-signet --tail 50
+
+# Healthcheck d'un service
+docker inspect --format='{{.State.Health.Status}}' bitcoin-signet
+```
+
+### Dépannage
+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"
+
+## Exemples d'Utilisation
+
+### Surveillance Continue
+```bash
+# Démarrer la surveillance en temps réel
+./scripts/watch-progress.sh
+
+# Dans un autre terminal, afficher les logs
+./scripts/logs-with-progress.sh bitcoin -p -f
+```
+
+### Démarrage Complet
+```bash
+# Arrêter tous les services
+docker compose --env-file .env.master down
+
+# Démarrer avec suivi de progression
+./scripts/start-with-progress.sh
+```
+
+### Vérification Rapide
+```bash
+# Aperçu rapide de tous les services
+./scripts/monitor-progress.sh
+
+# Logs récents avec progression
+./scripts/logs-with-progress.sh sdk_relay -p -n 20
+```
+
+## Personnalisation
+
+### Ajout de Nouveaux Services
+1. Ajouter le healthcheck dans `docker-compose.yml`
+2. Mettre à jour `monitor-progress.sh` avec le nouveau service
+3. Ajouter la logique de progression dans `logs-with-progress.sh`
+
+### Modification des Intervalles
+- **Healthchecks** : Modifier `interval` dans `docker-compose.yml`
+- **Surveillance** : Modifier le `sleep` dans `watch-progress.sh`
+- **Logs** : Utiliser l'option `-n` pour le nombre de lignes
+
+## Bonnes Pratiques
+
+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`
+
+## Dépannage Courant
+
+### Bitcoin IBD Lent
+- Vérifier la connectivité réseau
+- Vérifier l'espace disque disponible
+- Consulter les logs pour les erreurs de connexion
+
+### Services en Attente
+- Vérifier que les services de dépendance sont "healthy"
+- Consulter les logs des services de dépendance
+- Vérifier la configuration des dépendances dans `docker-compose.yml`
+
+### Healthchecks Échoués
+- Vérifier que les ports sont accessibles
+- Consulter les logs du service
+- Vérifier la configuration du healthcheck
+
+Ce système de monitoring et de progression permet une surveillance complète et en temps réel du déploiement LeCoffre Node, facilitant le diagnostic et la maintenance des services.
--- a/IA_agents/prompts/prompt-deploy.md
+++ b/IA_agents/prompts/prompt-deploy.md
@ -5,6 +5,7 @@
 ```
 Déploie l'architecture LeCoffre Node complète en respectant strictement les consignes de déploiement.
 Arrete et nettoie tous les services, images, tests, commandes, éditions... encore actives avant de relancer proprement.
+A la fin met bien à jour les documents de `IA_agents/` et ses sous dossiers.

 ## Contexte obligatoire
 - Consulte attentivement `IA_agents/context.md` pour le contexte technique
--- a/IA_agents/quick-reference-monitoring.md
+++ b/IA_agents/quick-reference-monitoring.md
@ -0,0 +1,237 @@
+# Guide de Référence Rapide - Monitoring LeCoffre Node
+
+## Commandes Essentielles
+
+### Surveillance Générale
+```bash
+# Aperçu complet de tous les services
+./scripts/monitor-progress.sh
+
+# Surveillance en temps réel
+./scripts/watch-progress.sh
+
+# Logs avec progression
+./scripts/logs-with-progress.sh <service> -p
+```
+
+### Démarrage et Arrêt
+```bash
+# Démarrage avec suivi de progression
+./scripts/start-with-progress.sh
+
+# Arrêt de tous les services
+docker compose --env-file .env.master down
+
+# Redémarrage d'un service
+docker compose --env-file .env.master restart <service>
+```
+
+### Vérification de l'État
+```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>
+```
+
+## Services et Leurs Noms
+
+| Service | Nom du Conteneur | Port | Description |
+|---------|------------------|------|-------------|
+| Tor | tor-proxy | 9050 | Proxy SOCKS |
+| Bitcoin | bitcoin-signet | 8332 | Nœud Bitcoin Signet |
+| BlindBit | blindbit-oracle | 8000 | Oracle BlindBit |
+| SDK Storage | sdk_storage | 8081 | Stockage SDK |
+| SDK Relay | sdk_relay | 8090-8091 | Relay WebSocket |
+| SDK Signer | sdk_signer | 3001 | Service de signature |
+| LeCoffre Backend | lecoffre-back | 8080 | API Backend |
+| LeCoffre Frontend | lecoffre-front | 3000 | Interface utilisateur |
+| IHM Client | ihm_client | 3003 | Client IHM |
+| Grafana | grafana | 3005 | Dashboard |
+| Loki | loki | 3100 | Agrégation de logs |
+| Promtail | promtail | 9080 | Collection de logs |
+| Status API | status-api | 3006 | API de statut |
+
+## 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`
+
+## Ordre de Démarrage
+
+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**
+
+## 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/`
+
+## Dépannage Rapide
+
+### Service en État "unhealthy"
+```bash
+# Vérifier les logs
+docker logs <service> --tail 50
+
+# Vérifier le healthcheck
+docker inspect --format='{{.State.Health.Status}}' <service>
+```
+
+### Progression Bitcoin Bloquée
+```bash
+# Vérifier la connectivité
+docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo
+
+# Vérifier les logs
+docker logs bitcoin-signet --tail 20
+```
+
+### Services en Attente
+```bash
+# Vérifier les dépendances
+docker compose --env-file .env.master ps
+
+# Vérifier les logs des services de dépendance
+docker logs <service-dependance> --tail 20
+```
+
+### Erreurs de Connexion
+```bash
+# Vérifier la connectivité réseau
+docker network ls
+docker network inspect lecoffre_node_btcnet
+
+# Vérifier les ports
+netstat -tlnp | grep <port>
+```
+
+## Variables d'Environnement Importantes
+
+### 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
+docker compose --env-file .env.master up -d
+```
+
+## Scripts de Monitoring
+
+### monitor-progress.sh
+- Aperçu complet de tous les services
+- Progression Bitcoin avec pourcentage
+- Statut des services avec codes couleur
+- Progression BlindBit et SDK Relay
+
+### watch-progress.sh
+- Surveillance en temps réel
+- Mise à jour automatique toutes les 10 secondes
+- Barre de progression Bitcoin
+- Services en attente de dépendances
+
+### logs-with-progress.sh
+- Logs avec informations de progression
+- Support de tous les services
+- Options de personnalisation
+- Suivi en temps réel
+
+### start-with-progress.sh
+- Démarrage ordonné des services
+- Attente de la santé de chaque service
+- Affichage de la progression
+- Test de l'accès externe
+
+## Bonnes Pratiques
+
+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
+
+## Exemples d'Utilisation
+
+### Démarrage Complet
+```bash
+# Arrêter tous les services
+docker compose --env-file .env.master down
+
+# Démarrer avec suivi de progression
+./scripts/start-with-progress.sh
+```
+
+### Surveillance Continue
+```bash
+# Démarrer la surveillance en temps réel
+./scripts/watch-progress.sh
+
+# Dans un autre terminal, afficher les logs
+./scripts/logs-with-progress.sh bitcoin -p -f
+```
+
+### Vérification Rapide
+```bash
+# Aperçu rapide de tous les services
+./scripts/monitor-progress.sh
+
+# Logs récents avec progression
+./scripts/logs-with-progress.sh sdk_relay -p -n 20
+```
+
+Ce guide de référence rapide permet aux agents IA d'utiliser efficacement le système de monitoring et de progression du déploiement LeCoffre Node.
--- a/IA_agents/troubleshooting-monitoring.md
+++ b/IA_agents/troubleshooting-monitoring.md
@ -0,0 +1,372 @@
+# Guide de Dépannage - Monitoring LeCoffre Node
+
+## Problèmes Courants et Solutions
+
+### 1. Services en État "unhealthy"
+
+#### Symptômes
+- Service affiché comme "unhealthy" dans `docker compose ps`
+- Healthcheck échoue constamment
+- Service ne répond pas aux requêtes
+
+#### Diagnostic
+```bash
+# Vérifier le statut du healthcheck
+docker inspect --format='{{.State.Health.Status}}' <service>
+
+# Vérifier les logs du healthcheck
+docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' <service>
+
+# Vérifier les logs du service
+docker logs <service> --tail 50
+```
+
+#### Solutions
+1. **Vérifier la connectivité réseau**
+   ```bash
+   # Vérifier que le service écoute sur le bon port
+   docker exec <service> netstat -tlnp
+   
+   # Vérifier la connectivité depuis l'extérieur
+   curl -f http://localhost:<port>/health
+   ```
+
+2. **Vérifier les dépendances**
+   ```bash
+   # Vérifier que les services de dépendance sont "healthy"
+   docker compose --env-file .env.master ps
+   ```
+
+3. **Redémarrer le service**
+   ```bash
+   docker compose --env-file .env.master restart <service>
+   ```
+
+### 2. Progression Bitcoin Bloquée
+
+#### Symptômes
+- Bitcoin IBD reste à un pourcentage fixe
+- Pas de nouveaux blocs téléchargés
+- Messages d'erreur dans les logs
+
+#### Diagnostic
+```bash
+# Vérifier l'état de la blockchain
+docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getblockchaininfo
+
+# Vérifier les connexions
+docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getpeerinfo
+
+# Vérifier les logs
+docker logs bitcoin-signet --tail 100 | grep -E "(ERROR|error|Error|WARN|warn|Warn)"
+```
+
+#### Solutions
+1. **Vérifier la connectivité réseau**
+   ```bash
+   # Vérifier que Tor fonctionne
+   docker logs tor-proxy --tail 20
+   
+   # Vérifier la connectivité Bitcoin
+   docker exec bitcoin-signet bitcoin-cli -conf=/etc/bitcoin/bitcoin.conf getnetworkinfo
+   ```
+
+2. **Vérifier l'espace disque**
+   ```bash
+   # Vérifier l'espace disponible
+   df -h
+   
+   # Vérifier la taille du volume Bitcoin
+   docker volume inspect 4nk_node_bitcoin_data
+   ```
+
+3. **Redémarrer Bitcoin**
+   ```bash
+   docker compose --env-file .env.master restart bitcoin
+   ```
+
+### 3. Services en Attente de Dépendances
+
+#### Symptômes
+- Services affichés comme "Stopped"
+- Messages "dependency failed to start"
+- Services ne démarrent pas
+
+#### Diagnostic
+```bash
+# Vérifier les dépendances dans docker-compose.yml
+grep -A 5 -B 5 "depends_on" docker-compose.yml
+
+# Vérifier le statut des services de dépendance
+docker compose --env-file .env.master ps
+```
+
+#### Solutions
+1. **Démarrer les services dans l'ordre correct**
+   ```bash
+   # Utiliser le script de démarrage ordonné
+   ./scripts/start-with-progress.sh
+   ```
+
+2. **Vérifier les conditions de dépendance**
+   ```bash
+   # Vérifier que les services de dépendance sont "healthy"
+   docker inspect --format='{{.State.Health.Status}}' <service-dependance>
+   ```
+
+3. **Modifier temporairement les dépendances**
+   ```bash
+   # Changer condition: service_healthy en condition: service_started
+   # (Attention : à remettre en place après résolution)
+   ```
+
+### 4. Erreurs de Connexion WebSocket
+
+#### Symptômes
+- SDK Relay ne répond pas sur le port 8091
+- Erreurs 502 Bad Gateway pour les WebSockets
+- Messages "TLS support not compiled in"
+
+#### Diagnostic
+```bash
+# Vérifier que le service écoute sur le bon port
+docker exec sdk_relay netstat -tlnp
+
+# Vérifier les logs du service
+docker logs sdk_relay --tail 50
+
+# Tester la connectivité locale
+curl -f http://localhost:8091/
+```
+
+#### Solutions
+1. **Vérifier la configuration Nginx**
+   ```bash
+   # Vérifier la configuration WebSocket
+   sudo grep -A 10 -B 5 "ws/" /etc/nginx/sites-enabled/dev4.4nkweb.com-https.conf
+   
+   # Tester la configuration Nginx
+   sudo nginx -t
+   ```
+
+2. **Vérifier les variables d'environnement**
+   ```bash
+   # Vérifier la configuration du SDK Relay
+   docker exec sdk_relay env | grep SDK_RELAY
+   ```
+
+3. **Redémarrer le service**
+   ```bash
+   docker compose --env-file .env.master restart sdk_relay
+   ```
+
+### 5. Problèmes de Permissions
+
+#### Symptômes
+- Erreurs "Permission denied"
+- Services ne peuvent pas écrire dans les volumes
+- Erreurs de montage de volumes
+
+#### Diagnostic
+```bash
+# Vérifier les permissions des volumes
+docker volume inspect <volume-name>
+
+# Vérifier les permissions des dossiers locaux
+ls -la logs/
+ls -la conf/
+```
+
+#### Solutions
+1. **Corriger les permissions des volumes**
+   ```bash
+   # Corriger les permissions des logs
+   sudo chown -R 1000:1000 logs/
+   sudo chmod -R 755 logs/
+   ```
+
+2. **Vérifier la configuration des volumes**
+   ```bash
+   # Vérifier la configuration dans docker-compose.yml
+   grep -A 5 -B 5 "volumes:" docker-compose.yml
+   ```
+
+3. **Redémarrer les services**
+   ```bash
+   docker compose --env-file .env.master down
+   docker compose --env-file .env.master up -d
+   ```
+
+### 6. Problèmes de Configuration
+
+#### Symptômes
+- Services ne démarrent pas
+- Erreurs de configuration dans les logs
+- Variables d'environnement manquantes
+
+#### Diagnostic
+```bash
+# Vérifier la configuration Docker Compose
+docker compose --env-file .env.master config
+
+# Vérifier les variables d'environnement
+docker exec <service> env | grep <VARIABLE>
+
+# Vérifier les fichiers de configuration
+cat .env.master | grep <VARIABLE>
+```
+
+#### Solutions
+1. **Vérifier le fichier .env.master**
+   ```bash
+   # Vérifier que toutes les variables sont définies
+   docker compose --env-file .env.master config --services
+   ```
+
+2. **Corriger les variables manquantes**
+   ```bash
+   # Ajouter les variables manquantes dans .env.master
+   echo "VARIABLE=valeur" >> .env.master
+   ```
+
+3. **Redémarrer les services**
+   ```bash
+   docker compose --env-file .env.master down
+   docker compose --env-file .env.master up -d
+   ```
+
+## Outils de Diagnostic
+
+### Scripts de Diagnostic
+```bash
+# Diagnostic complet
+./scripts/monitor-progress.sh
+
+# Logs avec progression
+./scripts/logs-with-progress.sh <service> -p -n 100
+
+# Surveillance en temps réel
+./scripts/watch-progress.sh
+```
+
+### Commandes Docker Utiles
+```bash
+# Informations détaillées sur un service
+docker inspect <service>
+
+# Logs en temps réel
+docker logs -f <service>
+
+# Exécuter une commande dans un conteneur
+docker exec -it <service> /bin/bash
+
+# Vérifier l'utilisation des ressources
+docker stats <service>
+```
+
+### Commandes Système
+```bash
+# Vérifier l'espace disque
+df -h
+
+# Vérifier la mémoire
+free -h
+
+# Vérifier les processus
+ps aux | grep docker
+
+# Vérifier les ports
+netstat -tlnp | grep <port>
+```
+
+## Procédures de Récupération
+
+### Récupération Complète
+```bash
+# Arrêter tous les services
+docker compose --env-file .env.master down
+
+# Nettoyer le système Docker
+docker system prune -af --volumes
+
+# Redémarrer avec le script de progression
+./scripts/start-with-progress.sh
+```
+
+### Récupération d'un Service
+```bash
+# Arrêter le service
+docker compose --env-file .env.master stop <service>
+
+# Supprimer le conteneur
+docker compose --env-file .env.master rm <service>
+
+# Redémarrer le service
+docker compose --env-file .env.master up -d <service>
+```
+
+### Récupération des Volumes
+```bash
+# Arrêter tous les services
+docker compose --env-file .env.master down
+
+# Supprimer les volumes
+docker volume rm <volume-name>
+
+# Redémarrer les services
+docker compose --env-file .env.master up -d
+```
+
+## Logs et Monitoring
+
+### Logs Importants
+```bash
+# Logs Bitcoin
+docker logs bitcoin-signet --tail 100
+
+# Logs SDK Relay
+docker logs sdk_relay --tail 100
+
+# Logs BlindBit
+docker logs blindbit-oracle --tail 100
+
+# Logs Nginx
+sudo tail -f /var/log/nginx/error.log
+```
+
+### Monitoring des Ressources
+```bash
+# Utilisation des ressources
+docker stats
+
+# Espace disque
+df -h
+
+# Mémoire
+free -h
+
+# CPU
+top
+```
+
+## Prévention des Problèmes
+
+### Vérifications Régulières
+1. **Vérifier l'espace disque** : `df -h`
+2. **Vérifier la mémoire** : `free -h`
+3. **Vérifier les logs** : `./scripts/monitor-progress.sh`
+4. **Vérifier la connectivité** : Tester les URLs externes
+
+### Maintenance Préventive
+1. **Nettoyer les logs** : `docker system prune -f`
+2. **Vérifier les mises à jour** : `docker images`
+3. **Sauvegarder les configurations** : Copier `.env.master`
+4. **Tester les sauvegardes** : Vérifier les volumes
+
+### Surveillance Continue
+1. **Utiliser les scripts de monitoring** : `./scripts/watch-progress.sh`
+2. **Configurer des alertes** : Surveiller les logs d'erreur
+3. **Vérifier les performances** : `docker stats`
+4. **Tester la connectivité** : Vérifier les URLs externes
+
+Ce guide de dépannage permet aux agents IA de diagnostiquer et résoudre rapidement les problèmes courants du système de monitoring LeCoffre Node.