# 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 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
```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 (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"
```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.