Boring-NixOS
Boring NixOS
A direct, practical guide to configuring infrastructure that builds identically every time: deterministic, immutable, and refreshingly boring.
Ambiguity is the enemy of reliability. When machines mutate silently through ad-hoc commands, builds drift, onboarding breaks, and outages follow. The boring default is to define the full closure in code — from developer compilers to multi-region cloud clusters — so every environment evaluates identically six months later.
Baseline: Nix 2.35+ · NixOS 26.05+ · Flakes enabled. Standalone and self-contained. You do not need any other title in this library.
Who this is for
- Engineers, platform developers, and SREs who want systems that build identically on a laptop, CI runner, and bare-metal server.
- Developers looking for instant, clean project environments without container lag or host library pollution.
- Teams moving away from fragile setup scripts and mutable system administration toward pure declarative configuration.
You do not need prior experience with Nix or functional programming. A terminal, a standard text editor, and basic Linux familiarity are all you need.
What “boring” means here
Nix is a purely functional package manager and domain-specific language. Applied with discipline, it eliminates entire categories of operational bugs: conflicting shared libraries, broken symlinks, broken OS upgrades, and undocumented host drift.
When over-complicated, it can become an impenetrable maze of nested overlays and tangled macros.
Boring NixOS teaches clear, sustainable defaults: - Plain, readable expressions over clever meta-programming. - Explicit inputs pinned by cryptographic lockfiles. - Modular, auditable NixOS system definitions that scale without surprise.
How to read
- Read the chapter concept and mental model.
- Type the expression into its designated file (
default.nix,shell.nix,flake.nix, orconfiguration.nix). - Run the exact build or evaluation command.
- Experiment with the Try this exercises to verify how the store and evaluator behave.
The chapters are sequenced progressively. Install Nix (and optionally NixOS) in part 0, then the store and the language. You can jump to devShells, NixOS services, or CI caching once those basics exist.
How examples work
Every code listing is a complete, runnable expression or file. Nothing is an incomplete fragment left for you to guess.
# default.nix
let
message = "reproducible desk online";
in
messagenix-instantiate --eval default.nix"reproducible desk online"A recurring scenario — a small team infrastructure desk (workstations, devShells, microservices, deployment pipelines) — connects the exercises so each technique solves a practical engineering challenge.
Map of the book
| Part | Folder | What you leave with |
|---|---|---|
| 0 | 00-introduction |
Why imperative setups drift; install Nix; install NixOS on a disposable VM |
| 1 | 01-nix-fundamentals |
/nix/store, hashes, RUNPATH, closures, db.sqlite, GC, raw derivations, why-depends / path-info / nix-tree |
| 2 | 02-nix-language |
Types, let … in, functions, attrsets, lists, imports, the REPL |
| 3 | 03-dev-environments |
mkShell, polyglot toolchains, flakes, direnv, nix-darwin, Nix on a foreign Linux, nix-ld / FHS |
| 4 | 04-packages-and-overlays |
nixpkgs, flake inputs, overlays, custom packages, fetchers, NIX_PATH / npins |
| 5 | 05-building-from-source |
stdenv, C/CMake, Rust, Python, Go modules / gomod2nix / Go shells / Go cross, Node, trivial builders, source filters, patches, anti-patterns |
| 6 | 06-nixos-system |
Modules, first machine, systemd, firewall, users, hardware, Disko, impermanence, generators, backups and GC windows, systemd Stage 1 initrd |
| 7 | 07-home-manager |
User modules, dotfiles, shell/editor, app settings, one-flake NixOS+HM |
| 8 | 08-cicd |
Binary caches, GitHub Actions, GitLab CI, caching strategy, tests, secrets, remote builders |
| 9 | 09-containers-k8s |
dockerTools images, k8s as modules, Helm, GitOps, mesh (optional late path) |
| 10 | 10-iac |
Terraform/OpenTofu providers, Ansible, cloud patterns |
| 11 | 11-secrets-security |
Why the store is public; sops-nix; Age; Vault; hardening |
| 12 | 12-platform-engineering |
IDP, monorepos, fleet, tuning, debug, tests, upgrades, Colmena, microVMs, CA internals |
| 13 | 13-production-capstone |
Threat model, Disko + ephemeral root, WireGuard, app stack, fleet rollback |
| 99 | 99-appendices |
Glossary, command cheat sheet, Nix/NixOS version notes |
What this book is not
- Not an exhaustive reference manual of all 100,000+ packages in
nixpkgs. - Not an exercise in esoteric functional programming puzzles.
- Not a guide to maintaining legacy channels and unpinned channels.
It is a concrete guide to writing reproducible systems that remain easy to understand, maintain, and operate.