first commit

README.md

@@ -0,0 +1,221 @@
+# NETbian
+
+NETbian est un outil de provisioning pour **Debian 13** base sur une architecture **profiles + roles**.
+
+Chaque **profil** compose une suite de **roles fonctionnels**. Un role regroupe au meme endroit :
+
+- ses paquets
+- sa configuration APT eventuelle
+- ses actions d'installation
+- sa configuration systeme
+- ses actions finales eventuelles
+
+Le projet est pense pour rester **idempotent** : un second passage doit converger vers l'etat attendu au lieu de casser la machine.
+
+## Profils disponibles
+
+- `cli`
+- `server`
+- `desktop`
+- `devel`
+
+Les profils sont definis dans `profiles/` et peuvent etre listes avec :
+
+```bash
+./run.sh --list-profiles
+```
+
+## Roles disponibles
+
+Le depot contient actuellement les roles suivants :
+
+- `base`
+- `codium`
+- `desktop`
+- `devel`
+- `docker`
+- `firewall`
+- `server`
+- `zram`
+
+Ils peuvent etre listes avec :
+
+```bash
+./run.sh --list-roles
+```
+
+## Structure du depot
+
+```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/
+```
+
+## Convention d'un role
+
+Un role peut contenir les fichiers suivants :
+
+- `packages.list` : paquets du role
+- `repo.sh` : ajout de depots / cles APT
+- `install.sh` : installation specifique
+- `config.sh` : configuration systeme
+- `run.sh` : actions finales du role
+- `l10n.packages` : mappings de paquets localises
+- `rules.<suffix>.list` : regles declaratives UFW pour le role firewall
+
+Tous ces fichiers sont **optionnels**. Le moteur execute uniquement ceux qui existent.
+
+## Profils fournis
+
+### `cli`
+
+Provisioning minimal en ligne de commande :
+
+```bash
+ROLE_ORDER=(base zram)
+```
+
+### `server`
+
+Machine orientee services :
+
+```bash
+ROLE_ORDER=(base firewall server zram docker)
+```
+
+### `desktop`
+
+Poste utilisateur graphique :
+
+```bash
+ROLE_ORDER=(base desktop firewall zram)
+```
+
+### `devel`
+
+Poste de developpement :
+
+```bash
+ROLE_ORDER=(base desktop firewall zram docker codium devel)
+```
+
+## Installation
+
+```bash
+git clone https://git.netig.net/netig/netbian.git
+cd netbian
+sudo ./run.sh --profile devel
+```
+
+## Utilisation
+
+```text
+Usage: run.sh [options]
+Options:
+  -p, --profile <server|desktop|devel|cli>   Profile to install (required)
+  -l, --lang <code>                          Language code if translations are needed (e.g. fr, es, de)
+      --config <path>                        Config file path (default: /etc/netbian.conf)
+      --list-profiles                        List available profiles and exit
+      --list-roles                           List available roles and exit
+  -h, --help                                 Show this help
+```
+
+Exemples :
+
+```bash
+sudo ./run.sh --profile server
+sudo ./run.sh --profile devel --lang fr
+sudo ./run.sh --config /root/netbian.conf --profile desktop
+NETBIAN_PROFILE=server sudo -E ./run.sh
+./run.sh --list-profiles
+./run.sh --list-roles
+```
+
+## Configuration
+
+`run.sh` lit et met a jour un fichier de configuration shell simple, par defaut :
+
+```text
+/etc/netbian.conf
+```
+
+Variables gerees actuellement :
+
+```bash
+profile=devel
+lang=fr
+```
+
+Priorite de resolution :
+
+1. options CLI (`--profile`, `--lang`, `--config`)
+2. variables d'environnement (`NETBIAN_PROFILE`, `NETBIAN_LANG`, `NETBIAN_CONFIG_FILE`)
+3. fichier de configuration cible
+4. absence de valeur -> erreur si `profile` reste non defini
+
+Le meme chemin de configuration est ensuite reutilise par `roles.sh`.
+
+## Logs d'execution
+
+NETbian utilise des logs simples pour le moteur d'orchestration :
+
+- `[RUN]` : etape lancee
+- `[OK]` : etape executee avec succes
+- `[SKIP]` : etat deja conforme ou etape vide
+- `[INFO]` : information de progression
+- `[WARN]` : situation non bloquante
+
+Les scripts de roles peuvent aussi ecrire leurs propres messages metier, mais la recommandation est d'utiliser les helpers centralises pour garder des traces homogenes.
+
+## Choix d'architecture pour un niveau infra mature
+
+- **Firewall centralise** : seules les listes `roles/firewall/rules.*.list` definissent les ouvertures UFW.
+- **Validation stricte** : les roles, manifests et le fichier de configuration sont verifies avant execution.
+- **Resume de run** : `roles.sh` imprime un recapitulatif des roles, etapes executees, sautees et en echec.
+- **Precedence explicite** : la resolution de la configuration est documentee et stable.
+
+## Particularites importantes
+
+- `run.sh` exige les droits `root`.
+- Le projet verifie qu'il tourne sur **Debian 13**.
+- Un test reseau HTTP est effectue avant provisioning en utilisant `curl` puis `wget`.
+- Le role `firewall` applique des regles `ufw` a partir de fichiers declaratifs.
+- Le role `server` ecrit une configuration SSH dediee puis tente de recharger `ssh` / `sshd` si le service existe.
+- Le role `codium` installe VSCodium, ses extensions et la configuration utilisateur si un utilisateur cible est detecte.
+- Les paquets localises eventuels sont ajoutes a partir de la variable `lang` de la configuration active.
+
+## Validation rapide
+
+Avant livraison, au minimum :
+
+```bash
+bash -n run.sh roles.sh lib.sh roles/*/*.sh profiles/*.sh
+./run.sh --list-profiles
+./run.sh --list-roles
+```
+
+Pour une validation production complete, il reste recommande de tester le provisioning sur une **Debian 13 fraiche** pour verifier le comportement reel des roles et des services.
+
+
+## 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.