nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 51 Guided Repository Tour
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
2 51 Guided Repository Tour
Nimmo edited this page 2026-09-13 13:14:49 +01:00
Table of contents

Guided Repository Tour

  • Type: Tutorial
  • Status: Current
  • Scope: First reading path through the registered nixos-config flake
  • Canonical sources: flake.nix; hosts/electra/default.nix; hosts/vega/default.nix; modules/common/base.nix; modules/profiles/; modules/services/; home/users/nimmo/default.nix; lib/auto-update-policy.nix; Repository Structure and Import Chain
  • Last verified: Source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12); source HEAD b2831d33132967b4c4fb69e6068b2b05fff8fdff changes only flake.lock. Builder and selected imports checked 2026-09-13; no configuration was activated.
  • Review triggers: Flake outputs or builder, host registration/imports, Home Manager entry point, profile ownership, inventory fields, or updater input policy

Learning goal and prerequisites

Follow one host from the flake entry point to its NixOS modules and Home Manager user configuration. You need only basic Git and Linux familiarity; the rest of this path teaches Nix syntax and module merging. Read files in the source checkout, not a dated export. The repository is authoritative; this page is a map for learning, not a second configuration inventory.

Walk the composition

  1. Open flake.nix. Its inputs name external sources; flake.lock pins their resolved revisions. Under outputs, find nixosConfigurations. The currently registered targets are Electra, Lena, Vega, Lyra, Cosmos, and Chaos. potential/nova is staged and not in that set. Its presence does not prove Nova runs NixOS; Nova currently runs Fedora.
  2. Pick vega = makeNixosSystem { configName = "vega"; };. The shared makeNixosSystem builder supplies SOPS, Home Manager, Paseo, the standalone updater, cache settings, and the host import ./hosts/${configName}. Cosmos and Chaos instead pass the stable Nixpkgs and matching Home Manager inputs to this same builder.
  3. Open hosts/vega/default.nix. Its imports compose common and server foundations, hardware/Disko files, selected service modules, networking, and the system user. The host sets networking.hostName, inventory metadata under nixosConfig.host, host storage, and service values. An imported module can be option-gated: its presence in imports alone may not enable the service. Trace an actual nixosConfig.<service>.enable value before saying a service is declared active.
  4. Follow one import, for example modules/services/bookstack.nix from Vega. Its option declaration defines the interface; its config = mkIf cfg.enable { ... }; contributes runtime state, SOPS paths, listener, backup intent, and monitoring only when enabled. Contrast an import-to-enable module in modules/profiles/. The Configuration Ownership Boundaries page explains why a host selects and parameterises reusable capabilities rather than copying every service implementation inline.
  5. Return to flake.nix and find home-manager.users.${config.nixosConfig.primaryUser}. It imports home/users/<primaryUser>/ for every registered host. In home/users/nimmo/default.nix, the desktop import is conditional on isServer, an argument supplied through home-manager.extraSpecialArgs. This is a separate Home Manager argument path from NixOS specialArgs.
  6. Look at lib/auto-update-policy.nix. Root flake inputs are classified by actual consuming hosts so the update pipeline validates the right targets. Adding an input or host is not complete merely when the flake evaluates; the guarded update surface must also be reviewed.

A safe exercise

Choose one registered host and one service or profile it imports. Without editing or deploying, write down: (a) the flake target, (b) the host entry module, (c) the selected import, (d) any enable option, and (e) the runtime or package declaration. Check your chain against Repository Structure and Import Chain and the relevant current Service Catalogue entry.

Then compare Electra's hosts/electra/default.nix with Vega's. Electra's base and igpu/dgpu specialisations are one registered target, not three flake outputs. The specialisations describe physical GPU presence; do not switch modes as a workload preference. ADR-001 explains why, and Safe Testing and Deployment owns activation rules.

Common mistakes and next reading

  • An import says where configuration may enter; check mkIf, options, assertions, and host values before claiming a unit exists.
  • flake.lock pins build inputs, but mutable services, external data, SOPS values, and deployment state are not contained in that file. A build is not proof of live health.
  • Untracked files are omitted from Git-backed flake evaluation. Stage a new .nix file before testing; do not need to change any file for this tour.

Next in this learning sequence is Nix Language Essentials; use the official Nix language basics for deeper language study. For the complete current architecture use the Engineering Handbook, not the retired generic course chapters in wiki Git history.