nordisk/Skidbladnir

Skíðblaðnir — for idiots (zero to a bundle across the gap)

Class: idiot. Every step, nothing assumed. Goal: pack a folder into one sealed bundle, then verify and unpack it on the "other side" — all on your own machine, no network. If you already know Rust, read guide.md instead — this one spells out every keystroke.

What you need first

• A terminal (the black window where you type commands).
• The Skidbladnir repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/Skidbladnir

• Rust installed (the cargo command). Check it — type and press Enter:

cargo --version

If it prints a version, you are good. If it says "command not found", install Rust from https://rustup.rs first.

Step 1 — make a folder to pack

We will pretend this folder is your whole product. Type each line, pressing Enter after each:

mkdir -p /tmp/mystaging/bin
echo "hello from my product" > /tmp/mystaging/bin/app

You now have a tiny "staging tree" — one file, bin/app.

Step 2 — build the tool

Type and press Enter (this compiles Skidbladnir once; it may take a minute):

cargo build --release

Red text = errors. If it finishes quietly, continue.

Step 3 — see the pipeline with your own eyes (a test run)

Skidbladnir's own tests pack, verify, and unpack a folder exactly the way the real pipeline does. Run them and watch them pass — type and press Enter:

cargo test --release archive

Look for the green line test result: ok. The test named pack_then_extract_roundtrip_with_manifest_checksums just did the whole pack → manifest → verify → extract loop on a fixture folder. That is the pipeline.

Step 4 — understand what just happened (the four moves)

1. pack — Skidbladnir copied your files into a versioned staging tree and wrote a VERSION file next to the bundle (so bumping the version is easy).
2. archive — it sealed the tree into one file (tar + zstd compression) and wrote a sidecar …​.manifest.json listing a SHA-256 fingerprint for every file plus one root fingerprint for the whole thing.
3. fetch (verify-on-receipt) — on the "other side" it re-computed every fingerprint and compared them to the manifest. If even one byte changed in transit, it refuses to continue.
4. unpack — only after the fingerprints match does it extract the files into place.

The point: you can carry that one file across an airgap on a USB stick, and the far side can prove nothing was tampered with before it unpacks anything.

Step 5 — run the whole test suite (optional, to see every function)

Type and press Enter:

cargo test --release

Every green ok is one function proving itself: pack, archive, fetch, pki, layout, install, unfold, orchestrate, events, msi. This is the whole ship, in miniature.

Where to go next

• To learn one function step-by-step, open its idiot guide — e.g. install-for-idiots.md walks a full service install.
• To drive the real pipeline (not the tests), read guide.md.
• To understand why it is built this way (one bundle, no shell, no network), read reasoning.md.