4NK_vault/storage/dev/README.md

_4NK Vault - Générateur de Configurations

Ce répertoire contient les scripts de génération automatique des configurations pour l'écosystème _4NK Vault.

🚀 Script Principal

generate.sh

Script principal qui orchestre la génération de toutes les configurations nécessaires.

Scripts exécutés dans l'ordre :

1. generate_docker_variables.sh - Génère .env.auto avec les variables Docker
2. generate_docker_compose.sh - Génère docker-compose.yml.auto
3. generate_grafana_dashboards.sh - Génère les dashboards Grafana et config Promtail
4. generate_nginx_configs.sh - Génère les configurations Nginx

📋 Scripts Individuels

1. Génération des Variables Docker

generate_docker_variables.sh

• Génère le fichier .env.auto avec toutes les variables Docker calculées
• Variables globales : DOCKER_GLOBAL_NAME, DOCKER_NETWORK_NAME, DOCKER_VOLUME_PREFIX
• Variables par service : {SERVICE}_DOCKER_NAME, {SERVICE}_DOCKER_IMAGE, etc.

2. Génération du Docker Compose

generate_docker_compose.sh

• Génère le fichier docker-compose.yml.auto basé sur les services définis
• Configuration complète : services, réseaux, volumes
• Ports et variables d'environnement par service

3. Génération des Dashboards Grafana

generate_grafana_dashboards.sh

• Génère les dashboards Grafana pour tous les services
• Configuration Promtail pour la collecte de logs
• Configurations logrotate pour la gestion des logs
• Dashboard overview avec vue d'ensemble

4. Génération des Configurations Nginx

generate_nginx_configs.sh

• Génère nginx/upstreams.conf avec les upstreams et format de log JSON
• Génère nginx/app-internal-ports.conf pour le proxy interne
• Génère nginx/proxy_headers.conf avec les headers de proxy
• Génère nginx/{SERVICE}_https.conf avec les vhosts HTTPS individuels
• Génère nginx/nginx_{HOST}-https.conf avec la configuration HTTPS consolidée
• Génère nginx/validate_templates.sh pour la validation

🔧 Utilisation

Prérequis

# Variables d'environnement requises dans .env
export HOST="dev4._4NKweb.com"
export SERVICES=(REDIS POSTGRESQL LOKI PROMTAIL GRAFANA NGNIX TOR _4NK_VAULT BITCOIN BLINDBIT_ORACLE SDK_RELAY SDK_STORAGE IHM_CLIENT _4NK_CERTIFICATOR _4NK_MINER LECOFFRE_FRONT _4NK_WEB_STATUS)

Exécution

# Charger les variables d'environnement
source .env

# Exécuter la génération complète
./generate.sh

# Ou exécuter un script individuel
./generate_docker_variables.sh
./generate_docker_compose.sh
./generate_grafana_dashboards.sh
./generate_nginx_configs.sh

📁 Structure des Fichiers Générés

storage/dev/
├── .env.auto                    # Variables Docker calculées
├── docker-compose.yml.auto      # Configuration Docker Compose
├── _4NK_modules/
│   ├── grafana/dashboards/      # Dashboards Grafana (.json)
│   └── promtail/promtail.yml    # Configuration Promtail
├── nginx/
│   ├── upstreams.conf           # Upstreams et format de log
│   ├── app-internal-ports.conf  # Proxy interne
│   ├── proxy_headers.conf       # Headers de proxy
│   ├── {SERVICE}_https.conf     # Configurations HTTPS individuelles
│   ├── nginx_{HOST}-https.conf  # Configuration HTTPS consolidée
│   └── validate_templates.sh    # Validation des templates
└── logrotade/                   # Configurations logrotate (.conf)

🛡️ Politique de Déploiement

Principes de Sécurité

1. Chiffrement des Flux : Toutes les communications utilisent HTTPS avec TLS 1.2+
2. Authentification : Authentification par clé utilisateur (X-User-ID)
3. Rotation des Clés : Rotation automatique des clés de chiffrement
4. Isolation des Services : Chaque service dans son propre réseau Docker
5. Logs Sécurisés : Collecte centralisée avec format JSON structuré

🚀 Politique NGINX

Configuration des Templates

• Proxy Redirect Off : Les applications gèrent leurs propres URLs
• Headers de Debug : X-Debug-Scheme et X-Debug-XFP pour le débogage
• HSTS : Strict-Transport-Security activé pour forcer HTTPS
• WebSocket Support : Support natif des WebSockets avec upgrade HTTP/1.1
• Logs JSON : Format structuré pour l'analyse des logs

Architecture des Templates

nginx/
├── upstreams.conf              # Upstreams et format de log JSON
├── app-internal-ports.conf     # Proxy interne (ports dédiés)
├── proxy_headers.conf          # Headers de proxy communs
├── {SERVICE}_https.conf        # Configurations HTTPS individuelles
├── nginx_{HOST}-https.conf     # Configuration HTTPS consolidée
└── validate_templates.sh       # Validation des templates générés

Directives Proxy Standardisées

# Dans proxy_headers.conf
proxy_redirect off;                    # Les apps gèrent leurs URLs
add_header X-Debug-Scheme $scheme always;
add_header X-Debug-XFP $http_x_forwarded_proto always;

# Headers de base
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Gestion des Upstreams

• Keepalive : 64 connexions persistantes par upstream
• Load Balancing : Répartition automatique des requêtes
• Health Checks : Vérification automatique de la disponibilité

Configuration HTTPS

• TLS 1.2+ : Protocoles sécurisés uniquement
• Certificats Dynamiques : Chemins configurables via variables
• Redirection HTTP→HTTPS : Redirection automatique du port 80 vers 443
• HSTS : Headers de sécurité stricts pour forcer HTTPS

Support WebSocket

location /ws/ {
    proxy_pass http://$upstream;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

Format de Logs JSON

log_format app_json escape=json
  '{ "time":"$time_iso8601",'
  '  "client":"$remote_addr",'
  '  "xff":"$http_x_forwarded_for",'
  '  "method":"$request_method",'
  '  "host":"$host",'
  '  "uri":"$request_uri",'
  '  "status":$status,'
  '  "bytes":$body_bytes_sent,'
  '  "ua":"$http_user_agent",'
  '  "upstream":"$upstream_addr",'
  '  "rt":$request_time,'
  '  "urt":$upstream_response_time }';

Gestion des Variables

1. Ordre de Chargement : .env.secrets → .env → .env.auto → .env.post
2. Résolution Récursive : Support des variables imbriquées ($VAR, ${VAR})
3. Protection : Les fichiers .env et .env.secrets ne sont jamais modifiés
4. Remplacement : Les fichiers de sortie sont toujours remplacés complètement

Monitoring et Observabilité

• Dashboards Grafana : Vue d'ensemble et métriques par service
• Collecte de Logs : Promtail + Loki pour l'agrégation des logs
• Rotation des Logs : Configuration logrotate automatique
• Métriques Docker : Monitoring des containers et ressources

Génération de Templates

• Templates Automatiques : Génération automatique de tous les templates
• Docker Compose : Template d'orchestration des services avec volumes persistants
• Réseaux Isolés : Configuration de réseaux Docker par environnement
• Volumes Nommés : Configuration de persistance des données avec volumes nommés
• Validation : Script de validation des templates générés

🔍 Dépannage

Erreurs Communes

1. Variable SERVICES non définie : Vérifiez que SERVICES est défini dans .env
2. Variable HOST non définie : Utilise la valeur par défaut dev4._4NKweb.com
3. Fichiers manquants : Vérifiez que tous les scripts sont présents et exécutables

Logs et Debug

• Les scripts affichent des messages détaillés en mode verbeux
• Les configurations Nginx incluent des headers de debug
• Les logs sont collectés au format JSON pour l'analyse

📚 Documentation des Scripts

Chaque script inclut :

• Documentation complète en en-tête
• Messages d'erreur explicites
• Validation des prérequis
• Gestion des erreurs robuste
• Support des options d'aide (--help)

🔄 Maintenance

Mise à Jour des Configurations

Les scripts sont conçus pour être idempotents :

• Les fichiers de sortie sont toujours remplacés complètement
• Aucune modification des fichiers sources (.env, .env.secrets)
• Régénération possible à tout moment sans conflit

Ajout de Nouveaux Services

1. Ajouter le service à la variable SERVICES dans .env
2. Définir les variables spécifiques au service (ports, base de données, etc.)
3. Relancer ./generate.sh pour régénérer toutes les configurations

Utilisation des Templates

Les templates générés sont prêts à être utilisés dans votre infrastructure :

1. Validation : Utilisez nginx/validate_templates.sh pour vérifier la cohérence
2. Adaptation : Modifiez les chemins et configurations selon vos besoins spécifiques
3. Déploiement : Intégrez les templates dans votre processus de déploiement
4. Rotation des Certificats : Les templates utilisent des variables pour les chemins :
   • $CERT_PATH/certs/fullchain.pem
   • $CERT_PATH/private/privkey.pem
   • Mise à jour automatique lors de la régénération des templates