Skip to content

Latest commit

 

History

History
124 lines (97 loc) · 7.61 KB

files.md

File metadata and controls

124 lines (97 loc) · 7.61 KB

Where dsoxlab writes

Audience: learners, catalog authors and trainers. This is the reference page the three share, and the only place these locations are written down.

Language: English · Français

dsoxlab keeps state in two families, and nowhere else: inside the catalog you are playing, and under your home directory. Progress belongs to the first family, so it is per catalog: two catalogs side by side keep separate histories, and deleting a catalog deletes its history with it.


In the catalog repository

Path What it holds Written by
<catalog>/.dsoxlab.db SQLite database: results (scores) and hint_requests check, submit, hint
<catalog>/.dsoxlab-context.json active section, level, language, lab, target, provider, and the course position use, run, course

Both belong in the catalog's .gitignore. Neither can be moved: they are the repository, which is what makes progress follow the catalog rather than the machine.

A catalog that declares vm labs also carries an SSH key pair under <catalog>/ssh/id_ed25519{,.pub}, generated by dsoxlab instructor bootstrap on each machine that provisions it. Neither half is committed: the private one must never be, and the public one is useless without it.


Under your home directory

Path What it holds Moved by
~/.local/state/dsoxlab/dsoxlab.log full log of every command, whatever the verbosity XDG_STATE_HOME
~/.local/state/dsoxlab/<catalog-id>/terraform/<provider>/ Terraform working directory and state XDG_STATE_HOME
~/.local/state/dsoxlab/<catalog-id>/cloud-init/ cloud-init templates copied out of the tool for provisioning XDG_STATE_HOME
~/.local/state/dsoxlab/<catalog-id>/dsoxlab.lock the per-catalog write lock (flock) XDG_STATE_HOME
~/.local/state/dsoxlab/<catalog-id>/bootstrap.json fingerprint of the catalog's foundation (infra.bootstrap) after it was played successfully. provision replays the playbook when its content no longer matches, or on --bootstrap; destroy removes this file XDG_STATE_HOME
~/.local/state/dsoxlab/<catalog-id>/provenance.json where the resources provisioned by this catalog come from: its id, the absolute path of the clone at provisioning time, the provider, the UTC timestamp, the provisioning id and the resource UUID. Read by dsoxlab infra origin, updated by provision, trimmed by destroy of whatever it actually destroyed. Versioned schema (dsoxlab-provenance-v1), atomic write, one file per catalog because the write lock is per catalog too. No secrets. This file is a readable cache: the same provenance is written onto the resources themselves (libvirt metadata on KVM, configuration keys of the same name on Incus), so deleting it loses nothing and the next provision rebuilds it XDG_STATE_HOME
~/.cache/dsoxlab/<catalog-id>/inventory.json generated Ansible inventory XDG_CACHE_HOME
~/.cache/dsoxlab/<catalog-id>/ssh_config generated OpenSSH config for the lab hosts XDG_CACHE_HOME
~/.cache/dsoxlab/version-check.json last version seen on PyPI, and when XDG_CACHE_HOME
~/.local/share/dsoxlab/demo/ demonstration catalog installed by dsoxlab demo XDG_DATA_HOME
~/.local/share/dsoxlab/catalogs/ catalogs installed by dsoxlab catalog add, one subdirectory per id XDG_DATA_HOME
~/.local/state/dsoxlab/<catalog-id>/labs/ work starting points, to tell a ready lab from one in progress XDG_STATE_HOME
~/.local/state/dsoxlab/catalogue-actif id of the active catalog, the one used without sitting in its directory XDG_STATE_HOME
~/.local/state/dsoxlab/sessions/<portal>-<digest>.json portal session opened by dsoxlab login: the tokens that let push write to your account. Mode 0600, one file per portal, removed by dsoxlab logout XDG_STATE_HOME
~/.ssh/config.d/<catalog-id>.conf SSH fragment for the lab hosts, so ssh, scp and your IDE reach them by name none

<catalog-id> is repo.id from the catalog's meta.yml. The lock falls back to the directory name plus a fingerprint of its absolute path when no meta.yml can be read, so two clones of the same catalog share one lock and one Terraform state.

The Terraform state is deliberately outside the catalog: a state file in a lab repository gets committed, and a committed state is a state that lies.

Two of these are caches, and losing them costs nothing but a regeneration: inventory.json and ssh_config are rebuilt on the next command that needs them. Anything that points at the generated ssh_config (an Include, an IDE profile) must tolerate its disappearance.

dsoxlab completion install writes outside these families, once: the shell completion (~/.zfunc/_dsoxlab plus a line in ~/.zshrc, or ~/.bash_completion.d/dsoxlab plus a line in ~/.bashrc).

Up to 0.1.61, dsoxlab install also wrote a wrapper at ~/.local/bin/dsoxlab. It no longer does: uv tool install and pipx put their launcher exactly there, and writing over a symlink writes into its target. If an old install left one behind, it is yours to delete.


What does not exist

These paths have been documented in the past. They are listed here so nobody looks for them again:

  • No ~/.config/dsoxlab/config.yaml, and no user configuration file at all. What can be set goes through the contract (meta.yml), the active context (dsoxlab use) or an environment variable. Multi-catalog discovery through such a file is planned (#78); until it lands, no code reads that path.
  • No ~/.local/share/dsoxlab/progress.db. Scores live in <catalog>/.dsoxlab.db, per catalog.
  • XDG_CONFIG_HOME is read nowhere. The three variables above are the only XDG variables dsoxlab honours.

Environment variables

Variable Effect
LAB_HOME Root of the catalog to work on, instead of auto-detection
DSOXLAB_LANG Display language (en / fr), wins over the context file
DSOXLAB_PROVIDER Infrastructure provider, wins over dsoxlab use --provider
DSOXLAB_TARGET Default target of a vm lab, when the session sets none
DSOXLAB_PAGER Pager for course and challenge (then PAGER, default less -R)
DSOXLAB_LOG DSOXLAB_LOG=debug is the same as -vv
DSOXLAB_HOST_READY_TIMEOUT Seconds to wait for a provisioned host to answer (default 180)
DSOXLAB_NO_UPDATE_CHECK Set to 1 to silence the daily PyPI version check
DSOXLAB_PORTAL_LOCAL Set to 1 to accept an http learning.portal_url towards localhost only, for whoever is writing a portal. Off by default, and never a catalogue's decision
DSOXLAB_OUTSCALE_PROFILE, DSOXLAB_AWS_PROFILE Credentials profile for those providers

Three more are set by dsoxlab and are not meant to be set by hand: DSOXLAB_TARGET_HOST (the host the tests must inspect, which is how a multi-distro lab tests the target you chose) and LAB_NO_REPLAY=1, both exported to the pytest run; and DSOXLAB_LAB_SESSION (the lab id) inside the session run opens, which is how submit knows it runs inside one.


This page cannot drift

tests/test_documentation_synchrone.py derives the real locations by calling the code — the same functions the CLI calls — and fails when a path cited in any documentation page matches none of them. The false progress.db and config.yaml above are what motivated it: they were documented for months because nothing read the documentation and the code at the same time.