From e326ea9d367e01745f7049d7bbc1535fcbbdb611 Mon Sep 17 00:00:00 2001 From: beatzaplenty Date: Wed, 15 Jul 2026 07:42:10 +1000 Subject: [PATCH] updated README --- README.md | 350 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 290 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 15619c5..cfaaa3b 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,59 @@ # Nix Auto Installer -This repository builds a custom NixOS installer ISO that can install one of the -hosts exposed by a separate NixOS flake. +This repository builds a custom NixOS installer environment that can automatically +install any host exposed by a separate NixOS flake. -The ISO is intentionally opinionated for a local environment. When the `nixos` -user logs in, it runs `/etc/auto-install.sh`, asks which flake host to install, -partitions `/dev/sda`, installs NixOS, and reboots. +The installer provides a small NixOS netboot/install environment with SSH access, +Git support, and an interactive installation script. When the `nixos` user logs +in, it runs `/etc/auto-install.sh`, discovers available hosts from the target +flake, allows the operator to choose a system profile, applies the matching +Disko storage configuration, installs NixOS, and reboots. + +The installer is designed for a mixed environment where different machines may +have different storage layouts, including Proxmox VMs, Linode instances, and +physical hardware. Disk layout is no longer hardcoded in the installer; it is +defined by each host's NixOS configuration using Disko. ## Repository Layout -- `flake.nix` defines the build output. The default package is an - `install-iso` image produced with `nixos-generators`. -- `installer.nix` defines the installer ISO configuration, including SSH, - Git credentials, users, and the generated auto-install script. +* `flake.nix` + + * Defines the installer build outputs. + * Builds an `install-iso` image using `nixos-generators`. + * Builds netboot kernel, initrd, and iPXE scripts. + +* `installer.nix` + + * Defines the installer environment. + * Enables SSH access. + * Configures Git access to the target flake repository. + * Creates the `nixos` and `root` users. + * Provides the generated `/etc/auto-install.sh` installation script. + +The installed system configuration lives in a separate NixOS flake. Each target +host is exposed through: + +```nix +nixosConfigurations. +``` + +and may optionally include a Disko storage configuration. ## Requirements -- A machine with Nix installed and flakes enabled. -- Network access to the configured NixOS flake repository. -- A target machine or VM where `/dev/sda` is the disk you want to erase. +The build machine requires: -## Build The ISO +* Nix installed with flakes enabled. +* Network access to fetch flake inputs. +* Ability to build NixOS images. + +The target machine requires: + +* Network connectivity during installation. +* A disk defined by its Disko configuration. +* SSH access or local console access. + +## Build The Installer ISO From the repository root: @@ -28,75 +61,272 @@ From the repository root: nix build ``` -The generated ISO will be available through the `result` symlink. +The generated installer ISO will be available through the `result` symlink. + +The ISO is generated using: + +```nix +nixos-generators.nixosGenerate { + format = "install-iso"; +} +``` + +## Build Netboot Components + +The flake also exposes netboot components: + +```sh +nix build .#netboot-ipxe +nix build .#netboot-initrd +nix build .#netboot-kernel +``` + +These can be used to PXE boot the installer environment. ## Use The Installer -1. Boot the generated ISO on the target machine. -2. Log in as the `nixos` user, or connect over SSH if networking is available. -3. The login shell runs `/etc/auto-install.sh`. -4. Choose one of the hosts returned by: +1. Boot the generated ISO or netboot environment on the target machine. + +2. Log in as the `nixos` user. + +3. The login shell launches: ```sh - nix eval --json --no-use-registries --no-accept-flake-config \ - "git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#nixosConfigurations" \ - --apply builtins.attrNames + /etc/auto-install.sh ``` -5. Confirm the install when prompted. +4. The installer queries the target flake: -## What The Installer Does + ```text + git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git + ``` -The generated `/etc/auto-install.sh` script: +5. Available installation profiles are discovered from: -1. Reads available host names from the configured flake. -2. Prompts for the host profile to install. -3. Asks for confirmation. -4. Repartitions `/dev/sda` with an MBR layout: - - `/dev/sda1`: ext4 root filesystem labeled `nixos` - - `/dev/sda2`: swap partition labeled `swap` -5. Mounts the new root filesystem at `/mnt`. -6. Runs `nixos-install --flake`. -7. Reboots the machine. + ```nix + nixosConfigurations + ``` + +6. Select the host profile to install. + +7. Confirm the installation. + +8. The installer applies the selected host's Disko storage layout. + +9. NixOS is installed using the selected flake configuration. + +10. The system reboots into the installed OS. + +## Storage Management + +Disk partitioning is handled by Disko. + +The installer no longer contains hardcoded commands such as: + +```sh +parted +mkfs.ext4 +mkswap +mount +``` + +Instead, each NixOS host defines its own storage layout. + +Example: + +```nix +{ + disko.devices = { + disk.main = { + type = "disk"; + device = "/dev/sda"; + + content = { + type = "gpt"; + + partitions = { + root = { + size = "-8G"; + + content = { + type = "filesystem"; + format = "ext4"; + mountpoint = "/"; + }; + }; + + swap = { + size = "100%"; + + content = { + type = "swap"; + }; + }; + }; + }; + }; + }; +} +``` + +This allows different hosts to define different layouts: + +* Proxmox VMs +* Linode instances +* Physical servers +* ZFS systems +* Future hardware-specific layouts + +A host without a Disko configuration will not be automatically partitioned. + +## Installer Process + +The generated `/etc/auto-install.sh` performs the following steps: + +1. Fetch available hosts from the configured NixOS flake. + +2. Present available `nixosConfigurations` as a menu. + +3. Confirm the selected installation target. + +4. Check whether the selected host has a Disko configuration. + +5. Run: + + ```sh + disko --mode destroy,format,mount --flake # + ``` + +6. Prepare `/mnt` using the Disko-generated mount configuration. + +7. Install NixOS: + + ```sh + nixos-install \ + --flake # \ + --no-root-password + ``` + +8. Remove temporary installation files. + +9. Reboot. ## Configuration Notes The installer currently assumes: -- The flake to install is - `git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git`. -- Install targets are exposed under `#nixosConfigurations`. -- The install disk is always `/dev/sda`. -- The timezone is `Australia/Brisbane`. -- SSH is enabled and root login is permitted. -- The generated ISO has both `root` and `nixos` users configured with hashed - passwords. +* Target flake: -Change these values in `installer.nix` before building if your environment -differs. + ```text + git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git + ``` + +* Host definitions are under: + + ```nix + nixosConfigurations + ``` + +* The installer has network access before installation. + +* SSH is enabled. + +* Root SSH login is permitted. + +* The timezone is: + + ```text + Australia/Brisbane + ``` + +* The target host is responsible for defining its own storage layout. + +Change these values in `installer.nix` if your environment differs. + +## Security Notes + +`installer.nix` currently contains: + +* Git credentials +* Password hashes +* SSH public keys + +Treat the repository and generated installer images as sensitive. + +For production use, consider replacing embedded credentials with: + +* Short-lived tokens +* SSH deploy keys +* External secrets management +* Runtime credential injection ## Safety Warnings -This installer is destructive. Once confirmed, it repartitions `/dev/sda` -without another prompt. Make sure the target disk name is correct before using -the ISO on real hardware. +This installer is destructive. -`installer.nix` currently contains embedded Git credentials, password hashes, -and an SSH public key. Treat this repository and any generated ISO as sensitive. -Prefer moving credentials to a safer delivery mechanism before sharing the repo -or ISO. +The command: + +```sh +disko --mode destroy,format,mount +``` + +will erase any disks defined by the selected host's Disko configuration. + +Always verify: + +* The selected host profile. +* The Disko device paths. +* The target machine. + +Never boot this installer on a machine containing important data unless the +storage configuration has been reviewed. ## Troubleshooting -- If no host choices appear, confirm the target machine has network access and - can reach the configured flake URL. -- If installation fails while fetching the flake, verify the embedded Git - credentials are valid. -- If the wrong disk is being partitioned, stop immediately and update the disk - paths in `installer.nix`. -- If the login shell does not start the installer, run it manually: +### No hosts appear in the menu - ```sh - sudo /etc/auto-install.sh - ``` +Check that the installer can reach the flake repository: +```sh +nix eval --json \ + "git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#nixosConfigurations" \ + --apply builtins.attrNames +``` + +### Selected host has no Disko configuration + +The installer checks for: + +```nix +config.disko.devices +``` + +Hosts without Disko storage definitions must either: + +* Add a Disko module, or +* Be installed using another storage method. + +### Disko evaluation fails + +Check the selected host locally: + +```sh +nix eval \ + ".#nixosConfigurations..config.disko.devices" +``` + +### Installation fails fetching the flake + +Verify: + +* Network connectivity. +* Git credentials. +* Flake input availability. + +### Installer does not start automatically + +Run manually: + +```sh +sudo /etc/auto-install.sh +```