diff --git a/artifacts.nix b/artifacts.nix index 9b4e0cf..139d35d 100644 --- a/artifacts.nix +++ b/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 .#` 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 [{ diff --git a/hosts/boot.nix b/hosts/boot.nix index 86fa595..33006ea 100644 --- a/hosts/boot.nix +++ b/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. + ''; }; }; diff --git a/hosts/types/nix-ephemeral.nix b/hosts/types/nix-ephemeral.nix index c8043c7..5deba70 100644 --- a/hosts/types/nix-ephemeral.nix +++ b/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 = [ diff --git a/installer/auto-install.nix b/installer/auto-install.nix index bb152a6..c4a3f5d 100644 --- a/installer/auto-install.nix +++ b/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 = [ diff --git a/sw/stateless-kiosk/default.nix b/sw/stateless-kiosk/default.nix index 7bc0f16..99b4a6a 100644 --- a/sw/stateless-kiosk/default.nix +++ b/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, diff --git a/sw/stateless-kiosk/kiosk-browser.nix b/sw/stateless-kiosk/kiosk-browser.nix index 89bc8c2..e34d039 100644 --- a/sw/stateless-kiosk/kiosk-browser.nix +++ b/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" ;; diff --git a/sw/stateless-kiosk/net.nix b/sw/stateless-kiosk/net.nix index e0387f1..7f1d222 100644 --- a/sw/stateless-kiosk/net.nix +++ b/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)