netbian/ARCHITECTURE.md

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.

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

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 :

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() :

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 :

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 :

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

./run.sh --list-profiles

Lister les roles :

./run.sh --list-roles

Validation minimale recommandee :

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.