NixOS Configuration Manual

A structured learning path to take you from "I need AI to change my config" to "I understand exactly what every line does and can confidently make changes myself."

This manual uses your actual configuration as the primary teaching material. Every concept is illustrated with real code from this repository so you can see theory applied in practice.

Last synced with nixos-config commit: 40a54ae248973e9dc510376679cdb20c3e3d794f.

Learning Path

The manual is organised in two parts. Part 1 covers the practical knowledge you need to manage and modify your configuration day-to-day. Part 2 explains the underlying theory — the Nix language, the module system, and how everything fits together. You can start with Part 1 and refer back to Part 2 when you want to understand why something works the way it does.

Part 1: Managing Your System

1. Configuration Structure -- How this multi-host repository is organized: directory layout, the makeNixosSystem helper, and import chains for each host.

2. Common Workflows -- Step-by-step instructions for every task you will do regularly: adding packages, creating modules, using the profile pattern, updating, rebuilding, and deploying.

3. Host Configurations -- All three hosts in detail: electra (three-tier laptop), lena (family laptop), and vega (home server).

4. NixOS Specialisations -- What specialisations are, how they work, and how electra's three boot tiers (battery, igpu, dgpu) are implemented.

5. Package Management -- System packages vs. user packages, the profile system, external flake packages, and how to find and add software.

6. Secrets Management -- How sops-nix encrypts secrets at rest and decrypts them during system activation using host SSH keys. Adding secrets, registering hosts, and how modules consume credentials.

7. Troubleshooting -- Common errors, how to read Nix error messages, debugging strategies (including multi-host and specialisation-specific issues), and how to recover from a broken configuration.

Appendix

8. Quick Reference -- Cheat sheet of commands, a complete file guide, and common Nix patterns.

Part 2: How NixOS Works

9. The Nix Language -- The syntax and data types you need to read and write Nix expressions. Start here if you want to understand the language from scratch; Nix is unlike most languages.

10. Declarative Configuration -- What it means to describe your system rather than script its setup, and why NixOS works this way.

11. Flakes -- How flake.nix and flake.lock define your project's inputs, outputs, and reproducibility guarantees. Covers the makeNixosSystem helper and the isServer flag.

12. Modules In Depth -- What NixOS modules are, how they merge, how to read them, and how to write your own. Covers both simple config modules and modules with custom options.

13. specialArgs and the Inputs Pipeline -- How flake inputs and extra parameters travel from flake.nix into every module, and why this matters for external packages and the isServer flag.

How to Use This Manual

• If you need to do a specific task right now, start at Chapter 2 (Workflows) or Chapter 8 (Quick Reference).
• If you want to understand how the repo is organised, start at Chapter 1 (Configuration Structure).
• If something broke, go to Chapter 7 (Troubleshooting).
• If you want to understand electra's three boot tiers, go to Chapter 4 (Specialisations).
• If you want to understand the home server configuration, go to Chapter 3 (Host Configurations) — Vega section.
• If you are brand new to Nix and want to learn the language, start at Chapter 9 (The Nix Language) and work through Part 2.
• If you can already read Nix but want to understand the theory, start at Chapter 10 (Declarative Configuration).