# Edit inventory
vim inventory.nix

# Validate changes
nix flake check

# Format code
nix fmt

# Commit and push
git add . && git commit -m "Your message" && git push

Users automatically get changes when they run update-system.

Repository Structure

flake.nix                 # Flake entry point (inputs + outputs)
inventory.nix             # Fleet inventory and host definitions
users.nix                 # User account definitions

flake.lock                # Locked dependency versions

hw/                 # Hardware type modules (exportable as nixosModules)
├── default.nix           # Auto-exports all variant types
├── nix-desktop.nix       # Desktop workstations
├── nix-laptop.nix        # Laptop systems
├── nix-surface.nix       # Surface Pro tablets
├── nix-lxc.nix           # LXC containers
├── nix-wsl.nix           # WSL instances
├── nix-zima.nix          # ZimaBoard systems
└── nix-ephemeral.nix     # Diskless/netboot systems

fleet/                    # Fleet generation and common configuration
├── default.nix           # Processes inventory.nix to generate all hosts
├── common.nix            # Common NixOS configuration (all hosts)
├── boot.nix              # Boot and filesystem configuration
└── user-config.nix       # User account and home-manager integration

sw/                       # Software configurations by system type
├── default.nix           # Software module entry point
├── python.nix            # Python tools (pixi, uv)
├── nvim.nix              # Neovim configuration
├── ghostty.nix           # Ghostty terminal
├── theme.nix             # System theme configuration
├── updater.nix           # System update scripts
├── update-ref.nix        # Update reference tracking
├── builders/             # Build server configuration
├── desktop/              # Desktop environment
├── headless/             # Server/container without GUI
├── tablet-kiosk/         # Surface tablet kiosk mode
└── stateless-kiosk/      # Diskless PXE netboot systems

installer/                # Build artifacts
├── default.nix           # Build configuration
├── artifacts.nix         # ISO/LXC/Proxmox definitions
├── auto-install.nix      # Installer scripts
├── modules.nix           # Installer-specific modules
├── deploy-proxmox-lxc.sh # Proxmox deployment script
└── PROXMOX_LXC.md        # Proxmox guide

templates/                # Templates for external modules
├── user/                 # User configuration template
│   ├── user.nix          # User options + home-manager config
│   └── README.md
└── system/               # System configuration template
    ├── default.nix       # NixOS module
    └── README.md

docs/                     # Documentation
├── README.md             # This file
├── INVENTORY.md          # Host configuration guide
├── NAMESPACE.md          # Option reference
├── USER_CONFIGURATION.md # User management
├── EXTERNAL_MODULES.md   # External module integration
├── BUILDING.md           # Build and deployment
└── DEVELOPMENT.md        # Development workflow

assets/                   # Assets
└── plymouth-theme/       # Boot splash theme

Configuration Overview

All Innovation Factory-specific options use the athenix namespace to avoid conflicts with NixOS options.

Common Options

# Host filesystem and hardware
athenix.host = {
  filesystem.device = "/dev/sda";
  filesystem.swapSize = "32G";
  buildMethods = [ "installer-iso" ];
  useHostPrefix = true;
};

# System type and packages
athenix.sw = {
  type = "desktop";  # desktop, tablet-kiosk, stateless-kiosk, headless, builders
  extraPackages = with pkgs; [ vim docker ];
};

# User management
athenix.users.myuser.enable = true;
athenix.forUser = "myuser";  # Convenience shortcut

See docs/NAMESPACE.md for complete option reference.

Common Tasks

Adding Hosts

Edit inventory.nix:

# Simple: Create 5 identical laptops
nix-laptop = {
  devices = 5;
};

# With custom configuration per device
nix-surface = {
  devices = {
    "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
    "2".athenix.sw.kioskUrl = "https://dashboard2.example.com";
  };
};

# With common overrides
nix-desktop = {
  devices = 3;
  overrides = {
    athenix.users.student.enable = true;
  };
};

See docs/INVENTORY.md for complete guide.

Managing Users

Edit users.nix:

athenix.users.myuser = {
  description = "My Name";
  extraGroups = [ "wheel" "networkmanager" ];
  shell = pkgs.zsh;
  hashedPassword = "$6$...";  # mkpasswd -m sha-512
  opensshKeys = [ "ssh-ed25519 AAAA..." ];
};

Enable in inventory.nix:

nix-laptop = {
  overrides.athenix.users.myuser.enable = true;
};

See docs/USER_CONFIGURATION.md for complete guide.

Using External Configurations

Reference external repositories for user dotfiles or system configurations:

# User dotfiles (in users.nix)
hdh20267.external = builtins.fetchGit {
  url = "https://git.factory.uga.edu/hdh20267/dotfiles";
  rev = "abc123...";
};

# System configuration (in inventory.nix)
nix-lxc = {
  devices."special" = builtins.fetchGit {
    url = "https://git.factory.uga.edu/org/server-config";
    rev = "abc123...";
  };
};

See docs/EXTERNAL_MODULES.md for complete guide.

Building Installation Media

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

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

# List all available artifacts
nix flake show

See docs/BUILDING.md for complete guide.

Using Athenix as a Library

Import Athenix in your own flake to use its fleet generation logic with custom inventory:

{
  inputs.athenix.url = "git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git";
  
  outputs = { self, athenix, ... }: {
    # Generate configurations with custom fleet and hardware types
    nixosConfigurations = athenix.lib.mkFleet {
      fleet = import ./my-inventory.nix;
      hwTypes = import ./my-hardware-types.nix;
    };
    
    # Or use individual modules
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        athenix.nixosModules.hw.nix-desktop  # Use Athenix hardware configs
        athenix.nixosModules.sw              # Use Athenix software configs
        ./configuration.nix
      ];
    };
  };
}

Exported modules: nix-desktop, nix-laptop, nix-surface, nix-lxc, nix-wsl, nix-ephemeral, nix-zima, sw, common

System Types

Set via athenix.sw.type:

desktop - Full GNOME desktop environment
tablet-kiosk - Surface tablets with Firefox kiosk browser
stateless-kiosk - Diskless PXE-booted systems
headless - Servers and containers without GUI
builders - Build servers

Development Workflow

# Check all configurations
nix flake check

# Format code
nix fmt **/*.nix

# Build specific artifact
nix build .#installer-iso-nix-laptop1

# Update flake inputs
nix flake update

See docs/DEVELOPMENT.md for detailed workflow.

Troubleshooting

Issue	Solution
Build errors	Run `nix flake check --show-trace` for details
Configuration validation	`nix flake check` checks all 50+ hosts
External modules fail	Verify Git URL accessibility and module structure
Remote build issues	Test SSH: `ssh engr-ugaif@nix-builder`
List all hosts	`nix eval .#nixosConfigurations --apply builtins.attrNames`
Disk space	`nix-collect-garbage -d && nix store optimise`

Prerequisites

Nix with flakes support:

# Recommended: Determinate Systems installer
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Or enable flakes in existing Nix installation
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf

More Information

docs/INVENTORY.md - Host configuration
docs/NAMESPACE.md - All option references
docs/USER_CONFIGURATION.md - User management
docs/EXTERNAL_MODULES.md - External modules
docs/BUILDING.md - Building and deployment
docs/DEVELOPMENT.md - Development guide

README.md

Athenix - UGA Innovation Factory NixOS Configuration

Quick Navigation

Getting Started

For End Users

For Administrators