4NK_vault/docs/templates-system.md

# Système de Templates et Génération Automatisée

## 🎯 Vue d'ensemble

Le système de templates de 4NK Vault permet de générer automatiquement toutes les configurations nécessaires à partir de templates sources avec variables d'environnement. Cette approche garantit la cohérence, la maintenabilité et la sécurité des configurations.

## 🏗️ Architecture du Système

### Workflow de Génération

```
templates/<env>/          →    Génération    →    storage/<env>/
├── .env.secrets          →    Scripts       →    ├── .env.auto
├── .env                  →    de génération →    ├── docker-compose.yml.auto
├── .env.post             →                  →    ├── _4NK_modules/
├── _4NK_modules/         →                  →    ├── 4NK_modules/
├── 4NK_modules/          →                  →    ├── logrotade/
└── nginx/                →                  →    └── nginx/
```

### Séparation des Responsabilités

- **`templates/`** : Fichiers sources avec variables (`$VARIABLE`)
- **`storage/`** : Fichiers finaux avec variables résolues (lecture seule par API)
- **Scripts de génération** : Orchestrent la création et la résolution des variables

## 📋 Scripts de Génération

### 1. Script Principal : `generate.sh`

Orchestrateur principal qui exécute tous les scripts de génération dans l'ordre correct.

```bash
cd templates/dev
./generate.sh
```

**Étapes d'exécution :**
1. Génération des variables d'environnement
2. Génération des dashboards Grafana
3. Génération de la configuration Promtail
4. Génération des configurations logrotate
5. Génération des configurations nginx
6. Résolution des variables et copie vers storage/

### 2. Génération des Variables : `generate_variables.sh`

Génère les variables d'environnement et le fichier Docker Compose à partir des services définis.

**Fonctionnalités :**
- Génération des variables internes pour chaque service
- Génération des variables externes (URLs, ports)
- Création du fichier `docker-compose.yml.auto`
- Support des services externes (BOOTSTRAP, LECOFFRE_BACK_MINI)

**Variables générées par service :**
```bash
${SERVICE}_DOCKER_NAME=$SERVICE
${SERVICE}_CONFS_DIR=$DOCKER_GLOBAL/confs/$SERVICE
${SERVICE}_LOGS_DIR=$DOCKER_GLOBAL/logs/$SERVICE
${SERVICE}_DATAS_DIR=$DOCKER_GLOBAL/datas/$SERVICE
${SERVICE}_URL_ROUTE=/$SERVICE
${SERVICE}_URL=http://$SERVICE_DOCKER_NAME:$SERVICE_DOCKER_PORT
${SERVICE}_URL_EXTERNAL=https://$HOST$SERVICE_URL_ROUTE
```

### 3. Génération Grafana : `generate_grafana_dashboards.sh`

Génère automatiquement les dashboards Grafana pour tous les services.

**Types de dashboards :**
- **Services Overview** : Vue d'ensemble de tous les services
- **Bitcoin Services** : Dashboards spécialisés Bitcoin
- **Frontend Services** : Dashboards pour les interfaces utilisateur
- **SDK Services** : Dashboards pour les services SDK

### 4. Génération Promtail : `generate_promtail_config.sh`

Génère la configuration Promtail pour la collecte de logs.

**Fonctionnalités :**
- Configuration automatique des jobs de collecte
- Support des logs Docker et fichiers locaux
- Variables dynamiques pour les chemins de logs

### 5. Génération Logrotate : `generate_logrotate_configs.sh`

Génère les configurations logrotate pour tous les services.

**Fonctionnalités :**
- Rotation automatique des logs
- Compression et archivage
- Redémarrage des services après rotation

### 6. Génération Nginx : `generate_nginx_configs.sh`

Génère les configurations nginx pour tous les services.

**Types de configurations :**
- Upstreams pour les services
- Configurations HTTPS
- Headers proxy
- Ports internes

### 7. Résolution des Variables : `replace_variables_and_copy.sh`

**Fonctionnalités principales :**
- Chargement séquentiel des fichiers `.env`
- Résolution multi-passes des variables imbriquées
- Copie des fichiers traités vers `storage/`

**Ordre de chargement :**
1. `.env.secrets` - Variables sensibles
2. `.env` - Variables principales
3. `.env.auto` - Variables générées (avec résolution)
4. `.env.post` - Variables finales (avec résolution)

**Résolution multi-passes :**
- Jusqu'à 5 passes pour résoudre les variables imbriquées
- Protection contre les dépendances circulaires
- Export explicite de toutes les variables

## 🔧 Configuration des Variables

### Structure des Fichiers d'Environnement

#### `.env.secrets`
Variables sensibles (clés API, mots de passe, etc.)
```bash
# Variables sensibles
API_SECRET_KEY=secret_value
DATABASE_PASSWORD=password
```

#### `.env`
Variables principales du système
```bash
# Configuration de base
ROOT_DIR=/home/debian/_4NK_env
DOMAIN=_4NKweb.com
HOST=dev4.$DOMAIN

# Services
export SERVICES=(
    "REDIS"
    "POSTGRESQL"
    "BITCOIN"
    # ...
)

# Services externes
export SERVICES_EXTERNAL=(
    "BOOTSTRAP"
    "LECOFFRE_BACK_MINI"
)
```

#### `.env.post`
Variables composites et finales
```bash
# URLs composites
SDK_RELAY_BOOSTRAP_URL=$BOOTSTRAP_URL_WS_EXTERNAL
RELAY_URLS=$SDK_RELAY_URL,$SDK_RELAY_BOOSTRAP_URL
BITCOIN_RPC_URL=http://$BITCOIN_DOCKER_NAME:$BITCOIN_SIGNET_RPC_PORT
```

### Résolution des Variables

#### Exemple de Résolution Complexe

**Variables de base :**
```bash
ROOT_DIR=/home/debian/_4NK_env
DOCKER_GLOBAL_NAME=projects/lecoffre/lecoffre_node
BITCOIN=bitcoin
```

**Variables intermédiaires :**
```bash
DOCKER_GLOBAL=$ROOT_DIR/$DOCKER_GLOBAL_NAME
```

**Variables finales :**
```bash
BITCOIN_DATAS_DIR=$DOCKER_GLOBAL/datas/$BITCOIN
```

**Résultat final :**
```bash
BITCOIN_DATAS_DIR=/home/debian/_4NK_env/projects/lecoffre/lecoffre_node/datas/bitcoin
```

## 🚀 Utilisation

### Génération Complète

```bash
# Générer toutes les configurations
cd templates/dev
./generate.sh
```

### Génération Partielle

```bash
# Générer seulement les variables
./generate_variables.sh

# Générer seulement les dashboards Grafana
./generate_grafana_dashboards.sh

# Résoudre les variables et copier
./replace_variables_and_copy.sh
```

### Vérification

```bash
# Vérifier les variables résolues
cd storage/dev
grep "datadir" _4NK_modules/bitcoin/bitcoin.conf
# Résultat: datadir=/home/debian/_4NK_env/projects/lecoffre/lecoffre_node/datas/bitcoin

# Vérifier les URLs externes
grep "BOOTSTRAP_URL_WS_EXTERNAL" .env.auto
# Résultat: BOOTSTRAP_URL_WS_EXTERNAL=wss://dev3._4NKweb.com:3006/ws
```

## 🔒 Sécurité

### Protection des Templates

- Les fichiers dans `templates/` ne sont jamais modifiés par l'API
- Seuls les fichiers dans `storage/` sont accessibles via l'API
- Les fichiers `.env.secrets` ne sont jamais copiés dans `storage/`

### Isolation des Environnements

- Chaque environnement (`dev`, `prod`) a ses propres templates
- Variables d'environnement isolées par environnement
- Pas de fuite de données entre environnements

## 🛠️ Maintenance

### Ajout d'un Nouveau Service

1. **Ajouter le service dans `.env` :**
```bash
export SERVICES=(
    "REDIS"
    "POSTGRESQL"
    "NOUVEAU_SERVICE"  # Ajouter ici
    # ...
)
```

2. **Définir les variables du service :**
```bash
NOUVEAU_SERVICE=nouveau_service
NOUVEAU_SERVICE_IMAGE=image:tag
NOUVEAU_SERVICE_PORT=8080:8080
```

3. **Régénérer les configurations :**
```bash
cd templates/dev
./generate.sh
```

### Modification des Variables

1. **Modifier les fichiers appropriés** dans `templates/dev/`
2. **Régénérer les configurations :**
```bash
cd templates/dev
./generate.sh
```

3. **Vérifier les résultats** dans `storage/dev/`

## 📊 Monitoring

### Logs de Génération

Les scripts de génération fournissent des logs détaillés :
- Nombre de variables chargées
- Fichiers traités et copiés
- Erreurs de résolution des variables

### Validation

- Vérification automatique des variables non résolues
- Protection contre les dépendances circulaires
- Validation des chemins et permissions

## 🔄 Intégration avec l'API

L'API 4NK Vault lit uniquement les fichiers dans `storage/<env>/` et ne traite plus les variables d'environnement. Cette séparation garantit :

- **Performance** : Pas de traitement de variables en temps réel
- **Fiabilité** : Variables pré-résolues et validées
- **Sécurité** : Isolation entre templates et fichiers finaux
- **Maintenabilité** : Workflow de génération automatisé et reproductible