inline docs

artifacts.nix

@@ -1,10 +1,14 @@
 { inputs, hosts, self, system }:
+# This file defines the logic for generating various build artifacts (ISOs, Netboot, LXC, etc.)
+# It exports a set of packages that can be built using `nix build .#<artifact-name>`
 let
   nixpkgs = inputs.nixpkgs;
   lib = nixpkgs.lib;
   pkgs = nixpkgs.legacyPackages.${system};
   nixos-generators = inputs.nixos-generators;
 
+  # Creates a self-installing ISO for a specific host configuration
+  # This ISO will automatically partition the disk (using disko) and install the system
   mkInstaller = hostName:
     let
       targetConfig = self.nixosConfigurations.${hostName}.config;
@@ -24,6 +28,7 @@ let
       ];
     };
 
+  # Uses nixos-generators to create artifacts like LXC containers, Proxmox VMA, or Live ISOs
   mkGenerator = hostName: format:
     nixos-generators.nixosGenerate {
       inherit system;
@@ -37,6 +42,8 @@ let
       inherit format;
     };
 
+  # Creates Netboot (iPXE) artifacts using the native NixOS netboot module
+  # Returns a system configuration that includes the netboot module
   mkNetboot = hostName:
     nixpkgs.lib.nixosSystem {
       inherit system;
@@ -52,6 +59,7 @@ let
 
   hostNames = builtins.attrNames hosts.nixosConfigurations;
 
+  # Generate installer ISOs for hosts that have "installer-iso" in their buildMethods
   installerPackages = lib.listToAttrs (lib.concatMap (name:
     let cfg = hosts.nixosConfigurations.${name}; in
     if lib.elem "installer-iso" cfg.config.host.buildMethods then [{
@@ -60,6 +68,7 @@ let
     }] else []
   ) hostNames);
 
+  # Generate Live ISOs for hosts that have "iso" in their buildMethods
   isoPackages = lib.listToAttrs (lib.concatMap (name:
     let cfg = hosts.nixosConfigurations.${name}; in
     if lib.elem "iso" cfg.config.host.buildMethods then [{
@@ -68,6 +77,7 @@ let
     }] else []
   ) hostNames);
 
+  # Generate iPXE artifacts (kernel, initrd, script) for hosts that have "ipxe" in their buildMethods
   ipxePackages = lib.listToAttrs (lib.concatMap (name:
     let cfg = hosts.nixosConfigurations.${name}; in
     if lib.elem "ipxe" cfg.config.host.buildMethods then [{
@@ -87,6 +97,7 @@ let
     }] else []
   ) hostNames);
 
+  # Generate LXC tarballs for hosts that have "lxc" in their buildMethods
   lxcPackages = lib.listToAttrs (lib.concatMap (name:
     let cfg = hosts.nixosConfigurations.${name}; in
     if lib.elem "lxc" cfg.config.host.buildMethods then [{

hosts/boot.nix

@@ -26,7 +26,15 @@
     buildMethods = lib.mkOption {
       type = lib.types.listOf lib.types.str;
       default = [ "installer-iso" ];
-      description = "List of allowed build methods (installer-iso, iso, ipxe, lxc, proxmox).";
+      description = ''
+        List of allowed build methods for this host.
+        Supported methods:
+        - "installer-iso": Generates an auto-install ISO that installs this configuration to disk.
+        - "iso": Generates a live ISO (using nixos-generators).
+        - "ipxe": Generates iPXE netboot artifacts (kernel, initrd, script).
+        - "lxc": Generates an LXC container tarball.
+        - "proxmox": Generates a Proxmox VMA archive.
+      '';
     };
   };
 

hosts/types/nix-ephemeral.nix

@@ -8,6 +8,8 @@
       ...
     }:
     {
+      # This host type is for ephemeral, diskless systems (e.g. kiosks, netboot clients).
+      # It runs entirely from RAM and does not persist state across reboots.
       imports = [ (modulesPath + "/installer/scan/not-detected.nix") ];
 
       boot.initrd.availableKernelModules = [

installer/auto-install.nix

@@ -1,3 +1,6 @@
+# This module defines a systemd service that automatically installs NixOS to the disk.
+# It is intended to be used in an installation ISO.
+# It expects `targetSystem` (the closure to install) and `diskoScript` (the partitioning script) to be passed as arguments.
 { config, lib, pkgs, inputs, hostName, hostPlatform, targetSystem, diskoScript, ... }:
 {
   environment.systemPackages = [

sw/stateless-kiosk/default.nix

@@ -1,3 +1,5 @@
+# This module defines the software stack for a stateless kiosk.
+# It includes a custom Firefox wrapper, Cage (Wayland kiosk compositor), and specific networking configuration.
 {
   config,
   lib,

sw/stateless-kiosk/kiosk-browser.nix

@@ -1,3 +1,6 @@
+# This module configures Firefox for kiosk mode.
+# It wraps Firefox with specific policies to disable UI elements and lock down the browser.
+# It also includes a startup script that determines the kiosk URL based on the machine's MAC address.
 { config, lib, pkgs, ... }:
 
 let
@@ -49,6 +52,7 @@ let
 
     BASE="http://homeassistant.lan:8123"
 
+    # Helper to find the primary MAC address
     get_primary_mac() {
       for dev in /sys/class/net/*; do
         iface="$(basename "$dev")"
@@ -64,6 +68,7 @@ let
     MAC="$(get_primary_mac 2>/dev/null || echo "")"
     MAC="$(echo "$MAC" | tr '[:upper:]' '[:lower:]')"
 
+    # Map MAC addresses to specific station IDs
     case "$MAC" in
       "00:e0:4c:46:0b:32") STATION="1" ;;
       "00:e0:4c:46:07:26") STATION="2" ;; 

sw/stateless-kiosk/net.nix

@@ -1,3 +1,5 @@
+# This module configures the network for the stateless kiosk.
+# It uses systemd-networkd to set up a VLAN (ID 5) on the primary interface.
 { config, lib, pkgs, inputs, ... }:
 {
   # Minimal container networking (systemd-networkd)