Installer dsoxlab en local avec uv ou pipx

Installer dsoxlab tient en une commande, uv tool install dsoxlab ou pipx install dsoxlab, et ne demande aucun droit d'administration. Cette leçon dit ce que l'outil exige réellement de votre poste, comment lire le diagnostic de dsoxlab doctor sans courir après un composant inutile, et comment garder la CLI à jour. Elle s'adresse à qui travaille sous Linux, ou sous macOS avec Python déjà en place : sous Windows, ou sur un Mac sans Python, la bonne réponse est l'appliance, traitée dans la leçon suivante.

Ce que vous allez apprendre

Vérifier les deux seuls prérequis de la CLI, et savoir ce qui vient avec elle.
Installer dsoxlab avec uv ou pipx, puis confirmer sa version.
Interpréter le diagnostic de dsoxlab doctor et distinguer requis et informatif.
Activer l'auto-complétion pour bash ou zsh.
Mettre à jour l'outil, et régler l'avis quotidien de nouvelle version.

Ce que dsoxlab exige, et ce qu'il apporte

Deux prérequis, et pas un de plus : Python 3.11 ou plus récent, et un installeur d'outils Python, uv ou pipx. Ces deux installeurs posent la CLI dans un environnement isolé, ce qui évite tout conflit avec les paquets Python de votre système. Si vous n'avez ni l'un ni l'autre, uv s'installe en une ligne, sans droit d'administration, en suivant sa documentation d'installation.

Un troisième composant est requis partout sans être une dépendance Python : git, parce que dsoxlab catalog add clone un dépôt. Il est presque toujours déjà présent, et dsoxlab doctor le nomme s'il manque. Deux autres ne deviennent nécessaires que sur certains labs : Docker dès qu'un lab déclare des services en conteneur, Terraform dès qu'un catalogue porte des labs vm. Aucun des deux n'est utile pour commencer.

À l'inverse, deux outils viennent avec la CLI et n'ont jamais à être installés à part : pytest et pytest-testinfra, qui exécutent les tests de validation, et ansible-core, qui joue les playbooks de préparation des labs vm. Un catalogue de labs n'installe donc aucun outillage de test.

Installer et vérifier la version

L'installation pose une commande, dsoxlab, et rien d'autre dans votre système. Choisissez l'installeur que vous avez déjà :

uv tool install dsoxlab      # ou : pipx install dsoxlab
dsoxlab --version

La seconde commande doit afficher dsoxlab 0.2.5, la dernière version publiée au moment où cette leçon est écrite. Si le shell répond command not found, le lanceur est bien posé mais son répertoire n'est pas dans votre PATH : chaque installeur a une commande pour l'y ajouter, uv tool update-shell pour uv et pipx ensurepath pour pipx, à faire suivre d'un nouveau terminal.

Lire le diagnostic de doctor

dsoxlab doctor ne rapporte que ce dont le catalogue courant a besoin, et range ses constats en deux tableaux. Le premier, « requis pour ce dépôt », liste ce qui vous bloque ici ; le second, « informatif », liste les composants dont ce catalogue ne se sert pas. Un hyperviseur absent n'apparaît donc jamais en rouge sur un catalogue fait de labs shell.

dsoxlab doctor

Sur le catalogue de démonstration, le tableau requis porte Python, pytest, le runtime shell, git et le compte de labs détectés, tous verts si l'installation a réussi. Chaque ligne rouge porte en face le geste qui la répare : une commande quand elle existe, une page d'installation quand seul un humain peut décider.

Trois options complètent la commande, et chacune répond à un usage précis :

Option	Ce qu'elle fait
`--fix`	Joue les remèdes sans risque, comme l'installation de libvirt et QEMU par `apt`, le seul gestionnaire de paquets que les remèdes connaissent. Une remédiation qui exige une reconnexion ou un redémarrage reste rouge jusque-là, et le dit.
`--strict`	Traduit le diagnostic en code de sortie, `9` si un contrôle requis échoue, `10` s'il n'a pas pu être mesuré. Sans elle, `doctor` sort toujours en `0` : pour un humain, un diagnostic n'est pas un échec.
`--json`	Rend le même diagnostic sous forme de document machine, avec un jeton stable par contrôle. Incompatible avec `--fix`.

Un contrôle a trois issues, jamais deux : ok, failed, et unknown quand la sonde elle-même n'a pas abouti. Cette troisième valeur ne compte pas dans le verdict affiché, parce qu'on ne peint pas en rouge ce qu'on ignore, mais --strict lui donne son propre code de sortie : un script ne peut rien conclure d'une mesure qui n'a pas eu lieu.

Jouer le lab de démonstration

Rien ne vaut un lab pour confirmer qu'une installation fonctionne. La commande demo installe un catalogue d'un seul lab sous ~/.local/share/dsoxlab/demo et dit quoi faire ensuite. Ce lab tourne en runtime shell : ni machine virtuelle, ni conteneur, donc il fonctionne partout où la CLI fonctionne.

dsoxlab demo
cd ~/.local/share/dsoxlab/demo
dsoxlab course premiers-pas     # la leçon
dsoxlab run premiers-pas        # vous dépose dans le répertoire de travail
dsoxlab challenge premiers-pas  # la mission
dsoxlab check premiers-pas      # les tests, et la note

Comptez cinq minutes. Le déroulé complet, avec le panneau de score et le piège du répertoire de travail, est décrit sur la page d'accueil de la formation.

Activer l'auto-complétion

La complétion évite de retenir les identifiants de labs, qui sont longs. Elle s'installe une fois, pour bash ou zsh, et prend effet au prochain rechargement du shell :

dsoxlab completion install      # écrit la complétion pour le shell courant
dsoxlab completion show         # imprime le script sans rien écrire

Sous zsh, la commande écrit ~/.zfunc/_dsoxlab et ajoute une ligne à ~/.zshrc ; sous bash, ~/.bash_completion.d/dsoxlab et une ligne à ~/.bashrc. L'ancienne commande dsoxlab install fait encore la même chose mais est dépréciée : n'en prenez pas l'habitude.

Choisir la langue

Chaque message de la CLI existe en anglais et en français, et la langue se règle à deux portées. La variable d'environnement vaut le temps d'un appel, le contexte de catalogue vaut durablement :

DSOXLAB_LANG=fr dsoxlab list-labs     # le temps d'un appel
dsoxlab use linux --lang fr           # durablement, pour ce catalogue

La priorité, de la plus forte à la plus faible : DSOXLAB_LANG, puis le fichier de contexte du catalogue, puis le LANG du système, puis en. Un poste en fr_FR.UTF-8 obtient donc le français sans rien régler.

Tenir l'outil à jour

dsoxlab regarde une fois par jour si une version plus récente existe sur PyPI, et le dit en fin de commande, sur la sortie d'erreur pour ne jamais polluer une sortie --json. Hors ligne, il se tait. La mise à jour passe par l'installeur qui a posé l'outil :

uv tool upgrade dsoxlab            # ou : pipx upgrade dsoxlab
DSOXLAB_NO_UPDATE_CHECK=1 dsoxlab list-labs   # couper l'avis, le temps d'un appel

Mettre l'outil à jour avant un catalogue n'est pas une préférence : un fichier de lab écrit pour un contrat plus récent que l'outil est écarté, alors qu'un fichier ancien lu par un outil récent fonctionne toujours. Quand un catalogue annonce une montée de version, l'outil se met à jour en premier.

Dépannage

Les trois cas ci-dessous couvrent l'essentiel de ce qui bloque entre l'installation et le premier lab. Chacun se reconnaît à son symptôme et se règle sans réinstaller.

Symptôme	Cause	Solution
`dsoxlab: command not found` juste après l'installation	Le répertoire des lanceurs de `uv` ou `pipx` n'est pas dans le `PATH`	`uv tool update-shell` ou `pipx ensurepath`, puis ouvrir un nouveau terminal
`dsoxlab catalog add` échoue en nommant `git`	`git` n'est pas installé : la CLI clone les catalogues	Installer `git` avec le gestionnaire de paquets du système, puis relancer `dsoxlab doctor`
`dsoxlab --version` affiche une version plus ancienne que celle annoncée	Un lanceur d'une installation précédente passe avant le nouveau	Retirer `~/.local/bin/dsoxlab` s'il vient d'un ancien `dsoxlab install`, puis `uv tool upgrade dsoxlab`

À retenir

Deux prérequis seulement : Python 3.11 et uv ou pipx ; git doit être présent parce que les catalogues se clonent.
pytest, pytest-testinfra et ansible-core viennent avec la CLI : un catalogue n'installe aucun outillage de test.
dsoxlab doctor sépare le requis de l'informatif ; --fix répare ce qui l'est sans risque, --strict sert aux scripts.
Un contrôle a trois issues, ok, failed et unknown : une sonde qui n'a pas pu mesurer ne conclut jamais au vert.
dsoxlab completion install remplace l'ancien dsoxlab install, déprécié.
On met l'outil à jour avant le catalogue, jamais l'inverse.

Pour aller plus loin

Dimensionner sa machine pour les labs : Ce que chaque catalogue déclare en mémoire, processeurs et disque avant d'installer un hyperviseur.
Les principales commandes de dsoxlab : De catalog add à check, l'ordre dans lequel les commandes s'enchaînent.
Fichiers, variables d'environnement et codes de sortie : Où la CLI écrit sur le disque, et ce que chaque code de sortie appelle comme geste.