nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 29 Pull requests Wiki Activity Actions
Page: Home
Pages
01 Configuration Structure 02 Workflows 03 Host Configurations 04 Specialisations 05 Package Management 06 Secrets Management 07 Troubleshooting 08 Quick Reference 09 Nix Language 10 Declarative Configuration 11 Flakes 12 Modules 13 Specialargs 20 Disaster Recovery 21 Electra Secure Boot 22 Wrapper Repo Service Packaging 23 Project Tracking 24 Security Baseline Home
13 Home
Nimmo edited this page 2026-07-29 21:41:36 +01:00
Table of contents

NixOS Configuration Wiki

This wiki is the durable operating knowledge for nixos-config. It combines a structured NixOS learning manual with playbooks, recovery procedures, and governance references derived from completed project work.

The repository remains the source of truth for configuration. Forgejo milestones and issues track work that is planned or in progress; reusable knowledge produced by that work belongs here.

Last synced with nixos-config commit: 875ac08927aa55a8783c4657c87a6cf7a16e8877.

Operational Playbooks

  • Disaster Recovery -- Restore hosts and user data, including Electra's Secure Boot and TPM recovery prerequisites.
  • Electra Secure Boot -- Implementation record, validation procedure, rollback guidance, and TPM policy recovery.
  • Wrapper-Repo Service Packaging -- Package an awkward upstream service through a dedicated wrapper repository and integrate it with NixOS.

Governance and Reference

  • Project Tracking -- How milestones, issues, labels, and wiki pages divide responsibility for planned work and durable knowledge.
  • Security Baseline -- Current controls, accepted boundaries, and the security review gate for hosts and services.

Learning Manual

The manual is organised in two parts. Part 1 covers practical day-to-day configuration. Part 2 explains the Nix language, module system, and underlying model. It uses the live repository as its primary teaching material.

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 four hosts in detail: electra (three-tier laptop), lena (family laptop), vega (home server), and lyra (GPU compute 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

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

Part 2: How NixOS Works

  1. 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.

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

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

  4. 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.

  5. 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 are responding to an outage or data loss, start with Disaster Recovery.
  • If you are planning or reviewing work, use Project Tracking and the Security Baseline.
  • 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).