Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions CHANGELOG.fr.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,55 @@ et le projet suit le [versionnage sémantique](https://semver.org/lang/fr/).

### Modifié

- **`dsoxlab doctor` guide jusqu'au bout : toutes les étapes qui manquent
d'un coup, dans l'ordre, chaque commande prête à coller.** Deux machines
vides mesurées le 2026-11-16 (Ubuntu 24.04 et AlmaLinux 10) obligeaient à
relancer `doctor` après chaque geste pour découvrir le suivant, et
`provision` échouait encore après un `doctor` vert. Le diagnostic :
- affiche des **étapes numérotées** dans l'ordre des dépendances (git,
provider, libvirt, groupes, pool, firmware EFI, Terraform, Ansible,
collections, clé SSH du catalogue, Include de `~/.ssh/config`), chaque
commande seule sur sa ligne au lieu d'être coupée dans une cellule de
tableau, puis « À savoir », ce qui est prêt, et la commande unique
`dsoxlab doctor --fix` ;
- **ne cache plus aucun contrôle** : sans libvirt, le pool, les groupes et
le firmware restent listés, « faire l'étape N d'abord » ; sans provider
choisi, il diagnostique avec celui qu'il recommande (kvm sur un Linux qui
expose `/dev/kvm`), sans l'enregistrer ;
- **contrôle quatre choses de plus**, qui faisaient échouer `provision` ou
`ssh` : la clé SSH du catalogue, la ligne `Include` de `~/.ssh/config`, le
firmware EFI (issue #381), et les groupes `kvm`/`libvirt`, en distinguant
« reconnectez-vous » de « rejoignez le groupe » ;
- **donne des commandes, plus des liens**, lues dans une table par famille
de distribution (`/etc/os-release`) : git, Terraform et Docker depuis leurs
dépôts officiels, `systemctl enable --now libvirtd` au lieu de `start`, qui
ne survivait pas au redémarrage, et plus de `dnf install incus` sur la
famille RHEL, dont aucun dépôt de base ne l'a ;
- avec `-v`, montre chaque contrôle et les mises en garde des lignes vertes
(un Terraform plus ancien que la dernière version).
- **`doctor --fix` affiche son plan et demande d'abord.** Rien ne part sans
`[y/N]` ou `--yes` ; sans terminal et sans `--yes`, rien ne part (code 1).
Les étapes sans sudo sont lancées par dsoxlab ; celles avec sudo passent
toutes par un seul `ansible-playbook --ask-become-pass -c local`, généré
depuis la même table que l'affichage, qui demande le mot de passe une fois ;
sans terminal, elles s'affichent à coller. Ansible est installé d'abord
(`uv tool install ansible-core`). Chaque étape est revérifiée par un
diagnostic refait, et **le premier échec arrête tout**, en nommant les
étapes restantes : l'ancienne cascade continuait, et créait un pool sans
libvirt. Docker et Incus, quand le catalogue n'en a pas besoin, ne viennent
qu'avec `--clients`.
- **Une mémoire trop petite pour tout le catalogue ne bloque plus.** Elle
passe sous « À savoir » avec `dsoxlab provision --host <machine>`, et dans
`informational` en `--json` : `doctor --strict` ne sort plus en 9 pour elle.
`start <lab>` reste bloquant sur la mémoire qu'exige son propre lab.
- `doctor --json` gagne trois champs par contrôle, sans rien retirer :
`commands` (les lignes à coller), `after` (le contrôle à réparer d'abord) et
`warning`. `fix` ne porte plus les commandes qui exigent un shell
(Terraform, Docker) : lire `commands`. Les codes de sortie ne changent pas.
- La section d'installation de `docs/learner.fr.md` donne les mêmes commandes
que le diagnostic, avec `sudo`, pour Debian/Ubuntu et la famille RHEL ; un
test la tient mot pour mot alignée sur la table.

- **Les machines provisionnées ne démarrent plus avec l'hôte, sauf si le
catalogue le demande** (issue #377). Les templates kvm et incus posaient le
démarrage automatique sur chaque machine, sans moyen d'y échapper : au
Expand Down
47 changes: 47 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- **`dsoxlab doctor` guides you to the end: every missing step at once, in
order, each command ready to paste.** Two empty machines measured on
2026-11-16 (Ubuntu 24.04 and AlmaLinux 10) needed `doctor` to be run again
after each gesture to discover the next one, and `provision` still failed
after a green `doctor`. The diagnosis now:
- prints **numbered steps** in dependency order (git, provider, libvirt,
groups, pool, EFI firmware, Terraform, Ansible, collections, catalogue
SSH key, `~/.ssh/config` Include), each command alone on its line instead
of cut inside a table cell, then « Good to know », what is ready, and the
single command `dsoxlab doctor --fix`;
- **hides no check**: without libvirt, the pool, the groups and the firmware
stay listed, "do step N first"; with no provider chosen, it diagnoses
with the recommended one (kvm on a Linux exposing `/dev/kvm`) without
recording it;
- **checks four new things** that made `provision` or `ssh` fail: the
catalogue SSH key, the `Include` line of `~/.ssh/config`, the EFI firmware
(issue #381), and the `kvm`/`libvirt` groups, telling "log in again" apart
from "join the group";
- **gives commands, not links**, read from one table per distribution family
(`/etc/os-release`): git, Terraform and Docker from their official
repositories, `systemctl enable --now libvirtd` instead of `start`, which
did not survive a reboot, and no `dnf install incus` on the RHEL family,
where no base repository has it;
- with `-v`, shows every check and the warnings on green lines (a Terraform
older than the latest release).
- **`doctor --fix` shows its plan and asks first.** Nothing runs without
`[y/N]` or `--yes`; without a terminal and without `--yes`, nothing runs
(exit 1). Steps without sudo are run by dsoxlab; sudo steps all go through
one `ansible-playbook --ask-become-pass -c local` run, generated from the
same table as the display, which asks for the password once; without a
terminal they are printed to paste. Ansible is installed first
(`uv tool install ansible-core`). Each step is checked again by a fresh
diagnosis, and **the first failure stops everything**, naming the remaining
steps: the old cascade went on, creating a pool without libvirt. Docker and
Incus, when the catalogue does not need them, only come with `--clients`.
- **A memory too small for the whole catalogue no longer blocks.** It moves
to « Good to know » with `dsoxlab provision --host <machine>`, and to
`informational` in `--json`: `doctor --strict` no longer exits 9 for it.
`start <lab>` still blocks on the memory its own lab needs.
- `doctor --json` gains three fields per check, nothing removed: `commands`
(the lines to paste), `after` (the check to repair first) and `warning`.
`fix` no longer carries the commands that need a shell (Terraform, Docker):
read `commands`. Exit codes are unchanged.
- The installation section of `docs/learner.md` gives the same commands as
the diagnosis, with `sudo`, for Debian/Ubuntu and the RHEL family; a test
keeps it word for word in line with the table.

- **Provisioned machines no longer start with the host, unless the catalogue
asks** (issue #377). The kvm and incus templates set autostart on every
machine, with no way out: when a training machine rebooted on 2026-11-16,
Expand Down
130 changes: 107 additions & 23 deletions docs/learner.fr.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,29 +80,113 @@ répare ce qui peut l'être sans risque.
Deux sortes de labs, et seule la première est gratuite. Un lab **`shell`** se
joue dans un répertoire de votre machine : le lab de démonstration en est un,
et tout le catalogue Terraform aussi. Un lab **`vm`** démarre de vraies
machines virtuelles à côté de vous — 66 des 86 labs du catalogue Linux le
font — et votre machine doit donc pouvoir les faire tourner :

- **Linux, avec KVM.** Les hyperviseurs packagés sont KVM/libvirt et Incus, et
aucun des deux n'existe sous Windows ou macOS : là-bas, les labs `vm`
passent par [l'appliance](./appliance.fr.md). Dans une machine virtuelle,
ils réclament en plus la virtualisation imbriquée, qui s'active sur l'hôte
et non dans l'invité.
- **libvirt et QEMU.** `dsoxlab doctor --fix` les installe là où le remède est
un `apt install`, le seul gestionnaire de paquets que les remèdes
connaissent aujourd'hui, et vous ajoute au groupe `kvm` — ce qui prend effet
à votre prochaine connexion.
- **Terraform.** `doctor` le nomme et renvoie à sa page d'installation, mais ne
peut pas l'installer : HashiCorp le distribue par son propre dépôt. Ansible
ne demande rien, il vient avec dsoxlab.
- **Une paire de clés SSH pour le catalogue**, produite par `dsoxlab instructor
bootstrap`. Le mot « instructor » nomme la commande, lancez-la quand même :
un catalogue que vous clonez ne porte aucune clé — son `.gitignore` exclut
tout le répertoire `ssh/`, une clé privée n'ayant rien à faire dans un
dépôt — et `provision` refuse de démarrer sans elle.

Rien de tout cela ne se devine : `dsoxlab doctor` le range entre ce que ce
catalogue exige et ce qui est informatif, et dit quoi faire de chaque ligne.
machines virtuelles à côté de vous, et votre machine doit donc pouvoir les
faire tourner. Il lui faut **Linux avec KVM** : les hyperviseurs packagés sont
KVM/libvirt et Incus, et aucun des deux n'existe sous Windows ou macOS, où les
labs `vm` passent par [l'appliance](./appliance.fr.md). Dans une machine
virtuelle, ils réclament en plus la virtualisation imbriquée, qui s'active sur
l'hôte et non dans l'invité.

Le chemin court : lancez `dsoxlab doctor`. Il liste d'un coup toutes les
étapes qui manquent, numérotées dans l'ordre où les faire, chaque commande
seule sur sa ligne, pour votre distribution (lue dans `/etc/os-release`).
Ensuite, `dsoxlab doctor --fix` affiche le plan et le lance une fois que vous
l'avez confirmé : les étapes sans sudo par dsoxlab lui-même, celles avec sudo
par un seul `ansible-playbook`, qui vous demande votre mot de passe une fois.
Chaque étape est revérifiée juste après, et le premier échec arrête tout.

Les mêmes étapes à la main. Sur **Debian ou Ubuntu** :

```bash
sudo apt install git
sudo apt install libvirt-clients libvirt-daemon-system qemu-kvm
sudo usermod -aG kvm,libvirt $USER
sudo virsh pool-define-as default dir --target /var/lib/libvirt/images
sudo virsh pool-build default
sudo virsh pool-start default
sudo virsh pool-autostart default
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
```

Sur **AlmaLinux, Rocky ou RHEL** (libvirt n'y démarre pas tout seul) :

```bash
sudo dnf install git
sudo dnf install libvirt qemu-kvm
sudo systemctl enable --now libvirtd
sudo usermod -aG kvm,libvirt $USER
sudo virsh pool-define-as default dir --target /var/lib/libvirt/images
sudo virsh pool-build default
sudo virsh pool-start default
sudo virsh pool-autostart default
sudo dnf install -y yum-utils
sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
sudo dnf -y install terraform
```

Fermez ensuite votre session et rouvrez-la : les groupes `kvm` et `libvirt` ne
valent que pour une nouvelle session. Puis, sur toutes les distributions,
depuis le catalogue :

```bash
uv tool install ansible-core
dsoxlab use --provider kvm
ansible-galaxy collection install -r requirements.yml
dsoxlab instructor bootstrap
mkdir -p ~/.ssh && t=$(mktemp) && { echo 'Include ~/.ssh/config.d/*.conf'; cat ~/.ssh/config 2>/dev/null || true; } > "$t" && mv "$t" ~/.ssh/config && chmod 600 ~/.ssh/config
```

Ces commandes installent Ansible (par `uv`, sans sudo), choisissent le
provider, installent les collections Ansible qu'appellent les playbooks du
catalogue, créent la clé SSH du catalogue (le mot « instructor » nomme la
commande, lancez-la quand même : un catalogue que vous clonez ne porte aucune
clé, et `provision` refuse de démarrer sans elle), et font lire à `ssh` les
fichiers que dsoxlab écrit dans `~/.ssh/config.d/`. La dernière marche sur un
`~/.ssh/config` vide ou absent, ce que ne fait pas un `sed -i '1i …'`.

Si `doctor` signale le firmware EFI absent : `sudo apt install ovmf` sur Debian ou
Ubuntu, `sudo dnf install edk2-ovmf` sur la famille RHEL. Il arrive d'habitude avec QEMU.

Une mémoire trop petite pour tout le catalogue ne bloque rien : `doctor` le dit
sous « À savoir », et `dsoxlab provision --host <machine>` ne monte que la
machine du lab que vous jouez.

Docker ne sert qu'aux catalogues dont les labs déclarent des conteneurs ;
`dsoxlab doctor --fix --clients` l'installe, depuis le dépôt de Docker. À la
main, sur Debian ou Ubuntu (remplacez `ubuntu` par `debian` dans les deux URL
sur Debian) :

```bash
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

Sur la famille RHEL :

```bash
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
```

Incus est packagé sur Debian et Ubuntu (`sudo apt install incus`), et dans
aucun dépôt de base de la famille RHEL.

---

Expand Down
Loading