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: 21 ADR 001 Electra Hardware Specialisations
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 21 ADR 001 Electra Hardware Specialisations
Nimmo edited this page 2026-09-13 13:14:49 +01:00
Table of contents

ADR-001: Electra hardware-presence specialisations in one system generation

  • Status: Accepted
  • Date: 2026-02-18
  • Scope: Electra NixOS configuration, GPU hardware profiles, and deployment behavior
  • Supersedes: None
  • Superseded by: None

Context

Electra is a Framework 16 whose NVIDIA expansion bay is physically removable. The system therefore needs configurations for two different hardware states: AMD integrated graphics only, and AMD/NVIDIA hybrid graphics. It also benefits from a low-power base that omits the full performance and desktop workload set.

The repository originally represented the iGPU and dGPU states as separate flake targets. That duplicated a single physical host, allowed their generations to drift, and required an alternate-configuration rebuild/synchronisation unit plus special garbage-collection protection merely to keep both boot choices available.

Commit 6f772ce replaced those targets with one electra configuration and a dGPU NixOS specialisation. Commit 8ce867f subsequently made the battery tier the base and expressed both full-featured hardware states as specialisations. Commit a5eaf18 made explicit that igpu and dgpu describe installed hardware, not a performance preference. The current implementation preserves that model.

Decision

Electra has one nixosConfigurations.electra target. Every rebuild produces a single NixOS generation containing three related boot entries:

  • the base battery tier, using the always-present AMD hardware and the conservative endurance configuration;
  • igpu, used when the NVIDIA expansion bay is absent;
  • dgpu, used when the NVIDIA expansion bay is installed and importing the matching NVIDIA hardware module.

Configuration shared by all three tiers belongs in the base. A specialisation contains only behavior that differs for that hardware/power tier. In particular, igpu and dgpu are selected from physical hardware presence; they must not be presented as interchangeable workload or performance modes.

Deployment and update tooling must address the hostname-level flake target and preserve or reactivate the running specialisation. Boot selection must retain the latest entry for the chosen tier across generations.

Consequences

  • All valid hardware states are built and garbage-collected as one generation, so the boot menu cannot silently retain an unrelated stale target.
  • Shared configuration has one owner and ordinary changes cannot drift between duplicate Electra flake configurations.
  • The alternate-target synchronisation service and its generation-protection workaround are unnecessary.
  • The battery base is the least-capable common configuration. Full-featured specialisations add capabilities rather than relying on extensive forced overrides to remove them.
  • A normal Electra build pays the evaluation/build cost of all three boot variants. Secure/measured-boot policy must also account for every retained variant and generation.
  • Raw test or switch commands that activate the base can unexpectedly leave a running igpu or dgpu session in the wrong tier. Project tooling therefore detects and reapplies the active specialisation.
  • Hardware-specific changes require validation in the affected specialisation; success in the base alone is insufficient.

Alternatives considered

Separate flake configurations for iGPU and dGPU

Rejected. They modelled one machine as two deployment targets, duplicated shared state, and needed continuing machinery to rebuild, retain, and align the inactive target.

One configuration selected entirely at runtime

Rejected for the removable NVIDIA case. Driver modules, hardware declarations, and boot-time behavior differ before an ordinary user session can choose a workload policy. Explicit boot entries make the installed-hardware assumption visible and recoverable.

Treat iGPU and dGPU as performance preferences

Rejected. The dGPU path requires hardware that may be physically absent; the iGPU path is the correct full-featured system in that state. Workload policy belongs in profiles or power controls, not in a false description of installed hardware.

Keep a full-featured iGPU base and subtract features for battery mode

Replaced during refinement of the decision. Making the conservative battery tier the base reduced priority overrides and lets the other tiers add their gaming, maker, power, and GPU capabilities.

References

  • Current implementation: flake.nix, hosts/electra/default.nix, hosts/electra/hardware.nix, and hosts/electra/hardware-dgpu.nix
  • Current-state reference: Host Inventory
  • Worked example: Electra Specialisations; operational context: Safe Testing and Deployment
  • Initial unification: repository commit 6f772ce76c1a0af96c87786277e2d8c2477d5174
  • Battery-base refinement: repository commit 8ce867f34048f23664d2e33564c0a8ef567bd1c9
  • Hardware-presence clarification: repository commit a5eaf18c2805d2b015b96504be069266623a9a93