athenix/docs/BUILDING.md

Building Installation Media

This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake.

Table of Contents

• Quick Start
• Available Artifacts
• Installer ISOs
• Live ISOs
• Container Images
• Remote Builders
• Troubleshooting

Quick Start

# Build an installer ISO for a specific host
nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1

# Result will be in result/iso/
ls -lh result/iso/

Available Artifacts

List all available build outputs:

nix flake show github:UGA-Innovation-Factory/nixos-systems

Common artifact types:

Artifact Type	Description	Example
installer-iso-*	Auto-install ISO that installs configuration to disk	installer-iso-nix-laptop1
iso-*	Live ISO (bootable without installation)	iso-nix-ephemeral1
ipxe-*	iPXE netboot artifacts (kernel, initrd, script)	ipxe-nix-ephemeral1
lxc-*	LXC container tarball	lxc-nix-builder
proxmox-*	Proxmox VMA archive	proxmox-nix-builder

Installer ISOs

Installer ISOs automatically install the NixOS configuration to disk on first boot.

Building Locally

# Build installer for a specific host
nix build .#installer-iso-nix-laptop1

# Result location
ls -lh result/iso/nixos-*.iso

# Copy to USB drive (replace /dev/sdX with your USB device)
sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress

Building from GitHub

nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1

Using the Installer

1. Boot from the ISO
2. The system will automatically partition the disk and install NixOS
3. After installation completes, remove the USB drive and reboot
4. Log in with the configured user credentials

Note: The installer will erase all data on the target disk specified in ugaif.host.filesystem.device.

Live ISOs

Live ISOs boot into a temporary system without installing to disk. Useful for:

• Testing configurations
• Recovery operations
• Ephemeral/stateless systems

Building Live ISOs

# Build live ISO
nix build .#iso-nix-ephemeral1

# Result location
ls -lh result/iso/nixos-*.iso

Stateless Kiosk Systems

For PXE netboot kiosks, use the ipxe-* artifacts:

# Build iPXE artifacts
nix build .#ipxe-nix-ephemeral1

# Result contains:
# - bzImage (kernel)
# - initrd (initial ramdisk)
# - netboot.ipxe (iPXE script)
ls -lh result/

Container Images

LXC Containers

Build LXC container tarballs for Proxmox or other LXC hosts:

# Build LXC tarball
nix build .#lxc-nix-builder

# Result location
ls -lh result/tarball/nixos-*.tar.xz

Importing to Proxmox:

# Copy tarball to Proxmox host
scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/

# Create container from Proxmox CLI
pct create 100 local:vztmpl/nixos-*.tar.xz \
  --hostname nix-builder \
  --memory 4096 \
  --cores 4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

See installer/PROXMOX_LXC.md for detailed Proxmox deployment instructions.

Proxmox VMA

Build Proxmox-specific VMA archives:

# Build Proxmox VMA
nix build .#proxmox-nix-builder

# Result location
ls -lh result/

Remote Builders

Speed up builds by offloading to build servers.

One-Time Remote Build

nix build .#installer-iso-nix-laptop1 \
  --builders "ssh://engr-ugaif@nix-builder x86_64-linux"

Persistent Configuration

Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf:

builders = ssh://engr-ugaif@nix-builder x86_64-linux

Then build normally:

nix build .#installer-iso-nix-laptop1

SSH Key Setup

For remote builders, ensure SSH keys are configured:

# Generate SSH key if needed
ssh-keygen -t ed25519

# Copy to builder
ssh-copy-id engr-ugaif@nix-builder

# Test connection
ssh engr-ugaif@nix-builder

Multiple Builders

Configure multiple build servers:

builders = ssh://engr-ugaif@nix-builder x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux

Troubleshooting

Build Errors

Check configuration validity:

nix flake check --show-trace

Test specific host build:

nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel

Remote Builder Issues

Test SSH access:

ssh engr-ugaif@nix-builder

Check builder disk space:

ssh engr-ugaif@nix-builder df -h

Temporarily disable remote builds:

In inventory.nix:

ugaif.sw.remoteBuild.enable = false;

Out of Disk Space

Clean up Nix store:

nix-collect-garbage -d
nix store optimise

Check space:

df -h /nix

ISO Won't Boot

Verify ISO integrity:

sha256sum result/iso/nixos-*.iso

Check USB write:

# Use correct block size and sync
sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress && sync

Try alternative boot mode:

• UEFI systems: Try legacy BIOS mode
• Legacy BIOS: Try UEFI mode

See Also

• README.md - Main documentation
• INVENTORY.md - Host configuration guide
• installer/PROXMOX_LXC.md - Proxmox deployment guide