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)
• Software Configuration (athenix.sw)
• User Management (athenix.users)
• 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:

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:

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:

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:

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

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:

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:

athenix.sw.kioskUrl = "https://dashboard.example.com";

athenix.sw.python.enable

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

Type: Boolean

Default: true

Example:

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:

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:

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:

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:

# 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

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)

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

shell

Login shell for the user.

Type: Package

Default: pkgs.bash

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

hashedPassword

Password hash for the user.

Type: String (SHA-512 hash)

Generation:

mkpasswd -m sha-512

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

opensshKeys

SSH public keys for this user.

Type: List of strings

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

athenix.users.myuser.useZshTheme = true;

useNvimPlugins

Apply system Neovim configuration to this user.

Type: Boolean

Default: true

athenix.users.myuser.useNvimPlugins = true;

external

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

Type: Path or Git reference

Example:

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

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

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

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

Equivalent to:

"alice" = {
  athenix.users.alice-uga.enable = true;
  athenix.host.wsl.user = "alice-uga";
};

See Also

• INVENTORY.md - Host configuration examples
• USER_CONFIGURATION.md - User account management guide
• EXTERNAL_MODULES.md - External module integration
• README.md - Main documentation