dsoxlab training: play and validate the site's labs

dsoxlab is the command line that runs the labs of this site's training paths. It prepares a throwaway environment, hands you a mission, then inspects the real state of the system to say whether the skill is acquired and to compute a score. It installs with one command, and the demonstration lab shipped with it needs no virtual machine, no container and no Docker.

This page walks you through a complete lab from end to end, then wires up the catalogues of the training paths. It also opens the dsoxlab training path: three parts, from the installation to writing your own catalogue of challenges. It is written for anyone following a path on this site who wants to prove what they can do, not only read about it.

What you will learn

Install the dsoxlab CLI and check that your machine is ready.
Play a complete lab without provisioning a single machine.
Understand the challenge, check, score model, and how the mark is computed.
Wire up the Linux, Ansible, Terraform and Kubernetes lab catalogues.
Diagnose the two errors that come back most often when starting out.
Place each lesson of the path, from the appliance to writing a course.

Prerequisites

Little is needed, and that is deliberate: Python 3.11 or newer, and one of the two Python tool installers, uv or pipx. Nothing to clone, nothing to compile. Labs that require virtual machines have extra prerequisites, covered further down this page, but none of them is needed to begin.

What is a verifiable lab?

A verifiable lab is an exercise whose success is measured on the state of a system, by automated tests, not by reading an answer key. That is what dsoxlab brings to the training paths of this site: a quiz checks what you understood, a verifiable lab proves what you can do, and neither replaces the other.

dsoxlab is an engine, not a course. It reads a declarative catalogue: a meta.yml file at the root says what the catalogue offers, and one lab.yaml per lab says what that lab requires. The engine provisions what is asked for, opens the session, then runs tests.

Those tests are its reason to exist. They read the state of the system, never the commands you typed. A lab that requires a running service checks that the service runs, whatever route you took to get there. That rule has a pleasant consequence: every way of succeeding counts, including the one the lab's author never thought of.

On the other hand, dsoxlab carries no teaching content of its own. The guides live on this site, the labs in companion repositories, and the engine knows nothing about Linux, Ansible or Kubernetes in particular.

The challenge, check, score model

Every lab rests on three parts, and each one maps to a command. The challenge is the mission, written in challenge/README.md: it says what has to be produced, with a scale announced task by task. The check is the validation: dsoxlab check runs pytest tests that inspect the system, then records the result. The score starts at 100 points, or at the scale the lab declares, and every hint you take removes a share known in advance.

Two details of this model are worth knowing before you start. First, a lab declared as a mock exam carries a pass mark, and dsoxlab submit then renders a verdict, passed or failed, against that mark. Second, as long as neither check nor submit has been run, nothing is written: a lab can be started over without leaving a trace in your history.

Installing dsoxlab

One command, and nothing lands on your system apart from the tool itself:

uv tool install dsoxlab      # or: pipx install dsoxlab

Then check that your machine has what it takes. The doctor command separates what is required from what is merely informational, which saves you from chasing a component you have no need for:

dsoxlab doctor

                              Required for this repo
┃ Component     ┃ Status ┃ Detail
│ Python        │  ✔ OK  │ 3.14.2
│ pytest        │  ✔ OK  │ bundled with dsoxlab (used by 'check')
│ ShellRuntime  │  ✔ OK  │ always available
│ git           │  ✔ OK  │ git version 2.43.0
│ Labs detected │  ✔ OK  │ 1 lab(s) in ~/.local/share/dsoxlab/demo

The informational table that follows lists Docker, KVM and Incus. None of them blocks anything as long as you are not playing a lab that requires it. The lesson Installing dsoxlab locally details the prerequisites, updating the tool and shell completion.

Playing a first lab, without provisioning anything

The demo command installs a catalogue with a single lab, whose subject is dsoxlab itself. It runs in the shell runtime: no virtual machine, no container, so it works wherever the CLI works.

Terminal: dsoxlab installs the demo catalogue, lists its lab, then prints the score once the work is validated

The sequence above is three commands long, and it is exactly what you are about to type:

dsoxlab demo
cd ~/.local/share/dsoxlab/demo
dsoxlab list-labs

The table printed carries one line per lab, with its section, its id, its type, its runtime, its duration and its score:

Section	ID	Title	Type	Runtime	Duration	Score
demo	`premiers-pas`	First steps with dsoxlab	lab	shell	5m	empty

The Score column stays empty until the lab has been validated. That column is what will tell you, later on, where you stand on a catalogue of sixty labs, and which ones are left to replay.

The loop of a lab: course, mission, hint, validation

Four commands are enough, and they always follow each other in the same order.

The course gives the material. On the catalogues of the training paths, it points to the matching lesson on this site:

dsoxlab course premiers-pas

The mission says what has to be produced, and above all what will be checked:

dsoxlab challenge premiers-pas

The demonstration lab asks for three files under reponses/, and its mission states its grading rule in black and white: "The files, and nothing else. Not your shell history, not the commands you typed. Any way of creating them counts."

A hint is available at any time, and its cost is announced before it is spent. On this lab, it removes 20 points out of 100:

dsoxlab hint premiers-pas

The validation runs the tests, prints the detail of each one and records the result:

dsoxlab check premiers-pas

The closing panel sums up the three figures that matter. Here is the one obtained by playing this lab with one hint taken:

Panel line	Value obtained
Tests	3 / 3
Hints	1 used, 20-point penalty
Score	80 / 100 pts

The scale is therefore readable: success earns the points, a hint reduces them, and dsoxlab scores keeps the complete history, failed attempts included.

The working directory trap

Here is the mistake that costs the most time, and it cannot be guessed. dsoxlab run does more than print instructions: it prepares an isolated working directory, challenge/work/, and drops you into it.

dsoxlab run premiers-pas

The banner it prints starts with Lab premiers-pas ready. You are now in challenge/work/ and names that directory as your isolated working directory. The tests read paths relative to that directory. If you create your files somewhere else, for instance straight under challenge/, they do not find them, the score drops to zero, and the message invites you to create a file you have just created. The demonstration lab's tests are written in French only, whatever your language setting, so the assertion reads:

E     Crée le fichier, par exemple : mkdir -p reponses && echo <le mot> > reponses/indice.txt
E     assert False
E      +  where False = exists()

The rule fits in one sentence: always go through dsoxlab run before working, and stay where it drops you. Type exit to leave the session without recording anything.

Wiring up the lab catalogues of the training paths

The demonstration lab only serves to understand the mechanics. The real labs live in catalogues, one per training path, which the CLI knows how to install and keep up to date:

dsoxlab catalog list
dsoxlab catalog add linux
dsoxlab catalog use linux

Three catalogues are known by their identifier in version 0.2.5, the one this training path documents:

Identifier	Description
`linux`	Linux administration, RHCSA and LFCS
`ansible`	Ansible, from first playbook to collections
`terraform`	Terraform and infrastructure as code

The Kubernetes catalogue is not in that registry. It installs through the URL of its repository, which catalog add accepts just as well as an identifier:

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

The page Every lab lists the full contents of those catalogues, filterable by skill and by certification, with the guide that teaches what each lab measures. That is where to go to pick a catalogue on evidence rather than on its name, and every lab there is written in English, brief included.

Once a catalogue is active, dsoxlab next recommends the next lab and dsoxlab progress shows your progress block by block. That is the point of view most missing on a long training path: knowing what is left to prove. The Linux and Kubernetes paths that tie these labs to their lessons are written in French and not translated yet; the English home page lists what is, and the reading conventions explain how a lab appears inside a guide.

Labs that require machines

Some skills cannot be proved in a container, because the kernel is shared with the host. An AppArmor profile, a kubeadm upgrade, a broken kubelet or an etcd restore require real machines. Those labs then declare a vm runtime, and two commands frame their life cycle:

dsoxlab provision   # creates the lab's infrastructure
dsoxlab destroy     # tears it down, machines left outside the state included

dsoxlab start <id> plays the whole sequence of a lab, context, prerequisites, infrastructure then session, announcing each step with the command that replays it alone. It is the command to learn first on a catalogue of vm labs: when a step fails, it names which one, and nothing beyond it is attempted.

The doctor command tells you whether the expected provider, KVM or Incus, is present. Always destroy the infrastructure afterwards: those machines keep consuming memory and disk long after the lab is over. The lesson Sizing your machine for the labs puts a figure on what each catalogue requires.

What this training path contains

The path follows the order in which a learner meets the questions: where to install the tool, how many resources to plan for, which sequence of commands to remember, then how to write your own labs. Every lesson reads on its own, but part 3 assumes you have played at least one lab with part 2.

Part	Lessons	Reading
Part 1 · Install and prepare your machine	Installing dsoxlab locally; The appliance: a ready-to-play virtual machine; Sizing your machine for the labs	50 min
Part 2 · Everyday commands	The main dsoxlab commands; Files, environment variables and exit codes	40 min
Part 3 · For the trainer	Creating a course and its challenges from scratch; Bringing up the infrastructure of vm labs	55 min

No lesson of this path carries a quiz or a lab block: it is a path about the tool that runs the labs of the others. Putting it into practice means playing the demonstration lab above, then a real catalogue. The training path page lets you tick the lessons as you read.

Troubleshooting

The first two lines cover most of the blockers met when starting out. The third is rarer, but its message does not point to its cause, which makes it expensive.

Symptom	Cause	Solution
The tests ask for a file that already exists	Files created outside the lab's working directory	Run `dsoxlab run <id>` and work where it drops you
`No catalogue installed`	The CLI is installed, but no catalogue is wired up	`dsoxlab catalog add <id>` then `dsoxlab catalog use <id>`
A lab stays stuck at provisioning	KVM or Incus provider missing or stopped	`dsoxlab doctor`, then install the expected provider

When in doubt, dsoxlab support produces an anonymised diagnostic report, to paste into an issue of the catalogue's repository, and dsoxlab support --issue files it there directly. The complete log is written in any case to ~/.local/state/dsoxlab/dsoxlab.log.

Key points

dsoxlab is a lab engine with no content of its own: the guides are on this site, the labs in companion repositories.
A lab holds three parts: the challenge states the mission, the check runs the tests, the score starts at 100 and pays for every hint.
The tests read the state of the system, never the commands typed: every way of succeeding counts.
The demonstration lab needs no infrastructure and walks the whole loop in five minutes.
dsoxlab run drops you into an isolated working directory, where the tests read relative paths: that is the most expensive trap.
A hint costs points, and its price is announced before it is spent.
The linux, ansible and terraform catalogues install by identifier, Kubernetes by the URL of its repository in version 0.2.5.
A lab in the vm runtime is played with dsoxlab start and destroyed after use with dsoxlab destroy.

Next steps

Installing dsoxlab locally: the exact prerequisites, updating, shell completion and the two installation errors that come back.
Sizing your machine for the labs: how much memory, CPU and disk each catalogue really declares, Kubernetes included.
The main dsoxlab commands: every command, what it does, and the order in which they chain.
Creating a course and its challenges from scratch: writing your own catalogue, from meta.yml to the tests that prove.