athenix/docs/INVENTORY.md

# Host Inventory Configuration

This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices.

## Table of Contents

- [Understanding Inventory Structure](#understanding-inventory-structure)
- [Hostname Generation Rules](#hostname-generation-rules)
- [Adding Hosts](#adding-hosts)
- [Device Configuration Options](#device-configuration-options)
- [Examples](#examples)

## Understanding Inventory Structure

The `inventory.nix` file defines all hosts in the fleet using a flexible system. Top-level keys are always hostname **prefixes**, and actual hostnames are generated from device configurations.

## Hostname Generation Rules

- **Numeric suffixes**: no dash (e.g., `nix-laptop1`, `nix-laptop2`)
- **Non-numeric suffixes**: with dash (e.g., `nix-laptop-alpha`, `nix-laptop-beta`)  
- **Custom hostnames**: Set `athenix.host.useHostPrefix = false` to use suffix as full hostname

## Adding Hosts

### Method 1: Quick Count (Simplest)

```nix
nix-laptop = {
  devices = 5;  # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
};
```

### Method 2: Explicit Count with Overrides

```nix
nix-laptop = {
  devices = 5;
  overrides = {
    # Applied to ALL nix-laptop hosts
    athenix.users.student.enable = true;
    athenix.sw.extraPackages = with pkgs; [ vim git ];
  };
};
```

### Method 3: Individual Device Configuration

```nix
nix-surface = {
  devices = {
    "1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
    "2".athenix.sw.kioskUrl = "https://dashboard2.example.com";
    "3".athenix.sw.kioskUrl = "https://dashboard3.example.com";
  };
};
```

### Method 4: Mixed (Default Count + Custom Devices)

```nix
nix-surface = {
  defaultCount = 2;  # Creates nix-surface1, nix-surface2
  devices = {
    "special" = {  # Creates nix-surface-special
      athenix.sw.kioskUrl = "https://special-dashboard.example.com";
    };
  };
  overrides = {
    # Applied to all devices (including "special")
    athenix.sw.kioskUrl = "https://default-dashboard.example.com";
  };
};
```

## Device Configuration Options

### Direct Configuration (Recommended)

Use any NixOS or `athenix.*` option:

```nix
"1" = {
  # Athenix options
  athenix.users.myuser.enable = true;
  athenix.host.filesystem.swapSize = "64G";
  athenix.sw.extraPackages = with pkgs; [ docker ];
  athenix.sw.kioskUrl = "https://example.com";
  
  # Standard NixOS options
  networking.firewall.enable = false;
  services.openssh.enable = true;
  time.timeZone = "America/New_York";
};
```

### Convenience: `athenix.forUser`

Quick setup for single-user systems (especially WSL):

```nix
nix-wsl = {
  devices = {
    "alice".athenix.forUser = "alice-username";
  };
};
```

This automatically enables the user account.

### External System Configuration

For complex configurations, use external modules (see [EXTERNAL_MODULES.md](../EXTERNAL_MODULES.md)):

```nix
nix-lxc = {
  devices = {
    "special-server" = builtins.fetchGit {
      url = "https://git.factory.uga.edu/org/server-config";
      rev = "abc123...";
    };
  };
};
```

## Examples

### Simple Lab Computers

```nix
nix-laptop = {
  devices = 10;  # Creates nix-laptop1 through nix-laptop10
  overrides = {
    athenix.users.student.enable = true;
  };
};
```

### Mixed Surface Tablets

```nix
nix-surface = {
  defaultCount = 5;  # nix-surface1 through nix-surface5 (default config)
  devices = {
    "admin" = {  # nix-surface-admin (special config)
      athenix.sw.type = "desktop";  # Full desktop instead of kiosk
      athenix.users.admin.enable = true;
    };
  };
  overrides = {
    athenix.sw.type = "tablet-kiosk";
    athenix.sw.kioskUrl = "https://dashboard.factory.uga.edu";
  };
};
```

### LXC Containers

```nix
nix-lxc = {
  devices = {
    "nix-builder" = {
      athenix.sw.type = "headless";
    };
    "webserver" = {
      athenix.sw.type = "headless";
      services.nginx.enable = true;
    };
  };
  overrides = {
    athenix.host.useHostPrefix = false;  # Use exact device key as hostname
  };
};
```

### WSL Instances

```nix
nix-wsl = {
  devices = {
    "alice".athenix.forUser = "alice-uga";
    "bob".athenix.forUser = "bob-uga";
  };
};
```

## See Also

- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
- [Configuration Namespace Reference](NAMESPACE.md) - All `athenix.*` options