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
• Hostname Generation Rules
• Adding Hosts
• Device Configuration Options
• 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-laptop = {
  devices = 5;  # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
};

Method 2: Explicit Count with Overrides

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

"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-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):

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

Examples

Simple Lab Computers

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

Mixed Surface Tablets

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-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-wsl = {
  devices = {
    "alice".athenix.forUser = "alice-uga";
    "bob".athenix.forUser = "bob-uga";
  };
};

See Also

• USER_CONFIGURATION.md - User account management
• EXTERNAL_MODULES.md - External configuration modules
• Configuration Namespace Reference - All athenix.* options