Projects index

Updated

July 30, 2026

Projects: packaging and your own distro

Hands-on projects that turn this book’s theory into store paths you own. Prefer a disposable VM (or a dedicated partition), flakes-first workflows, and commits after each green checkpoint.

Baseline Value
Nix 2.34 family (nix --version)
NixOS / nixpkgs 26.05 (nixos-26.05 flake input)
Style Flakes-first; modern nix CLI
Safety Lab machines only; no production secrets in trees

These projects sit after (or alongside late stages of) the main syllabus. They do not replace the stdenv phases chapter–56 packaging theory—they force you to ship small packages and then a branded ISO product.

How to use this part

Learning loop

read goal → declare flake/module → rebuild/build
    → observe store / VM → fix → commit slice → next project
  1. Read the goal and constraints before opening an editor. Know what “done” means.
  2. Type configs yourself. Copy-paste once to unstick, then retype the critical attrs so they stick.
  3. Break one thing on purpose (wrong hash, missing runtimeInputs, overlay not applied). Roll back with generations or git checkout.
  4. Commit a working flake slice before starting the next project. Tag optional: project-01-green.
  5. Write a short lab note (even five bullets). Future-you will forget which hash field mattered.

Lab environment checklist

Check Why
Flakes + nix-command enabled All project flakes assume modern CLI
≥ 20–40 GiB free on /nix volume ISO builds and language deps are fat
KVM / nested virt available Project 6–7 boot tests
Git installed Lockfiles and project slices
No production credentials in the tree Habits transfer to real fleets 
nix --version
# expect something in the 2.34.x line (or newer compatible)

# optional: isolate lab work
mkdir -p ~/lab/nixos-projects
cd ~/lab/nixos-projects

How chapters are structured

Every project chapter follows roughly the same skeleton:

Section Purpose
Goal One-sentence outcome
Why What skill this forces
Prerequisites Book stages / prior projects
Theory Concepts you must be able to explain
Lab tree Suggested layout
Step-by-step Commands and Nix you type
Acceptance criteria Binary pass/fail
Pitfalls Common failure modes
Stretch goals Optional depth after green

Project path

Track A — Derivations & packaging

Build confidence from the smallest honest package up to language builders and overlays.

# Chapter Outcome
1 Hello CLI (stdenv) nix run a shell/C tool you packaged
2 Script tool + wrap Declared runtime deps (jq, …) via wrappers
3 Language package buildGoModule or buildPythonApplication end-to-end
4 Overlay: pin / patch Change nixpkgs locally without a hard fork

Track B — Custom NixOS-based distro

Name a product, brand it, build an ISO, ship a multi-edition flake.

# Chapter Outcome
5 Distro identity & branding PRODUCT.md + identity module + assets
6 ISO + themes Bootable installer/live image with visible brand
7 Complete product flake Editions, defaults, install story, DEMO.md

Sample assets (lab-ready): branding/ — logo.svg (CC0), os-release fragment example, Plymouth notes. Copy into your distro flake; do not reuse official NixOS marks as your product logo.

Track A (packaging)              Track B (distro product)
───────────────────              ────────────────────────
01 hello CLI                     05 identity + artwork
02 script + wrap                 06 ISO + themes
03 language builder              07 full product flake
04 overlay pin/patch

Suggested order

  • Linear: 1 → 2 → 3 → 4 → 5 → 6 → 7 (recommended first pass).
  • Packaging only: stop after 4 if you only need nixpkgs craft.
  • Distro-first: you can start at 5 if you already completed Stage V packaging days—but Projects 1–2 still teach $out muscle memory that ISO work assumes.
  • Parallel with syllabus: Project 1 after the stdenv phases chapter; Project 4 after the overlays chapter + 49; Project 6 after the images/generators chapter.

Time and difficulty (rough)

Project Lab time Difficulty Heavy disk?
1 Hello CLI 1–2 h Easy No
2 Script tool 1–3 h Easy–medium No
3 Language pkg 2–5 h Medium Moderate (Go/Python deps)
4 Overlay 2–4 h Medium Low
5 Identity 2–4 h Medium Low
6 ISO + themes 3–8 h Hard Yes (multi‑GB)
7 Product 4–12 h Hard Yes

ISO builds can pull large closures. Plan cache space and coffee accordingly.

Repository hygiene (all projects)

good project slice
├── flake.nix
├── flake.lock          # committed
├── pkg.nix / modules/  # small, reviewable
├── NOTES.md or REPORT.md
└── no secrets, no /etc copies, no private keys
Rule Reason
Commit flake.lock Reproducible classmate / future rebuilds
Prefer nixos-26.05 over nixos-unstable for labs Stable teaching target for this book
One concern per commit Easy bisect when Project 6 ISO fails
Document the command that worked ISO flags and QEMU lines rot in memory 
# habit after each green project
git add -A
git status   # re-check: no secrets
git commit -m "project-NN: green checkpoint"

Done means (global bar)

You are “done” with this part when all of the following hold:

  • You can explain every store path your Project 1–3 packages produce (at least one sentence each).
  • Every lab flake has a committed flake.lock.
  • No secrets in any project repo (tokens, age keys, Wi‑Fi PSKs).
  • Project 4 overlay change is observable (nix run / version / patched string).
  • Distro ISO (Project 6) boots in a VM and shows your branding on ≥2 surfaces.
  • Project 7 README explains build → boot → install/upgrade in your own words.

Trademark and ethics (read once)

“NixOS” is a trademark of the NixOS Foundation. Building a learning derivative is encouraged; impersonating official media is not.

  • Choose a distinct product name (e.g. YararaOS, MyLabOS).
  • Do not ship official snowflake artwork as your logo.
  • When docs mention upstream, say “NixOS-based” honestly.
  • See NixOS community / branding guidance when publishing publicly.

Quick start: create the lab root

mkdir -p ~/lab/nixos-projects
cd ~/lab/nixos-projects
git init

# after Project 1 skeleton exists:
# nix flake new hello-cli   # or hand-write flake.nix as in the chapter

Work one directory per project (or one monorepo with subdirs). Avoid mixing ISO builds into the tiny hello-cli tree—different GC pressure and mental models.

When ready, open Project 1 — Hello CLI.