system_update/tache4.md

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 :

{
  "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 :

precheck
→ install
→ configure
→ initialize
→ verify
→ report JSON

Le JSON de retour doit détailler chaque étape :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "shareName": "docker-share",
  "path": "/home/gilles/docker",
  "validUsers": ["gilles"],
  "forceGroup": "gilles",
  "readOnly": false,
  "browseable": true,
  "createDirectory": true,
  "enableMdns": true,
  "enableWsdd2": true
}

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

{
  "exportName": "docker-nfs",
  "path": "/home/gilles/docker",
  "allowedNetwork": "10.0.0.0/22",
  "access": "rw",
  "syncMode": "sync",
  "rootSquash": true,
  "createDirectory": true
}

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

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 :

{
  "targetUser": "gilles",
  "theme": "gruvbox",
  "showHostname": true,
  "showIp": true,
  "showGitBranch": true,
  "enableMotd": true,
  "welcomeMessage": "Bienvenue sur {{hostname}}",
  "aliases": ["ll", "la", "update", "dps", "dcu"]
}

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

{
  "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.