4nk/4NK_env
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_env/docs/DEPLOYMENT_GUIDE.md

10 KiB
Raw Blame History

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

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

# 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

# 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

# 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

# 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

# Synchroniser les configurations
./scripts/sync-configs.sh

# Vérifier les variables d'environnement
./scripts/validate-deployment.sh

Problèmes de monitoring

# 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

# ✅ CORRECT
./scripts/start.sh
./scripts/start-monitoring.sh

# ❌ INCORRECT
docker compose up -d

Règle 2: Respecter l'ordre par phases

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

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

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

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