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
```bash
# 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
```bash
# 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
```nginx
# 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
```nginx
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
```nginx
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