Installer et gérer ses catalogues de labs dsoxlab

Un catalogue est un dépôt git de labs, et dsoxlab catalog add le clone sur votre poste puis le rend actif en une commande. Cette leçon s'adresse à qui a joué le lab de démonstration et veut passer aux vrais labs des formations du site. Elle montre comment lister les catalogues que la CLI connaît, en installer un par son nom ou par l'URL de son dépôt, savoir lequel dsoxlab sert quand vous tapez une commande, en changer, le mettre à jour, puis le retirer sans mauvaise surprise sur votre progression. Une seule famille de commandes suffit : dsoxlab catalog.

Ce que vous allez apprendre

• Définir ce qu'est un catalogue de labs et où dsoxlab le range.
• Lister les catalogues connus et ceux qui sont installés.
• Installer un catalogue par son nom ou par l'URL de son dépôt.
• Déterminer quel catalogue dsoxlab sert à un instant donné.
• Changer de catalogue actif avec dsoxlab catalog use.
• Mettre à jour et retirer un catalogue, en mesurant ce qui est perdu.

Prérequis

La leçon Jouer son premier lab dsoxlab avec dsoxlab demo a posé les mots utilisés ici : catalogue, lab, catalogue actif. Il vous faut aussi git, car catalog add clone un dépôt, et une connexion qui atteint GitHub. La leçon Installer dsoxlab en local explique comment vérifier la présence de git avec dsoxlab doctor.

Qu'est-ce qu'un catalogue de labs dsoxlab ?

Un catalogue est un dépôt git qui porte un fichier meta.yml à sa racine, des labs dans un dossier labs/, et la progression de celui qui les joue. Le moteur, la CLI dsoxlab, est publié à part : il ne contient aucun lab, à l'exception de celui de démonstration. Cette séparation permet de mettre à jour la CLI sans toucher à vos labs, et un catalogue par formation : Linux, Ansible, Terraform, Kubernetes et d'autres.

Votre progression, c'est-à-dire vos notes et les indices pris, est écrite dans un fichier .dsoxlab.db à la racine de chaque catalogue. Deux catalogues côte à côte gardent donc des historiques séparés, et supprimer un catalogue supprime son historique avec lui. Cette règle explique plusieurs précautions des commandes plus bas.

Quels catalogues dsoxlab connaît-il par leur nom ?

La CLI embarque un manifeste des catalogues publics, que dsoxlab catalog list affiche avant tout le reste. Ce manifeste ne restreint rien : il facilite la découverte, et catalog add accepte aussi n'importe quelle URL git. Il donne en revanche un identifiant court à chaque catalogue (douze dans la version 0.6.0), linux, ansible, terraform ou kubernetes par exemple, utilisable à la place d'une URL.

dsoxlab catalog list

                               Catalogues connus
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Identifiant    ┃ Description                  ┃ Dépôt                        ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ linux          │ Administration Linux, RHCSA  │ https://github.com/stephrob… │
│                │ et LFCS                      │                              │
│ ansible        │ Ansible, du premier playbook │ https://github.com/stephrob… │
│                │ aux collections              │                              │
│ terraform      │ Terraform et                 │ https://github.com/stephrob… │
│                │ l'infrastructure as code     │                              │
│ kubernetes     │ Kubernetes sur cluster       │ https://github.com/stephrob… │
│                │ kubeadm, pour CKA, CKAD et   │                              │
│                │ CKS                          │                              │
│ devsecops      │ DevSecOps, une application   │ https://github.com/stephrob… │
│                │ durcie version après version │                              │
│ python         │ Python, la construction pas  │ https://github.com/stephrob… │
│                │ à pas d'un outil de sécurité │                              │
│ iam            │ Gestion des identités et des │ https://github.com/stephrob… │
│                │ accès, avec Keycloak et un   │                              │
│                │ annuaire                     │                              │
│ dev-pour-ops   │ Le développement pour les    │ https://github.com/stephrob… │
│                │ Ops, autour d'un outil       │                              │
│                │ hérité                       │                              │
│ cicd           │ Les pipelines CI/CD, sur une │ https://github.com/stephrob… │
│                │ forge locale et sans compte  │                              │
│                │ en ligne                     │                              │
│ cloud          │ Le cloud, pratiqué contre un │ https://github.com/stephrob… │
│                │ émulateur local              │                              │
│ containers     │ Les conteneurs, Docker,      │ https://github.com/stephrob… │
│                │ Compose et Swarm             │                              │
│ github-actions │ GitHub Actions, des          │ https://github.com/stephrob… │
│                │ workflows rejoués en local   │                              │
└────────────────┴──────────────────────────────┴──────────────────────────────┘
Aucun catalogue installé. Installe-en un : dsoxlab catalog add <id>

Le tableau « Catalogues connus » liste l'identifiant, la description et le dépôt de chaque entrée. Un second tableau, « Catalogues installés », n'apparaît que lorsqu'il y en a au moins un ; sinon la commande le dit en une phrase, comme ci-dessus. Pour un script, dsoxlab catalog list --json rend les deux listes dans un document unique, clés known et installed. La page Tous les labs détaille le contenu de ces catalogues, filtrable par compétence et par certification.

Comment installer un catalogue par son nom ou par son URL ?

dsoxlab catalog add <référence> clone le dépôt, vérifie qu'il porte un meta.yml, puis le rend actif. La référence est un identifiant du manifeste ou une URL git commençant par https://, http://, git@, ssh://, git:// ou file://. Le clone est superficiel (--depth 1), donc rapide, et il ne ramène pas l'historique git du catalogue.

dsoxlab catalog add linux

ℹ Installation de linux depuis
https://github.com/stephrobert/linux-dsoxlab-training…
✔ Catalogue « linux » installé dans
/home/alice/.local/share/dsoxlab/catalogs/linux, et rendu actif.
ℹ Il est utilisable depuis n'importe quel répertoire :
  dsoxlab list-labs
  dsoxlab next

Le critère de réussite est la ligne « installé dans … et rendu actif », suivie des deux commandes proposées. Pour un catalogue absent du manifeste, ou pour un dépôt dont vous préférez donner l'adresse, passez son URL : l'identifiant est alors déduit du dernier segment de l'adresse, passé en minuscules et privé de son suffixe .git, et non l'identifiant court du manifeste.

dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training

L'identifiant installé est ici kubernetes-dsoxlab-training, et non kubernetes comme avec dsoxlab catalog add kubernetes. C'est le nom du dossier créé sous catalogs/, et c'est lui qu'il faudra taper dans catalog use, catalog update et catalog remove. Si un catalogue réclame des collections Ansible absentes de votre poste, catalog add le dit juste après l'installation et affiche la commande qui les installe : cet avis ne fait pas échouer l'ajout, et dsoxlab doctor le répétera avant le premier lab.

Relancer catalog add sur un catalogue déjà installé échoue en code 1 sans rien toucher, parce que le dossier porte votre progression. Le message cite deux sorties : catalog update pour le mettre à jour, ou --force pour le réinstaller, en perdant la progression et le travail qui s'y trouvent.

Où le catalogue est-il installé, et lequel dsoxlab sert-il ?

Les catalogues installés vivent sous ~/.local/share/dsoxlab/catalogs/, un sous-dossier par identifiant, et le choix du catalogue servi suit un ordre fixe. Le dossier suit $XDG_DATA_HOME quand elle est définie. Le catalogue actif est retenu à part, dans ~/.local/state/dsoxlab/catalogue-actif ($XDG_STATE_HOME quand elle est définie), un fichier d'une ligne qui porte son identifiant, ou son chemin pour le catalogue de démonstration. Le perdre ne coûte qu'un dsoxlab catalog use, jamais du travail.

Le schéma suit les questions que dsoxlab se pose, dans l'ordre, chaque fois que vous tapez une commande. La première porte sur LAB_HOME, une variable d'environnement qui, si elle est définie, désigne le dossier à servir en priorité. Regardez surtout que le catalogue actif vient après le dossier où vous vous trouvez : c'est volontaire, car quelqu'un qui se place dans un catalogue cloné à la main s'attend à travailler dessus.

Un catalogue actif ne prend jamais le pas sur un dépôt dans lequel vous vous trouvez. Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Cet ordre a une conséquence pratique : depuis n'importe quel dossier sans meta.yml, vos commandes visent le catalogue actif ; depuis l'intérieur d'un dépôt de catalogue, elles visent ce dépôt, quel que soit l'actif. Si une commande semble viser le mauvais catalogue, regardez d'abord où vous êtes et si LAB_HOME est définie, avant de soupçonner catalog use.

Comment changer de catalogue actif ?

dsoxlab catalog use <identifiant> désigne le catalogue servi hors de tout dépôt, parmi ceux qui sont installés. Chaque catalog add réussi rend déjà actif le catalogue qu'il vient de poser ; use sert donc à revenir sur un catalogue installé plus tôt, quand vous en jouez plusieurs en parallèle.

dsoxlab catalog use linux

✔ Catalogue actif : « linux » (/home/alice/.local/share/dsoxlab/catalogs/linux)

Pour vérifier, dsoxlab catalog list marque d'un ✔, dans la colonne « Actif » du tableau « Catalogues installés », le catalogue qui vient d'être choisi. Un identifiant qui n'est pas installé donne le message « Aucun catalogue … installé » et un code de sortie 1 : vérifiez l'orthographe avec catalog list, sans oublier que l'identifiant d'un catalogue installé par URL est celui du dossier créé.

Ne confondez pas catalog use avec dsoxlab use, qui fixe le contexte de travail à l'intérieur d'un catalogue, c'est-à-dire la section et le niveau. Le second est le sujet de la leçon Trouver son prochain lab dsoxlab.

Comment mettre à jour un catalogue ?

dsoxlab catalog update [identifiant] met à jour un catalogue installé, ou tous si vous n'en nommez aucun. Sous le capot, la commande lance git pull --ff-only dans le dossier du catalogue : elle avance l'historique sans jamais fusionner. Votre fichier .dsoxlab.db n'est pas versionné par le catalogue, donc la mise à jour ne l'efface pas.

dsoxlab catalog update linux

ℹ Catalogue « linux » à jour.

Quand le dépôt a avancé, la ligne devient « Catalogue « linux » mis à jour » suivie du résumé de git. Sans identifiant, update traite tous les catalogues installés l'un après l'autre et sort en code 1 si l'un d'eux échoue, même si les autres ont réussi : un script qui enchaîne lit ce code. Sans aucun catalogue installé, la commande se contente de le dire.

Mettez la CLI à jour avant les catalogues, pas l'inverse. Un catalogue récent peut exiger une version du contrat (le format du meta.yml et des labs) plus neuve que celle que la CLI sait lire ; elle le dit alors en nommant la version trouvée et celle qu'elle supporte, et la réparation est de mettre à jour l'outil, ce que la leçon Installer dsoxlab en local explique.

Comment retirer un catalogue ?

dsoxlab catalog remove <identifiant> supprime le dossier du catalogue, et avec lui votre progression. Si ce catalogue était l'actif, la commande oublie aussi cette désignation. Elle ne demande aucune confirmation : vérifiez l'identifiant avant de la taper.

dsoxlab catalog remove linux

✔ Catalogue « linux » retiré (/home/alice/.local/share/dsoxlab/catalogs/linux).

Le critère de réussite est que dsoxlab catalog list ne montre plus la ligne dans « Catalogues installés ». Si vous voulez garder vos notes, ne retirez pas le catalogue : l'historique n'a pas d'autre copie. Le catalogue de démonstration est un cas à part : il n'est pas installé sous catalogs/, et on le réinstalle avec dsoxlab demo --force, comme le montre la leçon sur le premier lab.

Dépannage

Le tableau part du message affiché, donne la cause et la commande qui répare. Les messages sont ceux de la CLI en français.

Symptôme	Cause	Solution
« Catalogue « xxx » inconnu »	catalog add n'a reçu ni identifiant du manifeste, ni URL	dsoxlab catalog list pour voir les identifiants, ou donner l'URL complète du dépôt
« git est absent »	catalog add clone un dépôt et ne peut pas fonctionner sans git	Installer git, puis relancer dsoxlab doctor et la commande
« Le clone de … a échoué »	URL fausse, dépôt privé ou réseau coupé	Vérifier l'URL dans un navigateur, puis relancer ; le dossier à moitié cloné est supprimé
« Le dépôt … ne porte pas de meta.yml »	L'URL pointe vers un dépôt qui n'est pas un catalogue dsoxlab	Utiliser le dépôt du catalogue, pas celui d'un outil ou d'un guide
« Le catalogue … est déjà installé »	Le dossier existe et porte votre progression	dsoxlab catalog update <id>, ou --force seulement pour tout perdre
« Aucun catalogue … installé » sur use, update ou remove	L'identifiant ne correspond à aucun dossier de catalogs/	Relire l'identifiant dans dsoxlab catalog list, colonne « Identifiant »
La mise à jour échoue avec un message de git	L'historique du dépôt a divergé de votre copie, --ff-only refuse de fusionner	Réinstaller avec dsoxlab catalog add <id> --force, en acceptant de perdre la progression
Une commande vise un autre catalogue que l'actif	Vous êtes dans un dépôt avec meta.yml, ou LAB_HOME est définie	Se placer hors du dépôt, ou retirer la variable avec unset LAB_HOME

Glissez pour voir

À retenir

• Un catalogue est un dépôt git de labs avec un meta.yml à sa racine ; la CLI n'en embarque aucun, hormis celui de démonstration.
• dsoxlab catalog list montre les catalogues connus par leur identifiant puis ceux qui sont installés, et accepte --json.
• dsoxlab catalog add prend un identifiant ou une URL, clone en --depth 1 sous ~/.local/share/dsoxlab/catalogs/ et rend le catalogue actif.
• Dans un dépôt de catalogue, la CLI sert ce dépôt : LAB_HOME passe d'abord, le catalogue actif ne vient qu'ensuite.
• dsoxlab catalog use change l'actif ; catalog update lance git pull --ff-only, sur un catalogue ou sur tous.
• Un catalogue installé par URL prend pour identifiant le nom de son dossier, et c'est lui que use, update et remove attendent.
• La progression vit dans .dsoxlab.db, dans le catalogue : remove et add --force l'effacent, update la préserve.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →