nix-auto-installer/README.md

Nix Auto Installer

This repository builds a custom NixOS installer environment that can automatically install any host exposed by a separate NixOS flake.

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 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:

nixosConfigurations.<hostname>

and may optionally include a Disko storage configuration.

Requirements

The build machine requires:

• 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:

nix build

The generated installer ISO will be available through the result symlink.

The ISO is generated using:

nixos-generators.nixosGenerate {
  format = "install-iso";
}

Build Netboot Components

The flake also exposes netboot components:

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 or netboot environment on the target machine.

2. Log in as the nixos user.

3. The login shell launches:

   /etc/auto-install.sh
   

4. The installer queries the target flake:

   git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git
   

5. Available installation profiles are discovered from:

   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:

parted
mkfs.ext4
mkswap
mount

Instead, each NixOS host defines its own storage layout.

Example:

{
  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:

   disko --mode destroy,format,mount --flake <flake>#<host>
   

6. Prepare /mnt using the Disko-generated mount configuration.

7. Check for a pre-seeded SSH host key at /root/host-keys/<host>_ssh_host_ed25519_key and install it to /mnt/etc/ssh/ if present (see "Pre-Seeding SSH Host Keys for sops-nix" below) — prompts for confirmation before continuing without one.

8. Install NixOS:

   nixos-install \
     --flake <flake>#<host> \
     --no-root-password
   

9. Remove temporary installation files.

10. Reboot.

Pre-Seeding SSH Host Keys for sops-nix

The nixos flake manages secrets with sops-nix, using an age key derived from each host's own /etc/ssh/ssh_host_ed25519_key. That key is normally generated by a systemd service (sshd-keygen) the first time a host boots — but sops-nix decrypts secrets (including the login password) earlier than that, during system activation, which runs before systemd starts pursuing the target that sshd-keygen is gated behind. On a genuinely fresh install, this means secrets fail to decrypt on the very first boot unless the host key already exists beforehand.

To avoid this, generate the key ahead of time and register it with the nixos flake's sops-nix setup before installing:

./scripts/prepare-host-key.sh <hostname> [path-to-nixos-repo]

This generates host-keys/<hostname>_ssh_host_ed25519_key(.pub) locally and prints the exact steps to add its derived age key to nixos/.sops.yaml, re-encrypt the relevant secrets/*.yaml files with sops updatekeys, and commit + push the nixos repo.

Once that's done and the target machine is booted into the installer, copy the generated key onto it before running (or continuing) /etc/auto-install.sh:

scp host-keys/<hostname>_ssh_host_ed25519_key{,.pub} root@<target-ip>:/root/host-keys/

auto-install.sh checks for this file automatically and installs it to the target's /mnt/etc/ssh/ before running nixos-install. If it's missing, the script warns and asks for confirmation before continuing — useful for hosts that don't consume any sops-nix secrets, but skipping it for a host that does will lock secrets out of decrypting on first boot.

host-keys/ is gitignored — never commit private key material.

Configuration Notes

The installer currently assumes:

• Target flake:

  git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git
  

• Host definitions are under:

  nixosConfigurations
  

• The installer has network access before installation.

• SSH is enabled.

• Root SSH login is permitted.

• The timezone is:

  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.

The command:

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

No hosts appear in the menu

Check that the installer can reach the flake repository:

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:

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:

nix eval \
  ".#nixosConfigurations.<host>.config.disko.devices"

Installation fails fetching the flake

Verify:

• Network connectivity.
• Git credentials.
• Flake input availability.

Installer does not start automatically

Run manually:

sudo /etc/auto-install.sh