Archived
updated README
This commit is contained in:
@@ -1,26 +1,59 @@
|
|||||||
# Nix Auto Installer
|
# Nix Auto Installer
|
||||||
|
|
||||||
This repository builds a custom NixOS installer ISO that can install one of the
|
This repository builds a custom NixOS installer environment that can automatically
|
||||||
hosts exposed by a separate NixOS flake.
|
install any host exposed by a separate NixOS flake.
|
||||||
|
|
||||||
The ISO is intentionally opinionated for a local environment. When the `nixos`
|
The installer provides a small NixOS netboot/install environment with SSH access,
|
||||||
user logs in, it runs `/etc/auto-install.sh`, asks which flake host to install,
|
Git support, and an interactive installation script. When the `nixos` user logs
|
||||||
partitions `/dev/sda`, installs NixOS, and reboots.
|
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
|
## Repository Layout
|
||||||
|
|
||||||
- `flake.nix` defines the build output. The default package is an
|
* `flake.nix`
|
||||||
`install-iso` image produced with `nixos-generators`.
|
|
||||||
- `installer.nix` defines the installer ISO configuration, including SSH,
|
* Defines the installer build outputs.
|
||||||
Git credentials, users, and the generated auto-install script.
|
* 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.<hostname>
|
||||||
|
```
|
||||||
|
|
||||||
|
and may optionally include a Disko storage configuration.
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
- A machine with Nix installed and flakes enabled.
|
The build machine requires:
|
||||||
- Network access to the configured NixOS flake repository.
|
|
||||||
- A target machine or VM where `/dev/sda` is the disk you want to erase.
|
|
||||||
|
|
||||||
## 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:
|
From the repository root:
|
||||||
|
|
||||||
@@ -28,75 +61,272 @@ From the repository root:
|
|||||||
nix build
|
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
|
## Use The Installer
|
||||||
|
|
||||||
1. Boot the generated ISO on the target machine.
|
1. Boot the generated ISO or netboot environment 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`.
|
2. Log in as the `nixos` user.
|
||||||
4. Choose one of the hosts returned by:
|
|
||||||
|
3. The login shell launches:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
nix eval --json --no-use-registries --no-accept-flake-config \
|
/etc/auto-install.sh
|
||||||
"git+https://gitea.lan.ddnsgeek.com/beatzaplenty/nixos.git#nixosConfigurations" \
|
|
||||||
--apply builtins.attrNames
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
```nix
|
||||||
2. Prompts for the host profile to install.
|
nixosConfigurations
|
||||||
3. Asks for confirmation.
|
```
|
||||||
4. Repartitions `/dev/sda` with an MBR layout:
|
|
||||||
- `/dev/sda1`: ext4 root filesystem labeled `nixos`
|
6. Select the host profile to install.
|
||||||
- `/dev/sda2`: swap partition labeled `swap`
|
|
||||||
5. Mounts the new root filesystem at `/mnt`.
|
7. Confirm the installation.
|
||||||
6. Runs `nixos-install --flake`.
|
|
||||||
7. Reboots the machine.
|
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 <flake>#<host>
|
||||||
|
```
|
||||||
|
|
||||||
|
6. Prepare `/mnt` using the Disko-generated mount configuration.
|
||||||
|
|
||||||
|
7. Install NixOS:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
nixos-install \
|
||||||
|
--flake <flake>#<host> \
|
||||||
|
--no-root-password
|
||||||
|
```
|
||||||
|
|
||||||
|
8. Remove temporary installation files.
|
||||||
|
|
||||||
|
9. Reboot.
|
||||||
|
|
||||||
## Configuration Notes
|
## Configuration Notes
|
||||||
|
|
||||||
The installer currently assumes:
|
The installer currently assumes:
|
||||||
|
|
||||||
- The flake to install is
|
* Target flake:
|
||||||
`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.
|
|
||||||
|
|
||||||
Change these values in `installer.nix` before building if your environment
|
```text
|
||||||
differs.
|
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
|
## Safety Warnings
|
||||||
|
|
||||||
This installer is destructive. Once confirmed, it repartitions `/dev/sda`
|
This installer is destructive.
|
||||||
without another prompt. Make sure the target disk name is correct before using
|
|
||||||
the ISO on real hardware.
|
|
||||||
|
|
||||||
`installer.nix` currently contains embedded Git credentials, password hashes,
|
The command:
|
||||||
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
|
```sh
|
||||||
or ISO.
|
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
|
## Troubleshooting
|
||||||
|
|
||||||
- If no host choices appear, confirm the target machine has network access and
|
### No hosts appear in the menu
|
||||||
can reach the configured flake URL.
|
|
||||||
- If installation fails while fetching the flake, verify the embedded Git
|
Check that the installer can reach the flake repository:
|
||||||
credentials are valid.
|
|
||||||
- If the wrong disk is being partitioned, stop immediately and update the disk
|
```sh
|
||||||
paths in `installer.nix`.
|
nix eval --json \
|
||||||
- If the login shell does not start the installer, run it manually:
|
"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.<host>.config.disko.devices"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installation fails fetching the flake
|
||||||
|
|
||||||
|
Verify:
|
||||||
|
|
||||||
|
* Network connectivity.
|
||||||
|
* Git credentials.
|
||||||
|
* Flake input availability.
|
||||||
|
|
||||||
|
### Installer does not start automatically
|
||||||
|
|
||||||
|
Run manually:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
sudo /etc/auto-install.sh
|
sudo /etc/auto-install.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user