# Architecture NETbian

Ce document decrit l'architecture actuelle de NETbian et le pipeline d'execution du provisioning.

## Vue d'ensemble

NETbian repose sur une architecture **profiles + roles**.

```text
profile -> liste ordonnee de roles
role    -> implementation technique autonome
```

Un profil ne contient que de la composition. Toute la logique technique est portee par les roles et par les fonctions partagees de `lib.sh`.

## Arborescence

```text
netbian/
├── run.sh
├── roles.sh
├── lib.sh
├── profiles/
│   ├── cli.sh
│   ├── desktop.sh
│   ├── devel.sh
│   └── server.sh
├── roles/
│   ├── base/
│   ├── codium/
│   ├── desktop/
│   ├── devel/
│   ├── docker/
│   ├── firewall/
│   ├── server/
│   └── zram/
└── config/
```

## Profils

Chaque profil est un script shell qui declare `ROLE_ORDER`.

Exemple avec `profiles/devel.sh` :

```bash
ROLE_ORDER=(base desktop firewall zram docker codium devel)
```

Profils fournis :

- `cli` -> `base zram`
- `server` -> `base firewall server zram docker`
- `desktop` -> `base desktop firewall zram`
- `devel` -> `base desktop firewall zram docker codium devel`

## Contrat d'un role

Un role est un repertoire sous `roles/<nom>/`.

Fichiers reconnus par le moteur :

- `repo.sh`
- `packages.list`
- `install.sh`
- `config.sh`
- `run.sh`
- `l10n.packages`
- `rules.<suffix>.list`

Tout autre fichier est rejete par `validate_role()` pour eviter les derives silencieuses.

## Pipeline global

### 1. `run.sh`

`run.sh` est le point d'entree. Il :

1. initialise l'environnement (`PROJECT_DIR`, `ROLE_DIR`, `PROFILE_DIR`)
2. charge `lib.sh` et active `set -Eeuo pipefail`
3. parse les options CLI
4. peut lister les profils et roles disponibles
5. verifie les prerequis (`root`, Debian 13, reseau HTTP)
6. valide puis lit / met a jour le fichier de configuration
7. exporte `CONFIG_FILE`
8. execute `roles.sh`

### 2. `roles.sh`

`roles.sh` :

1. charge `lib.sh`
2. valide `CONFIG_FILE`
3. lit `CONFIG_FILE`
4. recupere `profile`
5. source `profiles/<profile>.sh`
6. valide la definition du profil et les roles references
7. execute `run_role` pour chaque role dans l'ordre
8. imprime un resume d'execution en sortie

## Resolution de configuration

Ordre de priorite :

1. options CLI
2. variables d'environnement `NETBIAN_*`
3. fichier de configuration cible

Variables gerees :

- `profile`
- `lang`
- `CONFIG_FILE` (transportee par l'environnement entre `run.sh` et `roles.sh`)

`validate_config_file()` refuse les lignes invalides et controle les formats de `profile` et `lang` avant sourcing.

## Pipeline d'un role

Le moteur execute les etapes suivantes dans cet ordre :

1. `repo.sh`
2. `packages.list`
3. `install.sh`
4. `config.sh`
5. `run.sh`

Toutes les etapes sont optionnelles.

Implementation logique de `run_role()` :

```text
validate_role
run_role_script repo.sh
load_role_packages
append_localized_packages
run_role_packages
run_role_script install.sh
run_role_script config.sh
run_role_script run.sh
```

Les erreurs sont propagees explicitement avec `|| return 1` pour eviter de dependre uniquement du comportement implicite de `set -e`.

## Gestion des paquets

- `load_role_packages()` charge `roles/<role>/packages.list`
- `append_localized_packages()` enrichit la liste avec les paquets localises definis dans `roles/base/l10n.packages`
- la langue utilisee provient de la configuration active (`lang`)
- `run_role_packages()` appelle `ensure_packages_installed()`

Si un role n'a aucun paquet a installer, le moteur enregistre un `[SKIP]` sur `role/packages.list`.

## Configuration et copie de fichiers

`copy_config()` copie les fichiers depuis `config/` vers leur destination finale :

- propriete `root:root` pour les fichiers systeme
- propriete utilisateur si la destination est sous `/home/<user>/`
- ecriture idempotente si le contenu est identique

`write_if_changed()` et `write_text_file_if_changed()` centralisent les ecritures atomiques simples.

## Firewall declaratif

Le role `firewall` utilise un systeme declaratif base sur des listes de regles :

```text
roles/firewall/
├── rules.common.list
├── rules.desktop.list
├── rules.devel.list
└── rules.server.list
```

Ordre d'application :

1. initialisation UFW
2. regles communes
3. regles specifiques au profil

Chaque ligne correspond a une regle passee a `ufw allow`.

Exemple :

```text
# rules.common.list
ssh

# rules.server.list
http
https
imap
imaps
smtp
submissions
```

Le modele est volontairement unique : les ouvertures UFW sont centralisees dans les fichiers `rules.*.list`, pas dans les autres roles.

## Services systeme

`restart_service_if_present()` permet de redemarrer un service uniquement s'il existe. Cela evite de rendre certains roles fragiles sur des machines ou le service n'est pas installe.

Le role `server` s'appuie sur ce mecanisme apres ecriture de la configuration SSH.

## Logs et resume d'execution

Le moteur expose les helpers suivants :

- `log_run`
- `log_ok`
- `log_skip`
- `log_info`
- `log_warn`

Tags utilises par l'orchestrateur :

- `[RUN]`
- `[OK]`
- `[SKIP]`
- `[INFO]`
- `[WARN]`

Des tableaux runtime suivent les etapes et roles executes, ignores ou en echec :

- `EXECUTED_STEPS`
- `SKIPPED_STEPS`
- `FAILED_STEPS`
- `EXECUTED_ROLES`

Le resume est imprime par `print_execution_summary()` via un `trap EXIT` dans `roles.sh`.

## Decouverte et validation

Lister les profils :

```bash
./run.sh --list-profiles
```

Lister les roles :

```bash
./run.sh --list-roles
```

Validation minimale recommandee :

```bash
bash -n run.sh roles.sh lib.sh roles/*/*.sh profiles/*.sh
./run.sh --list-profiles
./run.sh --list-roles
```

Validation recommandee avant production :

1. machine Debian 13 fraiche
2. test de chaque profil
3. verification des services systemd critiques (`ssh`, `docker`, `zramswap`)
4. verification UFW apres run
5. rerun complet pour confirmer l'idempotence

## Principes de conception

- **Idempotence** : rejouer un role ne doit pas deteriorer l'etat.
- **Composition simple** : les profils ne font qu'ordonner des roles.
- **Validation stricte** : les roles, manifests et fichiers de configuration sont verifies avant execution.
- **Ecritures limitees** : seules les differences utiles sont ecrites.
- **Previsibilite** : les comportements critiques sont centralises dans `lib.sh`.
- **Source de verite unique** : un seul mecanisme par sujet critique (ex. firewall).


## Resume d execution

- `Steps executed` compte les etapes ayant effectue une action.
- `Steps skipped` compte les etapes entierement conformes ou sautees par l'orchestrateur.
- `Skip events` compte tous les messages `[SKIP]` emis pendant l'execution.