Automated NixOS CLI Installer

NixOS is traditionally either installed by creating and populating filesystems by hand, or by scripts that each only support one or a limited set of filesystem setups (the graphical installer falls somewhere between the two). The mounted filesystems and some hardware aspects are then be captured in a hardware-configuration.nix. This both completely contradicts the declarative nature and flexibility of Nix(OS).

In contrast to that, this flake implements a very flexible, declaratively driven and fully automated NixOS installer (framework). Hosts can define any number of disks and partitions on them. If the fileSystems use partlabels to identify their devices, then they can be associated with their partitions even before they are formatted -- and can thus automatically be formatted during the installation. ZFS pools and datasets, and LUKS and ZFS encryption are also supported. For setups with ephemeral / (root filesystem), modules/setup/temproot.nix.md provides various preconfigured setups. This, together with convenient defaults for most of the options, means that simple setups (see the minimal example) only require a handful of config lines, while complex multi-disk setups (see the raidz example) are just as possible.

A set of composable setup-scripts can then automatically grab this information and perform a completely automated installation. The only thing that the scripts will interactively prompt for are external secrets (e.g., passwords), iff required by the new host. When using mkSystemsFlake, the installation can be started with:

nix run .'#'hostname -- install-system /path/to/disk

Help output with information on available commands and flags is available here or via:

nix run .'#'hostname -- --help

config.installer.commands.* can be used to run host-specific commands at various points of the installation, and additional config.installer.scripts can add or replace new and existing setup commands or functions. This mechanism has been used to, for example, automatically deploy locally built system images tp Hetzner VPSes.

Repo Layout/Contents

This is a nix flake repository, so flake.nix is the entry point and export mechanism for almost everything.

lib/ defines new library functions which are exported as the lib flake output. Other Nix files in this repo use them as inputs.self.lib.
setup-scripts contains the implementation for the default setup (system installation and maintenance) commands.

modules/ contains NixOS configuration modules. bootloader/extlinux enables extlinux as alternative bootloader for legacy BIOS environments, because GRUB refuses top be installed to loop-mounted images. The modules in setup allow defining a NixOS system's disk and filesystem setup in sufficient detail that a fully automatic installation is possible. The installer module composes the setup-scripts and the host's config into its individual installer.

There is currently only one overlay that applies a patch to sgdisk (it allows moving the backup GPT table, see gptfdisk #32).

hosts/example provides some NixOS host definitions that demonstrate different types of disk setups.

example/ contains examples for customizing the installation script for the hosts, and this flake's default config.

License

All files in this repository (nixos-installer), except ./LICENSE, are authored by the authors of this repository, and are copyright 2022 - present Niklas Gollenstede.

See patches/README.md#license for the licensing of the included patches. All other parts of this software may be used under the terms of the MIT license, as detailed in ./LICENSE.

This license applies to the files in this repository only. Any external packages are built from sources that have their own licenses, which should be the ones indicated in the package's metadata.