# 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

hosts/                    # Host generation logic
├── default.nix           # Main host generator
├── boot.nix              # Boot and filesystem configuration
├── common.nix            # Common system configuration
├── user-config.nix       # User configuration integration
└── types/                # Hardware type modules
    ├── nix-desktop.nix
    ├── nix-laptop.nix
    ├── nix-surface.nix
    ├── nix-lxc.nix
    ├── nix-wsl.nix
    └── nix-ephemeral.nix

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.**

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