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: 57 Electra Specialisations Worked Example
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
1 57 Electra Specialisations Worked Example
Nimmo edited this page 2026-09-13 13:08:31 +01:00
Table of contents

Electra Specialisations: A Worked Example

  • Type: Tutorial
  • Status: Current
  • Scope: Reading Electra's base, igpu, and dgpu module compositions without changing its boot mode
  • Canonical sources: flake.nix; hosts/electra/default.nix; hosts/electra/hardware-dgpu.nix; justfiles/deploy.just; ADR-001; Safe Testing and Deployment
  • Last verified: Source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12); source HEAD b2831d33132967b4c4fb69e6068b2b05fff8fdff changes only flake.lock. Electra declarations and test/switch recipes checked 2026-09-13; no mode was changed.
  • Review triggers: Electra specialisation imports/labels, GPU bay rule, boot trust/PCR policy, deployment wrappers, or hardware profile composition

Learning goal and prerequisites

Use one real host to see how NixOS modules merge a base configuration with specialisation-specific definitions. Read NixOS Modules and Option Merging first. ADR-001 owns the design rationale. This is a read-only lesson, not instructions to select a boot entry or re-enrol TPM policies.

One host target, three built variants

flake.nix registers exactly one nixosConfigurations.electra target. hosts/electra/default.nix provides its base: common laptop and hardware imports, Disko, networking, the low-power/endurance settings, and a nixos-specialisation file containing battery. The same file defines specialisation.igpu.configuration and specialisation.dgpu.configuration. They extend the base in one NixOS generation; they are not separate flakes, channels, or independently updated host targets.

The base is the battery-optimised tier. igpu enables the fuller desktop, gaming/maker/Ollama profile set while the removable NVIDIA expansion bay is absent. dgpu is the corresponding full tier when that physical bay is installed. Their names encode hardware presence, not a wish for more performance on the same hardware. Do not boot dgpu without the bay or choose igpu merely to avoid using an installed bay. This safety rule is repeated in AGENTS.md, the ADR, and the deployment runbook.

Trace the merge

In hosts/electra/default.nix, the two specialisations both use sharedSpecialisationImports, containing gaming, maker, and Ollama profiles. Those imports are absent from the base. Both override the base mode file and selected power settings with lib.mkForce, because a specialisation inherits the base definitions and must deliberately replace some single-valued settings. The DGPU configuration adds the NVIDIA nixos-hardware module and ./hardware-dgpu.nix, declares NVIDIA availability, and adds DGPU-specific device/service settings. Put an ordinary all-tier setting in the base; put hardware-presence changes only in the relevant specialisation.

Electra's boot trust is more than a label. The base enables Lanzaboote and measured boot, while the DGPU branch handles its different PCR behaviour. Changing the bootloader, encryption, TPM, or DGPU policy is a recovery-risk change, not a tutorial exercise. Electra Boot-Trust and TPM Recovery owns the operational path.

The repository's just test and just build-diff recipes read /etc/nixos-specialisation and use the corresponding specialisation inside the built top-level by default. That is why a generic raw test command is not the project default. A deliberate physical mode change has its own reviewed procedure in Safe Testing and Deployment; just switch-spec affects boot selection and must not be used simply to complete this lesson.

Guided check

Without activating anything, find the base laptop.enduranceMode.enable value, then the igpu and dgpu overrides. Find one profile imported by both specialisations and one hardware module imported only by dgpu. Finally locate the just test logic that selects the active mode. Explain why changing a shared package in the base affects all three variants, while changing ./hardware-dgpu.nix should affect only the DGPU branch.

Common mistakes: counting three flake targets, assuming the specialisations can be rolled out separately, treating the mode as a workload switch, or using a NixOS generation rollback as a substitute for TPM/key recovery.