331 lines
10 KiB
Markdown
331 lines
10 KiB
Markdown
# Guide de Déploiement Complet - 4NK Environment
|
|
|
|
**Date** : 2025-01-27
|
|
**Version** : 2.0
|
|
**Contexte** : Guide de déploiement complet pour les agents IA et l'équipe de développement
|
|
|
|
## 📋 Vue d'ensemble du Déploiement
|
|
|
|
Ce guide présente le processus de déploiement complet de l'environnement 4NK, incluant tous les modules, le projet LeCoffre, et le système de monitoring.
|
|
|
|
## 🚀 Prérequis et Préparation
|
|
|
|
### Environnement Système
|
|
- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
|
|
- **Docker** : 20.10+ avec Docker Compose 2.0+
|
|
- **RAM** : Minimum 8 GB, 16 GB recommandé
|
|
- **Stockage** : Minimum 100 GB pour la blockchain et les données
|
|
- **Réseau** : Connexion stable à Internet
|
|
|
|
### Accès et Authentification
|
|
- **SSH** : Clés SSH configurées pour git.4nkweb.com
|
|
- **Docker Registry** : Accès à git.4nkweb.com/4nk/
|
|
- **Certificats** : Certificats SSL pour HTTPS (auto-signés en dev)
|
|
|
|
### Variables d'Environnement
|
|
- **Fichier principal** : `.env.master` dans la racine du projet
|
|
- **Synchronisation** : 4NK_vault synchronise vers `confs/`
|
|
- **Protection** : Fichiers .env inaccessibles pour des raisons de sécurité
|
|
|
|
## 🏗️ Architecture de Déploiement par Phases
|
|
|
|
### Principe Fondamental
|
|
Les services sont organisés en **5 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 | Description |
|
|
|---------|------|------------|--------|-------------|
|
|
| **tor** | 9050 | Aucune | `start.sh` | Proxy anonyme |
|
|
| **sdk_storage** | 8081 | Aucune | `start.sh` | Stockage temporaire |
|
|
| **status-api** | 3006 | Aucune | `start.sh` | API de statut |
|
|
|
|
### Phase 2: Services Blockchain (Séquentiel)
|
|
Ces services suivent la chaîne blockchain :
|
|
|
|
| Service | Port | Dépendance | Script | Description |
|
|
|---------|------|------------|--------|-------------|
|
|
| **bitcoin** | 8332 | tor (healthy) | `start.sh` | Nœud Bitcoin Signet |
|
|
| **blindbit** | 8000 | bitcoin (healthy) | `start.sh` | Oracle Bitcoin |
|
|
| **sdk_relay** | 8090-8091 | blindbit (healthy) | `start.sh` | Relais WebSocket |
|
|
|
|
### Phase 3: Services Applicatifs (Séquentiel)
|
|
Ces services suivent la chaîne applicative :
|
|
|
|
| Service | Port | Dépendance | Script | Description |
|
|
|---------|------|------------|--------|-------------|
|
|
| **lecoffre-front** | 3004 | sdk_relay + sdk_storage | `start.sh` | Frontend Next.js |
|
|
| **ihm_client** | 3003 | sdk_relay + sdk_storage | `start.sh` | Interface utilisateur |
|
|
|
|
### Phase 4: Services de Monitoring (Séquentiel, Indépendant)
|
|
Ces services sont indépendants des applications :
|
|
|
|
| Service | Port | Dépendance | Script | Description |
|
|
|---------|------|------------|--------|-------------|
|
|
| **loki** | 3100 | Aucune | `start-monitoring.sh` | Collecte de logs |
|
|
| **promtail** | 9080 | loki (healthy) | `start-monitoring.sh` | Agent de collecte |
|
|
| **grafana** | 3005 | loki + promtail (healthy) | `start-monitoring.sh` | Dashboards |
|
|
|
|
### Phase 5: Services Utilitaires
|
|
Services de maintenance et surveillance :
|
|
|
|
| Service | Port | Dépendance | Script | Description |
|
|
|---------|------|------------|--------|-------------|
|
|
| **watchtower** | 8080 | Aucune | `start.sh` | Mise à jour automatique |
|
|
|
|
## 🔧 Scripts de Déploiement
|
|
|
|
### Scripts OBLIGATOIRES
|
|
|
|
#### `./scripts/start.sh`
|
|
**Usage** : Démarrage complet avec phases
|
|
**Fonction** : Démarre les services applicatifs dans l'ordre correct
|
|
**Phases** : 1, 2, 3, 5
|
|
**Fonctionnalités** :
|
|
- Démarrage séquentiel avec progression
|
|
- Vérification des variables d'environnement
|
|
- Healthchecks informatifs
|
|
- Tests d'URLs complets
|
|
- Surveillance continue
|
|
|
|
#### `./scripts/start-monitoring.sh`
|
|
**Usage** : Démarrage monitoring indépendant
|
|
**Fonction** : Démarre les services de monitoring dans l'ordre correct
|
|
**Phases** : 4 uniquement
|
|
**Fonctionnalités** :
|
|
- Démarrage indépendant du monitoring
|
|
- Configuration Loki critique
|
|
- Dashboards Grafana
|
|
|
|
#### `./scripts/validate-deployment.sh`
|
|
**Usage** : Validation complète du déploiement
|
|
**Fonction** : Vérifie tous les services, volumes, et configurations
|
|
**Fonctionnalités** :
|
|
- Validation des services
|
|
- Validation des volumes
|
|
- Validation des URLs publiques
|
|
- Validation des WebSockets
|
|
- Validation des scripts
|
|
- Validation des variables d'environnement
|
|
|
|
### Scripts INTERDITS
|
|
```bash
|
|
# ❌ JAMAIS utiliser ces commandes
|
|
docker compose --env-file .env.master up -d
|
|
docker compose up -d
|
|
docker compose start
|
|
```
|
|
|
|
## 📊 Flux de Déploiement Complet
|
|
|
|
### Étape 1: Préparation
|
|
1. **Vérifier l'environnement** : Docker, RAM, stockage
|
|
2. **Synchroniser les configurations** : 4NK_vault → confs/
|
|
3. **Vérifier les variables d'environnement** : .env.master
|
|
4. **Préparer les volumes** : Données persistantes
|
|
|
|
### Étape 2: Déploiement Services Applicatifs
|
|
```bash
|
|
# Démarrage complet avec phases
|
|
./scripts/start.sh
|
|
```
|
|
|
|
**Progression attendue** :
|
|
1. **Phase 1** : tor, sdk_storage, status-api (parallèle)
|
|
2. **Phase 2** : bitcoin → blindbit → sdk_relay (séquentiel)
|
|
3. **Phase 3** : lecoffre-front, ihm_client (séquentiel)
|
|
4. **Phase 5** : watchtower (utilitaire)
|
|
|
|
### Étape 3: Déploiement Monitoring
|
|
```bash
|
|
# Démarrage monitoring indépendant
|
|
./scripts/start-monitoring.sh
|
|
```
|
|
|
|
**Progression attendue** :
|
|
1. **loki** : Collecte de logs
|
|
2. **promtail** : Agent de collecte
|
|
3. **grafana** : Dashboards
|
|
|
|
### Étape 4: Validation
|
|
```bash
|
|
# Validation complète
|
|
./scripts/validate-deployment.sh
|
|
```
|
|
|
|
**Tests effectués** :
|
|
- Services Docker
|
|
- Volumes persistants
|
|
- URLs publiques
|
|
- WebSockets
|
|
- Variables d'environnement
|
|
|
|
## 🔍 Configuration Critique
|
|
|
|
### 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)
|
|
- **Fichier** : `/conf/loki/loki-config.yaml`
|
|
- **Healthcheck** : `wget` (pas `curl`)
|
|
|
|
### Variables d'Environnement par Service
|
|
- **bitcoin** : BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, BITCOIN_RPC_PORT
|
|
- **blindbit** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
|
|
- **sdk_relay** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
|
|
- **sdk_storage** : STORAGE_PORT, STORAGE_DATA_DIR
|
|
- **lecoffre-front** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_IDNOT_BASE_URL
|
|
- **ihm_client** : VITE_API_URL, VITE_4NK_URL, VITE_RELAY_URL
|
|
- **grafana** : GF_SECURITY_ADMIN_PASSWORD, GF_DATABASE_TYPE
|
|
- **loki** : LOKI_CONFIG_FILE, LOKI_DATA_DIR
|
|
- **promtail** : PROMTAIL_CONFIG_FILE, LOKI_URL
|
|
- **status-api** : STATUS_API_PORT, STATUS_API_HOST
|
|
|
|
## 📊 Monitoring et Observabilité
|
|
|
|
### Stack de Monitoring
|
|
- **Grafana** : Dashboards et visualisation
|
|
- **Loki** : Collecte et stockage des logs
|
|
- **Promtail** : Agent de collecte des logs
|
|
- **Watchtower** : Mise à jour automatique
|
|
|
|
### Dashboards Disponibles
|
|
- Vue d'ensemble LeCoffre
|
|
- Bitcoin & Miner
|
|
- Services Applications
|
|
- SDK Services
|
|
- Frontend Services
|
|
|
|
### Logs Centralisés
|
|
- **Répertoire** : `/home/debian/4NK_env/projects/lecoffre/lecoffre_node/logs/`
|
|
- **Services** : tor, bitcoin, blindbit, sdk_relay, sdk_storage, lecoffre-front, ihm_client, grafana, loki, promtail, status-api
|
|
- **Collecte** : Promtail → Loki → Grafana
|
|
|
|
## 🚨 Dépannage et Maintenance
|
|
|
|
### Problèmes Courants
|
|
|
|
#### Services non accessibles
|
|
```bash
|
|
# Vérifier le statut
|
|
docker compose --env-file .env.master -f docker-compose.yml ps
|
|
|
|
# Vérifier les logs
|
|
docker compose --env-file .env.master -f docker-compose.yml logs -f <service>
|
|
```
|
|
|
|
#### Erreurs de configuration
|
|
```bash
|
|
# Synchroniser les configurations
|
|
./scripts/sync-configs.sh
|
|
|
|
# Vérifier les variables d'environnement
|
|
./scripts/validate-deployment.sh
|
|
```
|
|
|
|
#### Problèmes de monitoring
|
|
```bash
|
|
# Redémarrer le monitoring
|
|
./scripts/start-monitoring.sh
|
|
|
|
# Vérifier la configuration Loki
|
|
cat confs/loki/loki-config.yaml
|
|
```
|
|
|
|
### Scripts de Maintenance
|
|
- **backup-data.sh** : Sauvegarde des données
|
|
- **restore-data.sh** : Restauration des données
|
|
- **update-images.sh** : Mise à jour des images
|
|
- **collect-logs.sh** : Collecte des logs
|
|
- **maintenance.sh** : Menu de maintenance interactif
|
|
|
|
## 🎯 Bonnes Pratiques
|
|
|
|
### Règles d'Or pour les Agents IA
|
|
|
|
#### Règle 1: Toujours utiliser les scripts spécialisés
|
|
```bash
|
|
# ✅ CORRECT
|
|
./scripts/start.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.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/validate-deployment.sh
|
|
./scripts/monitor-progress.sh
|
|
|
|
# ❌ INCORRECT : Démarrage sans suivi
|
|
docker_compose_up_et_oublier
|
|
```
|
|
|
|
#### Règle 5: Diagnostic facilité
|
|
```bash
|
|
# ✅ CORRECT : Logs avec progression
|
|
./scripts/collect-logs.sh
|
|
./scripts/validate-deployment.sh
|
|
|
|
# ❌ INCORRECT : Logs bruts
|
|
docker logs <service>
|
|
```
|
|
|
|
## 📝 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
|
|
|
|
## 🔄 Mise à Jour et Maintenance
|
|
|
|
### Mise à Jour Automatique
|
|
- **Watchtower** : Mise à jour automatique toutes les 30 secondes
|
|
- **Images** : Tag `ext` pour toutes les images
|
|
- **Configuration** : Synchronisation automatique via 4NK_vault
|
|
|
|
### Maintenance Préventive
|
|
- **Sauvegarde** : `./scripts/backup-data.sh`
|
|
- **Logs** : `./scripts/collect-logs.sh`
|
|
- **Validation** : `./scripts/validate-deployment.sh`
|
|
- **Mise à jour** : `./scripts/update-images.sh`
|
|
|
|
---
|
|
|
|
**Document créé le 2025-01-27**
|
|
**Version** : 2.0
|
|
**Usage** : Guide de déploiement complet pour les agents IA et l'équipe de développement
|