# Athenix - UGA Innovation Factory NixOS Configuration

[![CI](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions/workflows/ci.yml/badge.svg)](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions)

Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.

## Quick Navigation

- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Define and configure hosts
- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - All `athenix.*` options reference
- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User accounts and dotfiles
- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External system and user configurations
- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs, containers, and artifacts
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflow and testing

## Getting Started

### For End Users

Update your system:

```bash
update-system
```

This automatically rebuilds your system with the latest configuration from the repository.

### For Administrators

Make configuration changes:

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

```nix
# 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](docs/NAMESPACE.md) for complete option reference.

## Common Tasks

### Adding Hosts

Edit `inventory.nix`:

```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](docs/INVENTORY.md) for complete guide.**

### Managing Users

Edit `users.nix`:

```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
nix-laptop = {
  overrides.athenix.users.myuser.enable = true;
};
```

**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete guide.**

### Using External Configurations

Reference external repositories for user dotfiles or system configurations:

```nix
# 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](docs/EXTERNAL_MODULES.md) for complete guide.**

### Building Installation Media

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

```nix
{
  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

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

```bash
# 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](docs/INVENTORY.md) - Host configuration
- [docs/NAMESPACE.md](docs/NAMESPACE.md) - All option references
- [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) - User management
- [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) - External modules
- [docs/BUILDING.md](docs/BUILDING.md) - Building and deployment
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development guide