gilles/system_update
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: roadmap tâches 1.9-8 (briefs, gates de validation, designs tâche 2) + plans d'implémentation

Browse Source 
Cartographie complète (liste_taches/coherence_taches), briefs tacheN + gates
validation_tacheN, design tâche 2 (docs/design/tache2/), specs/plans jalon 1-2
et tâche 1.9/2 (Phase 1, Phase 2, SJ-0→3). Validations consignées (1.9 ✅, 2-8 🟡).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
gilles soulier
2026-06-05 19:50:25 +02:00
parent f9ce991ec5
commit 0fbca06d3d
39 changed files with 11916 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tache4.md
+910
View File
@@ -0,0 +1,910 @@
# Consigne de dev — Amélioration des scripts, profils post-install et installateurs
> **Type** : mission d'**investigation + design scripts + contrats JSON** (PAS d'implémentation).
> **Langue** : français.
> **Livrable final attendu** : spec prête à passer en plan d'implémentation.
---
## 0. Contexte
Cette tâche regroupe tout ce qui concerne l'amélioration des scripts d'installation, post-install, configuration système, outils, profils réutilisables et installateurs externes.
Principe non négociable :
> Chaque action ou interrogation sur un hôte doit produire un échange JSON clair entre la machine et la webapp.
Les scripts peuvent streamer du log vers le terminal, mais l'état métier consommé par la webapp, Hermes et MCP doit être un JSON canonique.
À lire avant de travailler :
- `CLAUDE.md`
- `deep-research-report(7).md`
- `tache2.md`
- `validation_tache2.md`
- `templates/apt/*.tpl`
- `server/ssh/client.ts`
- `server/templates/render.ts`
- `shared/types.ts`
---
## 1. Objectif
Concevoir un système de scripts post-install et d'installateurs réutilisables pour préparer des machines Debian/Ubuntu/Proxmox/Raspberry Pi OS après ajout dans la webapp.
Cas concret prioritaire :
- VM Debian 13 installée via netinstall CLI ;
- IP initiale via DHCP ;
- connexion SSH sur l'IP DHCP ;
- élévation root ou sudo ;
- installation de prérequis ;
- changement éventuel hostname/domaine `.home` ;
- configuration IP statique ;
- reboot vérifié ;
- installation de groupes de paquets ;
- installation Docker officiel ;
- installation d'outils optionnels ;
- personnalisation terminal.
---
## 2. Modèle général des scripts
Un script ne doit jamais poser de questions interactives pendant l'exécution SSH.
Toute variable nécessaire est demandée par la webapp avant exécution :
- champs texte ;
- select ;
- multi-select ;
- checkbox/toggle ;
- IP/CIDR ;
- chemin ;
- utilisateur ;
- confirmation de risque.
Chaque script ou profil fournit un manifeste :
```json
{
"id": "identity_network",
"label": "Hostname + IP statique",
"description": "Configure le hostname, le domaine et l'IP statique de la machine.",
"category": "post_install",
"risk": "network_change",
"requiresConfirmation": true,
"fields": [],
"defaults": {},
"validations": [],
"steps": [],
"expectedJsonResult": "postInstall"
}
```
Cycle recommandé d'un installateur :
```text
precheck
→ install
→ configure
→ initialize
→ verify
→ report JSON
```
Le JSON de retour doit détailler chaque étape :
```json
{
"action": "install_recipe",
"recipeId": "docker_official_debian",
"status": "ok",
"steps": [
{ "id": "precheck", "status": "ok" },
{ "id": "install", "status": "ok" },
{ "id": "configure", "status": "ok" },
{ "id": "initialize", "status": "ok" },
{ "id": "verify", "status": "ok" }
],
"requiresRelogin": true,
"requiresReboot": true,
"errors": []
}
```
---
## 3. Profils post-install prioritaires
### `bootstrap_root`
Préparation minimale :
- `sudo`
- `resolvconf`
- `ca-certificates`
- `curl`
- ajout utilisateur au groupe `sudo`
- vérification sudo.
### `identity_network`
Configuration identité/réseau :
- hostname ;
- domaine/search `.home` ;
- `/etc/hosts` ;
- `/etc/network/interfaces` ;
- IP statique `10.0.x.y/22` ;
- gateway `10.0.0.1` ;
- DNS `10.0.0.1`, `10.0.0.10` ;
- reconnexion sur nouvelle IP ;
- reboot vérifié si nécessaire.
Variables :
```json
{
"newHostname": "debian-docker-01",
"domain": "home",
"interfaceName": "ens18",
"staticAddress": "10.0.4.25/22",
"gateway": "10.0.0.1",
"dnsNameservers": ["10.0.0.1", "10.0.0.10"],
"reconnectHost": "10.0.4.25"
}
```
### `base_tools`
Paquets de base, sans `vim` :
- `nano`
- `less`
- `bash-completion`
- `tmux`
- `screen`
- `htop`
- `iotop`
- `ncdu`
- `tree`
- `rsync`
- `unzip`
- `zip`
- `tar`
### `machine_probe`
Détection OS, virtualisation, matériel et capacités.
Ce script doit être proposé juste après l'ajout machine et relançable depuis les paramètres machine.
Commandes/outils possibles :
- `/etc/os-release`
- `uname -a`
- `dpkg --print-architecture`
- `systemd-detect-virt`
- `hostnamectl`
- `lscpu`
- `lsblk`
- `findmnt`
- `lspci` via `pciutils`
- `lsusb` via `usbutils`
- `dmidecode` seulement si utile et disponible ;
- `/proc/cpuinfo` pour Raspberry Pi ;
- `pveversion` et `pvesh` si Proxmox ;
- état `qemu-guest-agent`/guest tools si VM.
JSON attendu :
```json
{
"action": "machine_probe",
"status": "ok",
"os": {
"family": "debian",
"version": "13",
"codename": "trixie",
"arch": "amd64"
},
"machine": {
"kind": "vm",
"virtualization": "qemu",
"hypervisor": "kvm",
"raspberryPi": false,
"proxmoxHost": false
},
"hardware": {
"cpuModel": "Intel...",
"cpuCores": 4,
"memoryBytes": 4294967296,
"gpus": [],
"disks": []
},
"recommendations": [
{
"profileId": "vm_guest_tools",
"reason": "QEMU/KVM détecté"
}
]
}
```
Le résultat met à jour le profil OS/type machine proposé dans l'UI, mais l'utilisateur doit pouvoir corriger manuellement.
### `machine_metrics_simple`
Remontée légère CPU/RAM/disque pour tuiles, footer et Hermes.
Commandes possibles :
- charge CPU : `/proc/loadavg`, `uptime`, `nproc` ;
- mémoire : `free -b` ou `/proc/meminfo` ;
- disque : `df -h` et `df -B1` ;
- inodes : `df -i` ;
- uptime : `/proc/uptime` ;
- température optionnelle : `sensors` si installé, Raspberry Pi via `vcgencmd` si disponible.
JSON attendu :
```json
{
"action": "machine_metrics_simple",
"status": "ok",
"collectedAt": "ISO",
"cpu": {
"load1": 0.08,
"load5": 0.12,
"cores": 4
},
"memory": {
"totalBytes": 4294967296,
"usedBytes": 1123456789,
"availableBytes": 2987654321
},
"filesystems": [
{
"mount": "/",
"fstype": "ext4",
"sizeBytes": 32100000000,
"usedBytes": 9300000000,
"usedPercent": 29
}
],
"warnings": []
}
```
Ce script doit être non destructif, rapide, lançable en tâche planifiée, et ne doit pas nécessiter d'installation lourde.
### `apt_repositories`
Analyse et configuration contrôlée des dépôts selon OS.
Besoins :
- Debian : vérifier `main`, `contrib`, `non-free`, `non-free-firmware` selon les profils firmware/drivers ;
- Ubuntu : vérifier `main`, `universe`, `restricted`, `multiverse` selon besoins drivers ;
- Proxmox : vérifier dépôts PVE enterprise/no-subscription, dépôts Debian compatibles, warnings si repo absent/incohérent ;
- Raspberry Pi OS : vérifier dépôts Raspberry Pi OS et Debian associés, sans remplacer par une Debian générique.
Le script doit d'abord produire une analyse, puis proposer une action séparée et validée pour modifier les dépôts.
### `firmware_tools`
Profil machine physique/portable/serveur.
Paquets et outils possibles selon OS :
- `fwupd`
- `pciutils`
- `usbutils`
- `dmidecode`
- `lshw`
- `lm-sensors`
- `smartmontools`
- firmwares Debian selon matériel détecté.
Règles :
- jamais installer du firmware propriétaire sans profil/repo compatible et validation ;
- sur VM, proposer seulement si passthrough ou matériel réel détecté ;
- sur Proxmox bare-metal, tenir compte des recommandations firmware host.
### `gpu_drivers`
Installation/diagnostic GPU par constructeur.
Sous-profils :
- `gpu_nvidia`
- `gpu_amd`
- `gpu_intel`
- `gpu_intel_arc`
Principe :
- première étape obligatoire : `machine_probe` + détection GPU ;
- deuxième étape : analyse repos/paquets disponibles ;
- troisième étape : proposition d'installation selon OS.
Contraintes :
- Debian : les drivers/firmwares peuvent nécessiter `contrib`, `non-free`, `non-free-firmware` ;
- Ubuntu : utiliser `ubuntu-drivers` quand disponible pour recommander les pilotes NVIDIA/GPU ;
- AMD/Intel : privilégier le stack kernel/Mesa/firmware de la distribution avant scripts externes ;
- Intel Arc : vérifier kernel/firmware/Mesa suffisamment récents avant installation ;
- Proxmox : drivers GPU seulement si besoin host/passthrough/transcodage, jamais par défaut ;
- VM : ne pas proposer sauf GPU passthrough détecté.
### `benchmark_tools`
Outils de test et benchmark, optionnels et jamais installés par défaut.
Catégories :
- CPU : `sysbench`, `stress-ng` ;
- disque : `fio`, `hdparm` en lecture contrôlée ;
- réseau : `iperf3` ;
- monitoring ponctuel : `sysstat` selon disponibilité ;
- hardware : `hardinfo` seulement si pertinent avec interface graphique, sinon éviter.
Règles :
- les benchmarks peuvent charger la machine : confirmation explicite ;
- pas de test disque destructif ;
- rapport JSON avec commande, durée, score, erreurs ;
- utile surtout pour machine physique, Proxmox host, serveur media ou dev.
### `network_tools`
- `iproute2`
- `iputils-ping`
- `dnsutils`
- `traceroute`
- `net-tools` optionnel
- `tcpdump`
- `nmap`
- `mtr-tiny`
- `lsof`
- `netcat-openbsd`
`nmap` est ici classé comme **outil réseau d'administration** pour découverte locale, diagnostic et inventaire contrôlé. Les usages plus intrusifs ou offensifs relèvent du profil `security_lab`, jamais installé par défaut.
### `dev_git`
- `git`
- `curl`
- `wget`
- `jq`
- `yq`
- `gnupg`
- `lsb-release`
- `build-essential` optionnel.
### `sharing`
Partage réseau :
- Samba ;
- NFS ;
- mDNS/Avahi ;
- `wsdd2`.
Sous-profils :
- `sharing_samba`
- `sharing_nfs`
- `sharing_mdns`
- `sharing_wsdd2`
### `docker_official`
Installation Docker via documentation officielle Debian :
- ajout clé GPG officielle dans `/etc/apt/keyrings` ;
- fichier `docker.sources` ;
- `docker-ce`
- `docker-ce-cli`
- `containerd.io`
- `docker-buildx-plugin`
- `docker-compose-plugin`
- `usermod -aG docker <user>`
- création dossier `/home/gilles/docker` ou variable ;
- enable/start service ;
- verify `docker version` + `docker compose version`;
- reboot ou relogin selon besoin.
Docker doit être modélisé comme **installateur externe officiel**, pas comme simple groupe de paquets Debian.
---
## 4. Profils additionnels à prévoir
### `home_automation`
- `mosquitto`
- `mosquitto-clients`
- `bluetooth`
- `bluez`
- `avahi-daemon`
- `dbus`
- `jq`
- `curl`
- `socat`
- `ser2net`
- Zigbee2MQTT via script externe optionnel.
### `dev_tools`
Paquets Debian :
- `git`
- `build-essential`
- `pkg-config`
- `cmake`
- `python3`
- `python3-venv`
- `python3-pip`
- `pipx`
Installateurs externes optionnels :
- Python `uv`
- Rust via `rustup`
- Node.js via `nvm` ou NodeSource
- npm récent si besoin.
### `embedded_esp_platformio`
- `python3-venv`
- `pipx`
- PlatformIO via `pipx` ou script validé ;
- `esptool`
- `openocd`
- `avrdude`
- `dfu-util`
- `cmake`
- `ninja-build`
- `build-essential`
- ajout utilisateur aux groupes `dialout`, `plugdev`;
- règles udev ESP/USB si nécessaires ;
- relogin/reboot requis.
### `dev_ide`
Profil desktop optionnel :
- VS Code ou VSCodium ;
- CLI `code` ;
- extensions optionnelles Python, C/C++, PlatformIO, ESP-IDF.
### `storage_health`
- `smartmontools`
- `nvme-cli`
- `hdparm`
- `sdparm`
- `lsscsi`
- `sg3-utils`
- `parted`
- `gdisk`
- `fio`
### `media_tools`
- `ffmpeg`
- `mediainfo`
- `imagemagick`
- `mpv` optionnel
- `vlc` optionnel, surtout desktop
- `alsa-utils`
- `pipewire-utils` ou `pulseaudio-utils` selon système.
### `security_audit`
Pour audit légitime :
- `nmap`
- `whois`
- `dnsutils`
- `tcpdump`
- `tshark`
- `lynis`
- `testssl.sh` via script externe optionnel.
### `security_lab`
Profil high-risk, jamais par défaut :
- `nmap`
- `masscan`
- `hydra`
- `john`
- `hashcat`
- `gobuster`
- `dirsearch`
- `sqlmap`
- `metasploit-framework`
- wordlists.
L'UI doit afficher un avertissement clair : usage uniquement sur systèmes autorisés/lab.
Distinction attendue dans la spec :
- `network_tools/nmap` : scan simple et local, ex. port SSH `22`, inventaire de machines autorisées.
- `security_audit/nmap` : audit défensif, réseau appartenant à l'utilisateur.
- `security_lab/nmap` : scénarios offensifs/lab, high-risk, confirmation explicite, jamais inclus dans une installation standard.
### `backup_sync`
- `restic`
- `borgbackup`
- `rclone`
- `rsync`
- `syncthing`
- `duplicity`
### `monitoring`
- `prometheus-node-exporter`
- `lm-sensors`
- `smartmontools`
- `collectd`
- Netdata via script externe optionnel.
### `network_services`
- `nginx`
- `caddy`
- `certbot`
- `wireguard-tools`
- Tailscale via script externe optionnel
- `openssh-server`
- `fail2ban`
### `vm_guest_tools`
- `qemu-guest-agent`
- `open-vm-tools`
- choix selon hyperviseur.
---
## 5. Scripts de partage — exemples attendus
### Samba
Variables UI :
```json
{
"shareName": "docker-share",
"path": "/home/gilles/docker",
"validUsers": ["gilles"],
"forceGroup": "gilles",
"readOnly": false,
"browseable": true,
"createDirectory": true,
"enableMdns": true,
"enableWsdd2": true
}
```
Retour JSON :
```json
{
"action": "post_install_sharing_samba",
"status": "ok",
"changed": true,
"packagesInstalled": ["samba", "avahi-daemon", "libnss-mdns", "wsdd2"],
"filesChanged": ["/etc/samba/smb.conf"],
"directoriesCreated": ["/home/gilles/docker"],
"services": [
{ "name": "smbd", "enabled": true, "active": true },
{ "name": "nmbd", "enabled": true, "active": true },
{ "name": "avahi-daemon", "enabled": true, "active": true },
{ "name": "wsdd2", "enabled": true, "active": true }
],
"errors": []
}
```
### NFS
Variables UI :
```json
{
"exportName": "docker-nfs",
"path": "/home/gilles/docker",
"allowedNetwork": "10.0.0.0/22",
"access": "rw",
"syncMode": "sync",
"rootSquash": true,
"createDirectory": true
}
```
Retour JSON :
```json
{
"action": "post_install_sharing_nfs",
"status": "ok",
"changed": true,
"packagesInstalled": ["nfs-kernel-server"],
"filesChanged": ["/etc/exports"],
"exports": [
{
"path": "/home/gilles/docker",
"allowedNetwork": "10.0.0.0/22",
"options": ["rw", "sync", "root_squash"]
}
],
"services": [
{ "name": "nfs-kernel-server", "enabled": true, "active": true }
],
"errors": []
}
```
---
## 6. Installateurs externes réutilisables
Créer une spec pour une section paramètres webapp :
```text
Paramètres
└─ Scripts d’installation
├─ Docker officiel Debian
├─ Rust via rustup
├─ Node.js via nvm / NodeSource
├─ Python uv
├─ PlatformIO / ESP
├─ Personnalisation terminal
├─ Zigbee2MQTT
└─ Script perso
```
Chaque installateur doit être :
- versionné sur disque ;
- rendu via Mustache ;
- prévisualisable ;
- validé par formulaire ;
- journalisé ;
- traçable dans un rapport ;
- accompagné d'un JSON résultat ;
- non interactif ;
- sans secret en clair.
Règles de sécurité :
- pas de `curl | sh` opaque sans justification ;
- URL officielle documentée ;
- checksum/signature si disponible ;
- confirmation obligatoire ;
- rollback ou sauvegarde quand un fichier système est modifié ;
- erreur structurée si une décision manque.
---
## 7. Initialisation complémentaire des outils
Prévoir que certains installateurs nécessitent des commandes après installation.
Chaque recette doit pouvoir déclarer :
- `precheck`
- `install`
- `configure`
- `initialize`
- `verify`
- `postNotes`
Exemples :
- Docker : enable service, usermod docker, créer dossier Compose, vérifier `docker compose`.
- Rust : installer toolchain, vérifier `cargo`, ajouter PATH utilisateur.
- Node : installer nvm/NodeSource, vérifier `node`, `npm`, `corepack`.
- PlatformIO : installer via pipx, vérifier `pio`, ajouter user à `dialout`.
- Samba : écrire partage, `testparm`, restart service, vérifier service actif.
- NFS : écrire exports, `exportfs -ra`, vérifier exports.
---
## 8. Personnalisation terminal
Créer un profil `terminal_customization`.
Fonctions :
- MOTD ;
- message d'accueil SSH ;
- prompt bash ;
- couleurs/style ;
- aliases ;
- affichage hostname ;
- affichage IP ;
- affichage branche Git ;
- bannière maintenance ;
- configuration par utilisateur.
Variables UI :
```json
{
"targetUser": "gilles",
"theme": "gruvbox",
"showHostname": true,
"showIp": true,
"showGitBranch": true,
"enableMotd": true,
"welcomeMessage": "Bienvenue sur {{hostname}}",
"aliases": ["ll", "la", "update", "dps", "dcu"]
}
```
Retour JSON :
```json
{
"action": "post_install_terminal_customization",
"status": "ok",
"changed": true,
"targetUser": "gilles",
"filesChanged": [
"/home/gilles/.bashrc",
"/etc/update-motd.d/99-system-update"
],
"backupFiles": [
"/home/gilles/.bashrc.su-backup-{{backupDate}}"
],
"verify": {
"bashrcSyntax": "ok",
"motdScriptExecutable": true
},
"errors": []
}
```
---
## 9. JSON canonique
Tout script doit produire un résultat structuré.
Champs communs :
```json
{
"action": "post_install_profile",
"profileId": "base_tools",
"status": "ok",
"startedAt": "ISO",
"finishedAt": "ISO",
"changed": true,
"steps": [],
"packagesInstalled": [],
"filesChanged": [],
"services": [],
"requiresReboot": false,
"requiresRelogin": false,
"errors": []
}
```
Le log brut reste archivé. Hermes/MCP ne reçoivent que le JSON réduit et les lignes importantes.
---
## 10. Erreurs à prévoir
Taxonomie minimale :
- `missing_required_input`
- `unsupported_os`
- `unsupported_architecture`
- `network_unreachable`
- `apt_update_failed`
- `package_install_failed`
- `external_download_failed`
- `signature_verification_failed`
- `service_enable_failed`
- `service_start_failed`
- `verify_failed`
- `network_config_invalid`
- `reconnect_failed`
- `user_not_found`
- `permission_denied`
- `human_interaction_required`
- `timeout`
Aucune auto-réparation dangereuse sans validation explicite.
---
## 11. Livrables attendus
À produire sous `docs/` :
1. Catalogue complet des profils post-install.
2. Manifeste type d'un profil/script.
3. Modèle de recette `precheck/install/configure/initialize/verify`.
4. Spec des installateurs externes réutilisables.
5. Spec des scripts réseau, partage Samba/NFS/wsdd2.
6. Spec Docker officiel.
7. Spec détection machine/hardware, métriques simples, firmware, drivers GPU et benchmark.
8. Spec dev tools, embedded ESP/PlatformIO, terminal customization.
9. JSON canoniques d'entrée/sortie.
10. Taxonomie d'erreurs.
11. Découpage en sous-jalons.
---
## 12. Définition de terminé
- Les profils sont classés et optionnels.
- Docker est traité comme installateur externe officiel.
- Les scripts nécessitant des champs UI sont modélisés.
- Les scripts tiennent compte du couple OS/type machine.
- La détection hardware et les métriques simples sont prévues.
- Les drivers/firmware/benchmark restent optionnels et validés explicitement.
- Les étapes complémentaires d'initialisation sont prévues.
- Les retours JSON sont spécifiés.
- Les secrets sont exclus des logs/UI/MCP.
- Aucun code de production n'est livré pendant cette mission de design.
---
## 13. Technos à utiliser — checklist
- [ ] Bash templates versionnés sur disque.
- [ ] Mustache pour variables de scripts.
- [ ] JSON canonique en sortie de chaque script.
- [ ] `apt-get` non interactif pour paquets Debian/Ubuntu.
- [ ] Docker Engine dépôt officiel pour Docker.
- [ ] `systemd`/services pour enable/start/verify quand disponible.
- [ ] `systemd-detect-virt`, `/etc/os-release`, `lspci`, `lsusb`, `lsblk`, `df`, `free` pour détection.
- [ ] `qemu-guest-agent` / `open-vm-tools` selon VM.
- [ ] `smartmontools`, `lm-sensors`, `fwupd` optionnels pour physique.
- [ ] `ubuntu-drivers` pour recommandations GPU Ubuntu.
- [ ] `rustup`, `nvm`/NodeSource, `uv`, `pipx`, PlatformIO selon profils dev.
- [ ] Aucune commande interactive pendant SSH.
## 14. URLs utiles
- Docker Engine Debian : https://docs.docker.com/engine/install/debian/
- Docker Compose plugin Linux : https://docs.docker.com/compose/install/linux/
- Debian NetworkConfiguration : https://wiki.debian.org/NetworkConfiguration
- Debian Handbook network config : https://www.debian.org/doc/manuals/debian-handbook/sect.network-config
- Samba documentation : https://www.samba.org/samba/docs/
- Debian NFS server wiki : https://wiki.debian.org/NFSServerSetup
- Avahi : https://www.avahi.org/
- Rustup : https://rustup.rs/
- NodeSource distributions : https://github.com/nodesource/distributions
- nvm : https://github.com/nvm-sh/nvm
- uv : https://docs.astral.sh/uv/
- pipx : https://pipx.pypa.io/
- PlatformIO : https://docs.platformio.org/
- Ubuntu NVIDIA drivers : https://ubuntu.com/server/docs/nvidia-drivers-installation
- fwupd : https://fwupd.org/
- smartmontools : https://www.smartmontools.org/
## 15. Liens parent/enfant avec les autres tâches
- Parents :
- `tache2.md` pour moteur templates et sécurité scripts.
- `tache1.9.md` pour stockage profils/recettes/versions.
- Enfants :
- `tache5.md` pour exécution, stockage résultats, API.
- `tache3.md` pour formulaires de profils et paramètres.
- `tache6.md` pour analyse Hermes des erreurs scripts.
- `tache7.md` pour métriques simples, sécurité secrets, nettoyage.
- Validation : `validation_tache4.md`.