NixOS host — install, configure, modules

Updated

July 30, 2026

NixOS host — install, configure, modules

This part of the standalone NixOS book is organized by topic (normal book chapters), not by calendar day.

Read chapters in order within the part when learning; skip or skim freely when using the book as a reference.

What this part is for

NixOS host turns the Concepts toolkit into machine ownership: install a disposable NixOS system, manage it with a flake (nixosConfigurations), rebuild and roll back safely, then configure users, network, packages, systemd, modules, boot, and filesystems.

You leave this part with a lab host whose source of truth is a git flake, not ad-hoc edits under /etc/nixos alone.

Previous part This part Next part
Concepts — language, store, flakes Install + configure one host Home Manager, flake layout, lock discipline

Baseline (this book)

Piece Baseline
NixOS / nixpkgs 26.05 “Yarara”
Nix 2.34.x with nix-command + flakes
Host management sudo nixos-rebuild switch --flake .#<host>
Install target Disposable VM preferred (not daily-driver only disk)

Learning outcomes

By the end of this part you should be able to:

  1. Install NixOS 26.05 (UEFI-oriented) and document hardware/boot layout
  2. Define nixosConfigurations.<name> and rebuild from a flake repo
  3. Choose switch / test / boot / build and rollback generations
  4. Declare users, SSH keys, and safe remote access habits
  5. Configure networking and an explicit firewall that still allows admin access
  6. Prefer environment.systemPackages vs programs.* deliberately
  7. Ship custom systemd services and timers via Nix
  8. Consume modules via options (mkIf / mkDefault literacy)
  9. Write a small custom module with options, mkIf, and assertions
  10. Document boot loader, kernel, and firmware choices
  11. Inventory filesystems and classify store vs state (impermanence idea)

Prerequisites

Required Strongly recommended
Concepts part (or equivalent fluency) Working flake + modern CLI habits
Hypervisor or spare machine VM snapshots before boot/network experiments
Git for the host config repo Console access for lockout recovery drills

If you skipped Concepts, at least complete: store/closures, functions, flakes + devShell, modern CLI.

Chapter map

Chapter Title Focus
Installing NixOS ISO, UEFI, partition, first boot, snapshots
Flake-defined hosts nixosConfigurations, repo layout, first switch
Rebuild and generations Modes, profile gens, rollback card
Users and access wheel, SSH keys, password hygiene
Networking and firewall networkd/NM, ports, DNS, safety patterns
Packages and programs systemPackages vs programs.*, closure discipline
systemd via Nix units, timers, absolute paths, inspect
Modules as consumer options, merge, mkIf/mkDefault, reading source
Custom modules options + config, assertions, namespaces
Boot and hardware loader, kernel, firmware, recovery
Filesystems and state mounts, persist lists, store ≠ data

Suggested learning paths

Path Order Notes
Linear (recommended) 01 → 11 Each chapter assumes the flake host exists
Already installed Start at 02; skim 01 for inventory Still document hardware
Ops recovery focus 03, 04, 05, 10, 11 After a minimal flake host works
Module author track 08 → 09 after 02–07 Needs a living host config

Architecture sketch (part-level)

git repo: ~/nixos-config
  flake.nix  →  nixosConfigurations.lab = nixosSystem { modules = [ … ] }
  hosts/lab/configuration.nix
  hosts/lab/hardware-configuration.nix
  modules/*.nix

sudo nixos-rebuild switch --flake .#lab
        │
        ▼
  evaluate modules → system derivation → realize → activate
        │
        ▼
  /nix/var/nix/profiles/system  (generations + boot entries)

Safety rules for this part

  1. Prefer a VM with snapshots before firewall, boot, or SSH lockout drills
  2. Keep console access until key-based SSH is proven
  3. Use nixos-rebuild **test** for risky network/firewall changes, then switch
  4. Never put private keys or live passwords in the flake
  5. Treat hardware-configuration.nix UUIDs as machine-specific truth
  6. Remember: rollback restores system closure, not /var databases

Lab workspace convention

On the lab host (or mirrored on your workstation):

mkdir -p ~/nixos-config/{hosts/lab,modules,docs}
cd ~/nixos-config
git init

Rebuild command of record:

sudo nixos-rebuild switch --flake .#lab

Document hostname, flake attr, and hypervisor network mode in README.md.

Part gate (before Home / flake layout)

  • Disposable NixOS 26.05 lab boots
  • Flake nixosConfigurations.<host> is source of truth
  • Successful switch --flake and a documented rollback path
  • SSH key admin user; no private keys in git
  • Firewall enabled with explicit SSH allow
  • Daily tools declared (not only nix profile)
  • At least one custom systemd unit and one custom module
  • Boot + filesystem docs exist; store vs state explained

Further depth (this book only)

After this part… Go to
Home Manager, direnv, flake-parts Part Home and flake layout
sops, hardening, services, TLS Part Services and security
Disko, impermanence, deploy, tests Part Ops and fleet
Module system internals Part Internals
Capstone multi-service host Part Capstone / Projects

How to use this part as a reference

  • Jump via chapter titles when debugging (“firewall”, “generations”, “custom modules”)
  • Keep a rollback card (docs/rollback.md) updated as you learn boot and SSH
  • Prefer options on search.nixos.org with 26.05 selected
  • Do not link or depend on any external day-numbered curriculum; this book is self-contained

When later parts say “on your lab host,” they mean the machine and flake built here.