athenix/docs/NAMESPACE.md

# Configuration Namespace Reference

All UGA Innovation Factory-specific options are in the `athenix` namespace to avoid conflicts with standard NixOS options.

## Table of Contents

- [Host Configuration (`athenix.host`)](#host-configuration-athenixhost)
- [Software Configuration (`athenix.sw`)](#software-configuration-athenixsw)
- [User Management (`athenix.users`)](#user-management-athenixusers)
- [Convenience Options](#convenience-options)

## Host Configuration (`athenix.host`)

Hardware and boot-related settings.

### `athenix.host.filesystem.device`

Boot disk device path.

**Type:** String or null

**Default:** `null` (must be set by hardware type or per-host)

**Example:**
```nix
athenix.host.filesystem.device = "/dev/nvme0n1";
```

### `athenix.host.filesystem.swapSize`

Swap partition size.

**Type:** String (size with unit, e.g., `"32G"`, `"2G"`) or null

**Default:** `null` (must be set by hardware type or per-host)

**Example:**
```nix
athenix.host.filesystem.swapSize = "64G";
```

### `athenix.host.buildMethods`

Artifact types to build for this host.

**Type:** List of strings

**Options:** `"installer-iso"`, `"iso"`, `"ipxe"`, `"lxc"`, `"proxmox"`

**Default:** `[ "installer-iso" ]`

**Description:**
- `"installer-iso"` - Installer ISO with auto-install
- `"iso"` - Live ISO (boot without installation)
- `"ipxe"` - iPXE netboot artifacts
- `"lxc"` - LXC container tarball
- `"proxmox"` - Proxmox VMA template

**Example:**
```nix
athenix.host.buildMethods = [ "installer-iso" "lxc" ];
```

### `athenix.host.useHostPrefix`

Whether to prepend the host type prefix to the generated hostname.

**Type:** Boolean

**Default:** `true`

**Example:**
```nix
# With useHostPrefix = true (default)
# Device "1" under "nix-laptop" → "nix-laptop1"

# With useHostPrefix = false
# Device "builder" under "nix-lxc" → "builder" (not "nix-lxc-builder")
athenix.host.useHostPrefix = false;
```

### `athenix.host.wsl.user`

Default WSL user account (only for `nix-wsl` type).

**Type:** String (username)

**Example:**
```nix
athenix.host.wsl.user = "myusername";
```

## Software Configuration (`athenix.sw`)

System type, packages, and application configuration.

### `athenix.sw.enable`

Enable software configuration.

**Type:** Boolean

**Default:** `true`

### `athenix.sw.type`

System profile/type. Determines which software packages and services are installed.

**Type:** String or list of strings

**Options:**
- `"desktop"` - Full GNOME desktop environment with development tools
- `"tablet-kiosk"` - Surface tablets with Firefox kiosk browser
- `"stateless-kiosk"` - Diskless PXE-booted ephemeral systems
- `"headless"` - Servers and containers without GUI
- `"builders"` - Build servers with build dependencies

**Default:** `"desktop"`

**Example:**
```nix
athenix.sw.type = "desktop";

# Multiple types supported
athenix.sw.type = [ "desktop" "headless" ];
```

### `athenix.sw.kioskUrl`

URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types).

**Type:** String (URL)

**Default:** `"https://ha.factory.uga.edu"`

**Example:**
```nix
athenix.sw.kioskUrl = "https://dashboard.example.com";
```

### `athenix.sw.python.enable`

Enable Python development tools (pixi, uv, etc.).

**Type:** Boolean

**Default:** `true`

**Example:**
```nix
athenix.sw.python.enable = true;
```

### `athenix.sw.remoteBuild`

Configure remote build servers for offloading builds.

**Type:** Attribute set

**Options:**
- `enable` - Enable remote builders (Boolean, default: `true` for tablets)
- `hosts` - List of remote builder hostnames (List of strings)

**Example:**
```nix
athenix.sw.remoteBuild = {
  enable = true;
  hosts = [ "nix-builder" "nix-builder2" ];
};
```

### `athenix.sw.extraPackages`

Additional system packages beyond the type defaults.

**Type:** List of packages

**Default:** `[ ]`

**Example:**
```nix
athenix.sw.extraPackages = with pkgs; [
  vim
  docker
  htop
  ripgrep
];
```

### `athenix.sw.excludePackages`

Packages to remove from the default list for this system type.

**Type:** List of packages

**Default:** `[ ]`

**Example:**
```nix
athenix.sw.excludePackages = with pkgs; [
  firefox  # Don't install Firefox on this system
];
```

## User Management (`athenix.users`)

User account configuration and access control.

### `athenix.users.<username>.enable`

Enable a user account on this system.

**Type:** Boolean

**Default:** `false` (except `root` and `engr-ugaif` which are `true`)

**Example:**
```nix
# In inventory.nix
nix-laptop = {
  devices = 5;
  overrides.athenix.users.myuser.enable = true;
};
```

### User Account Options (in `users.nix`)

Define user accounts in `users.nix` with these options:

#### `description`

Full name or description of the user.

**Type:** String

```nix
athenix.users.myuser.description = "John Doe";
```

#### `extraGroups`

Additional Unix groups for the user.

**Type:** List of strings

**Common groups:**
- `"wheel"` - Sudo access
- `"networkmanager"` - Network configuration
- `"docker"` - Docker access
- `"video"` - Video device access
- `"audio"` - Audio device access
- `"input"` - Input device access (keyboards, mice)

```nix
athenix.users.myuser.extraGroups = [ "wheel" "docker" "networkmanager" ];
```

#### `shell`

Login shell for the user.

**Type:** Package

**Default:** `pkgs.bash`

```nix
athenix.users.myuser.shell = pkgs.zsh;
```

#### `hashedPassword`

Password hash for the user.

**Type:** String (SHA-512 hash)

**Generation:**
```bash
mkpasswd -m sha-512
```

```nix
athenix.users.myuser.hashedPassword = "$6$...";
```

#### `opensshKeys`

SSH public keys for this user.

**Type:** List of strings

```nix
athenix.users.myuser.opensshKeys = [
  "ssh-ed25519 AAAA... user@host"
  "ssh-rsa AAAA... user@other"
];
```

#### `useZshTheme`

Apply system Zsh theme configuration to this user.

**Type:** Boolean

**Default:** `true`

```nix
athenix.users.myuser.useZshTheme = true;
```

#### `useNvimPlugins`

Apply system Neovim configuration to this user.

**Type:** Boolean

**Default:** `true`

```nix
athenix.users.myuser.useNvimPlugins = true;
```

#### `external`

Reference external user configuration (dotfiles, home-manager).

**Type:** Path or Git reference

**Example:**
```nix
athenix.users.myuser.external = builtins.fetchGit {
  url = "https://git.factory.uga.edu/username/dotfiles";
  rev = "abc123...";
};
```

See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) for detailed external module usage.

### Enabling Users on Systems

Users defined in `users.nix` are **not enabled by default**. Enable them in `inventory.nix`:

```nix
# Option 1: Enable on all devices in a group
nix-laptop = {
  devices = 5;
  overrides.athenix.users.student.enable = true;
};

# Option 2: Enable on specific devices
nix-surface = {
  devices = {
    "1".athenix.users.admin.enable = true;
    "2".athenix.users.admin.enable = true;
  };
};
```

## Convenience Options

### `athenix.forUser`

Quick setup for single-user systems. Automatically enables a user and sets it as the default.

**Type:** String (username) or null

**Default:** `null`

**Example:**
```nix
# In inventory.nix - enables the user automatically
nix-wsl = {
  devices = {
    "alice".athenix.forUser = "alice-uga";
  };
};
```

Equivalent to:
```nix
"alice" = {
  athenix.users.alice-uga.enable = true;
  athenix.host.wsl.user = "alice-uga";
};
```

## See Also

- [INVENTORY.md](INVENTORY.md) - Host configuration examples
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management guide
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module integration
- [README.md](../README.md) - Main documentation