254 lines
7.0 KiB
Markdown
254 lines
7.0 KiB
Markdown
# 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
|
|
|
|
### **Configuration Loki (CRITIQUE)**
|
|
- **OBLIGATOIRE** : `http_listen_address: 0.0.0.0` (pas 127.0.0.1)
|
|
- **OBLIGATOIRE** : `instance_addr: 0.0.0.0` (pas 127.0.0.1)
|
|
- **RECOMMANDÉ** : `min_ready_duration: 5s` pour l'ingester
|
|
- **Fichier** : `/conf/loki/loki-config.yaml` avec configuration complète
|
|
|
|
## 📝 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
|