athenix/docs/BUILDING.md

# Building Installation Media and Artifacts

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

## Table of Contents

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

## Quick Start

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

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

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

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

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

### Burning to USB

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

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

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

#### Importing to Proxmox

1. Copy tarball to Proxmox host:

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

2. Create container:

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

```bash
pct start 100
pct shell 100
```

#### Proxmox Integration

For detailed Proxmox deployment instructions, see [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md).

### Proxmox VMA

Build Proxmox-specific VMA archives:

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

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

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

See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed network boot setup.

## Remote Builders

Speed up builds by offloading to build servers.

### One-Time 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`:

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

Then build normally:

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

### SSH Setup

Ensure SSH is configured for the builder:

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

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

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

This speeds up builds on resource-constrained devices.

## Troubleshooting

### Build Errors

Get detailed error information:

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

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

### Out of Disk Space

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

# Optimize store
nix store optimise
```

### Build Hangs

```bash
# List processes
ps aux | grep nix

# Cancel build
Ctrl+C
```

### Finding Artifact Outputs

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

```bash
# 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.md) - Development workflow
- [INVENTORY.md](INVENTORY.md) - Host configuration
- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment
- [README.md](../README.md) - Main documentation