athenix/docs/NAMESPACE.md

Configuration Namespace Reference

All UGA Innovation Factory-specific options are under 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)
• System Configuration (athenix.system)
• Convenience Options

Host Configuration (athenix.host)

Hardware and host-specific settings.

athenix.host.filesystem

Disk and storage configuration.

Options:

• athenix.host.filesystem.device - Boot disk device (default: /dev/sda)
• athenix.host.filesystem.swapSize - Swap file size (default: "32G")

Example:

athenix.host.filesystem = {
  device = "/dev/nvme0n1";
  swapSize = "64G";
};

athenix.host.buildMethods

List of supported build artifact types for this host.

Type: List of strings

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

Default: ["installer-iso"]

Example:

athenix.host.buildMethods = [ "lxc" "proxmox" ];

athenix.host.useHostPrefix

Whether to prepend the host type prefix to the hostname (used in inventory generation).

Type: Boolean

Default: true

Example:

athenix.host.useHostPrefix = false;  # "builder" instead of "nix-lxc-builder"

athenix.host.wsl

WSL-specific configuration options.

Options:

• athenix.host.wsl.user - Default WSL user for this instance

Example:

athenix.host.wsl.user = "myusername";

Software Configuration (athenix.sw)

System software and application configuration.

athenix.sw.enable

Enable the software configuration module.

Type: Boolean

Default: true

athenix.sw.type

System type that determines the software profile.

Type: Enum

Options:

• "desktop" - Full desktop environment (GNOME)
• "tablet-kiosk" - Surface tablets with kiosk mode browser
• "stateless-kiosk" - Diskless PXE boot kiosks
• "headless" - Servers and containers without GUI

Default: "desktop"

Example:

athenix.sw.type = "headless";

athenix.sw.kioskUrl

URL to display in kiosk mode browsers (for tablet-kiosk and stateless-kiosk types).

Type: String

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

Example:

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

athenix.sw.python

Python development tools configuration.

Options:

• athenix.sw.python.enable - Enable Python tools (pixi, uv) (default: true)

Example:

athenix.sw.python.enable = true;

athenix.sw.remoteBuild

Remote build server configuration for offloading builds.

Options:

• athenix.sw.remoteBuild.enable - Use remote builders (default: enabled on tablets)
• athenix.sw.remoteBuild.hosts - List of build server hostnames

Example:

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

athenix.sw.extraPackages

Additional system packages to install beyond the type defaults.

Type: List of packages

Default: []

Example:

athenix.sw.extraPackages = with pkgs; [
  vim
  htop
  docker
];

athenix.sw.excludePackages

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

Type: List of packages

Default: []

Example:

athenix.sw.excludePackages = with pkgs; [
  firefox  # Remove Firefox from default desktop packages
];

User Management (athenix.users)

User account configuration and management.

athenix.users.<username>.enable

Enable a specific user account on this system.

Type: Boolean

Default: false (except root and engr-ugaif which default to true)

Example:

athenix.users = {
  myuser.enable = true;
  student.enable = true;
};

User Account Options

Each user in users.nix can be configured with:

# Option 1: Define inline in users.nix
athenix.users.myuser = {
  description = "Full Name";
  isNormalUser = true;                    # Default: true
  extraGroups = [ "wheel" "docker" ];     # Additional groups
  shell = pkgs.zsh;                       # Login shell
  hashedPassword = "$6$...";              # Hashed password
  opensshKeys = [ "ssh-ed25519 ..." ];    # SSH public keys
  useZshTheme = true;                     # Use system Zsh theme
  useNvimPlugins = true;                  # Use system Neovim config
  
  enable = false;  # Enable per-system in inventory.nix
};

# Option 2: Use external configuration (recommended)
# The external user.nix can set athenix.users.myuser options directly
athenix.users.anotheruser.external = builtins.fetchGit {
  url = "https://git.factory.uga.edu/username/dotfiles";
  rev = "abc123...";
};

System Configuration (athenix.system)

System-wide settings and services.

athenix.system.gc

Automatic garbage collection configuration.

Options:

• athenix.system.gc.enable - Enable automatic garbage collection (default: true)
• athenix.system.gc.frequency - How often to run (default: "weekly")
• athenix.system.gc.retentionDays - Days to keep old generations (default: 30)
• athenix.system.gc.optimise - Optimize Nix store automatically (default: true)

Example:

athenix.system.gc = {
  enable = true;
  frequency = "daily";
  retentionDays = 14;
  optimise = true;
};

Convenience Options

athenix.forUser

Quick setup option that enables a user account in one line.

Type: String (username) or null

Default: null

Example:

athenix.forUser = "myusername";  # Equivalent to athenix.users.myusername.enable = true

Usage in inventory.nix:

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

See Also

• INVENTORY.md - Host inventory configuration guide
• USER_CONFIGURATION.md - User management guide
• EXTERNAL_MODULES.md - External configuration modules
• README.md - Main documentation