netbian/README.md

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