4NK_env/IA_agents/quick-reference-monitoring.md

Guide de Référence Rapide - Monitoring LeCoffre Node

Commandes Essentielles

Surveillance Générale

# 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

# ✅ 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

# Redémarrage d'un service
docker compose --env-file .env.master restart <service>

Vérification de l'État

# 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 (config: 0.0.0.0)
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

Architecture de Déploiement par Phases

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

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"

# Vérifier les logs
docker logs <service> --tail 50

# Vérifier le healthcheck
docker inspect --format='{{.State.Health.Status}}' <service>

Progression Bitcoin Bloquée

# 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

# 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

# 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

# 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

# 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

# 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

# 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.