# Building Installation Media

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

## Table of Contents

- [Quick Start](#quick-start)
- [Available Artifacts](#available-artifacts)
- [Installer ISOs](#installer-isos)
- [Live ISOs](#live-isos)
- [Container Images](#container-images)
- [Remote Builders](#remote-builders)
- [Troubleshooting](#troubleshooting)

## Quick Start

```bash
# Build an installer ISO for a specific host
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1

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

## Available Artifacts

List all available build outputs:

```bash
nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
```

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

```bash
# 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 Gitea

```bash
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#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 `athenix.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

```bash
# 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:

```bash
# 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:

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

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

**Importing to Proxmox:**

```bash
# 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](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions.

### Proxmox VMA

Build Proxmox-specific VMA archives:

```bash
# 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

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

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

Then build normally:

```bash
nix build .#installer-iso-nix-laptop1
```

### SSH Key Setup

For remote builders, ensure SSH keys are configured:

```bash
# 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:

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

## Troubleshooting

### Build Errors

**Check configuration validity:**
```bash
nix flake check --show-trace
```

**Test specific host build:**
```bash
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
```

### Remote Builder Issues

**Test SSH access:**
```bash
ssh engr-ugaif@nix-builder
```

**Check builder disk space:**
```bash
ssh engr-ugaif@nix-builder df -h
```

**Temporarily disable remote builds:**

In `inventory.nix`:
```nix
athenix.sw.remoteBuild.enable = false;
```

### Out of Disk Space

**Clean up Nix store:**
```bash
nix-collect-garbage -d
nix store optimise
```

**Check space:**
```bash
df -h /nix
```

### ISO Won't Boot

**Verify ISO integrity:**
```bash
sha256sum result/iso/nixos-*.iso
```

**Check USB write:**
```bash
# 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](../README.md) - Main documentation
- [INVENTORY.md](INVENTORY.md) - Host configuration guide
- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment guide