athenix/docs/BUILDING.md

Building Installation Media and Artifacts

Guide to building installer ISOs, live images, and container artifacts.

Table of Contents

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

Quick Start

# List all available artifacts
nix flake show

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

# Result is in result/iso/
ls -lh result/iso/

Available Artifacts

Athenix can build multiple artifact types for deployment:

Type	Description	Location	Use Case
installer-iso-*	Auto-install ISO	result/iso/	Install NixOS to disk
iso-*	Live ISO	result/iso/	Boot without installing
ipxe-*	PXE netboot	result/	Diskless netboot systems
lxc-*	LXC container	result/tarball/	LXC/Proxmox containers
proxmox-*	Proxmox VMA	result/	Proxmox VM templates

Set artifact types per-host via athenix.host.buildMethods in inventory.nix:

nix-laptop = {
  devices = 5;
  overrides.athenix.host.buildMethods = [ "installer-iso" ];
};

nix-lxc = {
  devices.builder = {
    athenix.host.buildMethods = [ "lxc" "proxmox" ];
  };
};

Building Locally

Build artifacts on your local machine:

# Build installer ISO
nix build .#installer-iso-nix-laptop1

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

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

# Build all available outputs
nix build .#

Result locations:

• ISOs: result/iso/nixos-*.iso
• LXC: result/tarball/nixos-*.tar.xz
• Proxmox: result/
• iPXE: result/ (kernel, initrd, script)

Build Specific Host

# Get list of all hosts
nix eval .#nixosConfigurations --apply builtins.attrNames

# Build specific host
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel

Building from Remote

Build from the Gitea repository without cloning:

# Build installer ISO
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1

# Build LXC container
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#lxc-nix-builder

# Use specific branch or revision
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git?ref=develop#installer-iso-nix-laptop1

Installer ISOs

Installer ISOs automatically partition and install NixOS on first boot.

Building

nix build .#installer-iso-nix-laptop1
ls -lh result/iso/

Burning to USB

# Find USB device (be careful!)
lsblk

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

# Sync and eject
sudo sync && sudo eject /dev/sdX

Installation Process

1. Boot from the USB drive
2. System automatically boots into installer
3. Installer partitions disk according to athenix.host.filesystem
4. NixOS is installed and configured
5. System reboots automatically
6. Log in with configured user

Note: Installer will erase all data on the target disk specified in athenix.host.filesystem.device.

Installer Configuration

Customize installer via host configuration:

nix-laptop = {
  devices = 5;
  overrides = {
    athenix.host.filesystem.device = "/dev/nvme0n1";
    athenix.host.filesystem.swapSize = "32G";
    athenix.host.buildMethods = [ "installer-iso" ];
  };
};

Live ISOs

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

Building

nix build .#iso-nix-ephemeral1

Usage

Live ISOs are useful for:

• Testing configurations before installation
• Recovery operations
• Ephemeral/stateless systems
• Booting in kiosk mode

Customizing Live ISO

nix-ephemeral = {
  devices.live = {
    athenix.sw.type = "stateless-kiosk";
    athenix.sw.kioskUrl = "https://dashboard.example.com";
    athenix.host.buildMethods = [ "iso" ];
  };
};

Container Images

LXC Containers

Build LXC container tarballs for Proxmox or standalone LXC:

nix build .#lxc-nix-builder
ls -lh result/tarball/

Importing to Proxmox

1. Copy tarball to Proxmox host:

scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/

2. Create container:

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

3. Start and log in:

pct start 100
pct shell 100

Proxmox Integration

For detailed Proxmox deployment instructions, see installer/PROXMOX_LXC.md.

Proxmox VMA

Build Proxmox-specific VMA archives:

nix build .#proxmox-nix-builder
ls -lh result/

VMA files can be imported directly into Proxmox for rapid VM creation.

iPXE / Network Boot

Build iPXE artifacts for diskless PXE boot systems:

nix build .#ipxe-nix-ephemeral1
ls -lh result/

Artifacts include:

• bzImage - Linux kernel
• initrd - Initial ramdisk
• netboot.ipxe - iPXE boot script

iPXE Setup

Configure your PXE server to boot from these artifacts:

kernel tftp://server/bzImage
initrd tftp://server/initrd
boot

See installer/PROXMOX_LXC.md for detailed network boot setup.

Remote Builders

Speed up builds by offloading to build servers.

One-Time Build

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

Persistent Configuration

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

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

Then build normally:

nix build .#installer-iso-nix-laptop1

SSH Setup

Ensure SSH is configured for the builder:

# Generate 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

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

Automatic Remote Build (Tablets)

Surface tablets are configured to automatically use remote builders:

athenix.sw.remoteBuild = {
  enable = true;
  hosts = [ "nix-builder" ];
};

This speeds up builds on resource-constrained devices.

Troubleshooting

Build Errors

Get detailed error information:

# Verbose error traces
nix build .#installer-iso-nix-laptop1 --show-trace

# Check all configurations first
nix flake check --show-trace

Out of Disk Space

# Clean up Nix store
nix-collect-garbage -d

# Optimize store
nix store optimise

Build Hangs

# List processes
ps aux | grep nix

# Cancel build
Ctrl+C

Finding Artifact Outputs

# List all buildable outputs
nix flake show

# Check specific output exists
nix flake show | grep installer-iso-nix-laptop1

# Get path to output
nix build .#installer-iso-nix-laptop1 --no-link

Build Not Creating Expected File

# Check build log
nix build .#installer-iso-nix-laptop1 -L

# Check what's in result
ls -la result/

# Inspect NixOS build structure
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L

See Also

• DEVELOPMENT.md - Development workflow
• INVENTORY.md - Host configuration
• installer/PROXMOX_LXC.md - Proxmox deployment
• README.md - Main documentation