.nornir/workspace-for-idiots.md · nordisk/nornir

The nornir workspace — for idiots

Class: idiot. Every step, nothing assumed. Goal: stand up one nornir workspace from a cold shell, from an empty directory to nornir workspace ls showing it green. If you already know your way around a terminal, read workspace-guide.md instead — this one spells out every keystroke. The what is in workspace-design.md; the why in workspace-reasoning.md.

What a workspace is, in one sentence

A workspace is a named list of code repositories (the "members") that nornir clones, indexes, and stores together as one unit. You are going to write that list in one small text file and then run one command.

What you need first

A terminal (the black window where you type commands).
nornir installed and on your PATH. Check it — type this and press Enter:

nornir --version

If that prints a version, you are good. If it says "command not found", nornir is not installed yet — stop and install it first.

Step 1 — go to where your code lives

Your workspace folder sits next to your code checkouts, not inside them. Go to the directory that holds them. For example, type this and press Enter (change the path to yours):

cd /run/media/rickard/T9/git

Type this and press Enter to see what's there:

ls

You should see your code folders (like holger, znippy, nornir).

Step 2 — make the workspace folder

Pick a name for your workspace (here we use demo). Type this and press Enter:

mkdir -p workspace_demo/release workspace_demo/.nornir/logs

Then go into it — type and press Enter:

cd workspace_demo

Step 3 — write the descriptor file

This one file lists the members. Open a text editor on a new file called nornir-workspace.toml in this folder. Put exactly this in it (change the names and URLs to your repos):

[workspace]
name = "demo"

[repos.holger]
git = "https://codeberg.org/nordisk/holger"

[repos.znippy]
git = "https://codeberg.org/nordisk/znippy"

Rules:

One [repos.<something>] block per repo.
git = "https://…" for a public repo (no password needed).
git = "git@codeberg.org:…" for a private repo (needs a key — see Step 6).
If the code is already checked out on your disk, use path = "../holger" instead of git.

Save the file.

Step 4 — register the workspace

Make sure you are still inside workspace_demo (that's why we cd'd in — so nornir can find the file you just wrote). Type this and press Enter:

nornir workspace add demo --monitored --poll 60s

This does everything at once: it records the workspace, clones every member, and builds the warehouse. You will see four lines go by:

① registered demo (2 member(s))
② fetching   2 member(s)…
③ building   warehouse…
✓ added demo — populated now (snapshot …) at ~/.nornir/workspaces/demo/builds

If you see the ✓ line, it worked. Skip to Step 7.

Step 5 — if you see red text

Read the last line. The two common problems:

"SSH-only members can't be cloned yet" — one of your members uses a git@codeberg.org:… URL and you have no key yet. Go to Step 6.
A member failed to clone — see exactly why by typing and pressing Enter:

nornir workspace events demo

It prints one line per member with the reason (wrong URL, repo doesn't exist, no network). Fix the URL in nornir-workspace.toml and run Step 4 again — it's safe to re-run.

Step 6 — private (SSH) members: make a key once

Only if a member uses a git@… URL. Type these, pressing Enter after each:

nornir key generate
nornir key show

The second command prints a public key. Copy that whole line, open your repo on codeberg in a browser, go to its Settings → Deploy Keys, and paste it in. Do that for each private member. Then run Step 4 again.

Step 7 — check it's really there

Type this and press Enter:

nornir workspace ls --status

You should see one row for demo with a green POPULATE mark, meaning every member cloned and built. If a member is red, it names which one and the error — go back to Step 5.

To see the full record, type and press Enter:

nornir workspace show demo

To see where nornir put all the data, type and press Enter:

nornir root

It prints something like /home/you/.nornir. Your workspace's data is under .nornir/workspaces/demo/ — the cloned code in git/, the warehouse in builds/warehouse/. You do not edit anything in there by hand.

Step 8 — keep it fresh

You don't have to do anything: a running nornir server re-clones and rebuilds whenever a member's code changes. To force a refresh yourself right now, type and press Enter:

nornir workspace fetch demo

If you need to remove it

Type this and press Enter to forget the workspace but keep its data:

nornir workspace rm demo

Or to delete its data too (the warehouse), type and press Enter:

nornir workspace rm demo --purge

That's the whole thing. One folder, one nornir-workspace.toml, one nornir workspace add. Do the next workspace the same way.