UGA-Innovation-Factory/athenix
3
1
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

overhaul external user modules

Browse Source
This commit is contained in:
Hunter David Halloran
2025-12-17 15:34:34 -05:00
parent b1ae664ab0
commit b9d7af509f
8 changed files with 346 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/USER_CONFIGURATION.md
View File

@@ -90,8 +90,8 @@ username = {
"ssh-rsa AAAA... user@otherhost" "ssh-rsa AAAA... user@otherhost"
]; ];
# === Home Configuration === # === External Configuration ===
home = builtins.fetchGit { ... }; # External home-manager config (see below) external = builtins.fetchGit { ... }; # External user module (see below)
# OR (if not using external config): # OR (if not using external config):
homePackages = with pkgs; [ # User packages homePackages = with pkgs; [ # User packages
@@ -120,12 +120,13 @@ In `users.nix`:
```nix ```nix
myuser = { myuser = {
# Basic options can be set here OR in the external module's user.nix
description = "My Name"; description = "My Name";
extraGroups = [ "wheel" ]; extraGroups = [ "wheel" ];
hashedPassword = "$6$..."; hashedPassword = "$6$...";
# Point to external dotfiles repository # Point to external configuration repository
home = builtins.fetchGit { external = builtins.fetchGit {
url = "https://github.com/username/dotfiles"; url = "https://github.com/username/dotfiles";
rev = "abc123..."; # Pin to specific commit rev = "abc123..."; # Pin to specific commit
}; };
@@ -136,7 +137,7 @@ myuser = {
``` ```
dotfiles/ dotfiles/
├── home.nix # Required: Home-manager configuration ├── user.nix # Optional: User options AND home-manager config
├── nixos.nix # Optional: System-level configuration ├── nixos.nix # Optional: System-level configuration
└── config/ # Optional: Your dotfiles └── config/ # Optional: Your dotfiles
├── bashrc ├── bashrc
@@ -144,13 +145,28 @@ dotfiles/
└── ... └── ...
``` ```
**home.nix (required):** **Both `.nix` files are optional, but at least one should be present.**
**user.nix (optional):**
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, osConfig, ... }: { config, lib, pkgs, ... }:
{ {
home.packages = with pkgs; [ vim git htop ]; # User account options (imported as NixOS module)
ugaif.users.myusername = {
description = "My Full Name";
extraGroups = [ "wheel" "docker" ];
shell = pkgs.zsh;
useZshTheme = true;
};
# Home-manager configuration (imported into home-manager)
home.packages = with pkgs; [
vim
ripgrep
];
programs.git = { programs.git = {
enable = true; enable = true;
userName = "My Name"; userName = "My Name";
@@ -174,12 +190,22 @@ dotfiles/
### What External Modules Receive ### What External Modules Receive
**In home.nix:** **In user.nix:**
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.) - `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
- `config` - Home-manager configuration - `config` - Configuration (NixOS or home-manager depending on import context)
- `lib` - Nixpkgs library functions - `lib` - Nixpkgs library functions
- `pkgs` - Package set - `pkgs` - Package set
- `osConfig` - OS-level configuration (read-only) - `osConfig` - (home-manager context only) OS-level configuration
### How External Modules Are Loaded
The `user.nix` module is used in two ways:
1. **User Options (Data Extraction)**: The `ugaif.users.<username>` options are extracted and loaded as **data**. The module is evaluated with minimal arguments to extract just the ugaif.users options, which override any defaults set in `users.nix` (which uses `lib.mkDefault`).
2. **Home-Manager Configuration**: The entire module (including `home.*`, `programs.*`, `services.*` options) is imported into home-manager as a configuration module.
This means you can define both user account settings AND home-manager configuration in a single file.
**In nixos.nix:** **In nixos.nix:**
- `inputs` - Flake inputs - `inputs` - Flake inputs
@@ -191,23 +217,21 @@ dotfiles/
**Local path (for testing):** **Local path (for testing):**
```nix ```nix
home = /home/username/dev/dotfiles; external = /home/username/dev/dotfiles;
``` ```
**Inline configuration:** **Note:** User options can be set in users.nix OR in the external module's user.nix file.
**No external config:**
```nix ```nix
home = { # Configure everything directly in users.nix
home.packages = with pkgs; [ vim ]; myuser = {
programs.git.enable = true; description = "My Name";
homePackages = with pkgs; [ vim git ];
# external is null by default
}; };
``` ```
**No external config (legacy):**
```nix
homePackages = with pkgs; [ vim git ];
# home = null; # Default
```
### Create User Template ### Create User Template
```bash ```bash

13
hosts/default.nix
View File

@@ -51,14 +51,17 @@ let
userNixosModulePaths = lib.filterAttrs (_: v: v != null) ( userNixosModulePaths = lib.filterAttrs (_: v: v != null) (
lib.mapAttrs ( lib.mapAttrs (
name: user: name: user:
if (user ? home && user.home != null) then if (user ? external && user.external != null) then
let let
homePath = externalPath =
if builtins.isAttrs user.home && user.home ? outPath then user.home.outPath else user.home; if builtins.isAttrs user.external && user.external ? outPath then
nixosModulePath = homePath + "/nixos.nix"; user.external.outPath
else
user.external;
nixosModulePath = externalPath + "/nixos.nix";
in in
if if
(builtins.isPath homePath || (builtins.isString homePath && lib.hasPrefix "/" homePath)) (builtins.isPath externalPath || (builtins.isString externalPath && lib.hasPrefix "/" externalPath))
&& builtins.pathExists nixosModulePath && builtins.pathExists nixosModulePath
then then
nixosModulePath nixosModulePath

150
hosts/user-config.nix
View File

@@ -14,6 +14,57 @@
# and Home Manager configuration. # and Home Manager configuration.
let let
# Load users.nix to get account definitions
pkgs' = pkgs;
usersData = import ../users.nix { pkgs = pkgs'; };
accounts = usersData.ugaif.users or { };
# Helper: Resolve external module path from fetchGit/fetchTarball/path
resolveExternalPath = external:
if external == null then
null
else if builtins.isAttrs external && external ? outPath then
external.outPath
else
external;
# Helper: Check if path exists and is valid
isValidPath = path:
path != null
&& (builtins.isPath path || (builtins.isString path && lib.hasPrefix "/" path))
&& builtins.pathExists path;
# Extract ugaif.users options from external user.nix modules
externalUserOptions = lib.foldl' (
acc: item:
let
name = item.name;
user = item.user;
externalPath = resolveExternalPath (user.external or null);
userNixPath = if externalPath != null then externalPath + "/user.nix" else null;
# Load the module and extract its ugaif.users options
moduleOptions =
if isValidPath userNixPath then
let
# Import and evaluate the module with minimal args
outerModule = import userNixPath { inherit inputs; };
evaluatedModule = outerModule {
config = { };
inherit lib pkgs;
osConfig = null;
};
# Extract just the ugaif.users.<name> options
ugaifUsers = evaluatedModule.ugaif.users or { };
userOptions = ugaifUsers.${name} or { };
in
userOptions
else
{ };
in
if moduleOptions != { } then acc // { ${name} = moduleOptions; } else acc
) { } (lib.mapAttrsToList (name: user: { inherit name user; }) accounts);
# Submodule defining the structure of a user account # Submodule defining the structure of a user account
userSubmodule = lib.types.submodule { userSubmodule = lib.types.submodule {
options = { options = {
@@ -49,7 +100,7 @@ let
type = lib.types.listOf lib.types.path; type = lib.types.listOf lib.types.path;
default = [ ]; default = [ ];
}; };
home = lib.mkOption { external = lib.mkOption {
type = lib.types.nullOr ( type = lib.types.nullOr (
lib.types.oneOf [ lib.types.oneOf [
lib.types.path lib.types.path
@@ -59,10 +110,14 @@ let
); );
default = null; default = null;
description = '' description = ''
External home-manager configuration. Can be: External user configuration module. Can be:
- A path to a local module - A path to a local module directory
- A fetchGit/fetchTarball result pointing to a repository - A fetchGit/fetchTarball result pointing to a repository
- An attribute set with home-manager configuration
The external module can contain:
- user.nix (optional): Sets ugaif.users.<name> options AND home-manager config
- nixos.nix (optional): System-level NixOS configuration
Example: builtins.fetchGit { url = "https://github.com/user/dotfiles"; rev = "..."; } Example: builtins.fetchGit { url = "https://github.com/user/dotfiles"; rev = "..."; }
''; '';
}; };
@@ -98,8 +153,10 @@ let
}; };
}; };
}; };
in in
{ {
options.ugaif.users = lib.mkOption { options.ugaif.users = lib.mkOption {
type = lib.types.attrsOf userSubmodule; type = lib.types.attrsOf userSubmodule;
default = { }; default = { };
@@ -107,6 +164,20 @@ in
}; };
config = { config = {
# Merge user definitions from users.nix with options from external user.nix modules
# External options take precedence over users.nix (which uses lib.mkDefault)
ugaif.users = lib.mapAttrs (
name: user:
{
description = lib.mkDefault (user.description or null);
shell = lib.mkDefault (user.shell or null);
extraGroups = lib.mkDefault (user.extraGroups or [ ]);
external = user.external or null;
}
// (externalUserOptions.${name} or { })
) accounts;
# Generate NixOS users # Generate NixOS users
users.users = users.users =
let let
@@ -143,52 +214,59 @@ in
in in
lib.mapAttrs ( lib.mapAttrs (
name: user: name: user:
{ ... }:
let let
# Check if user has external home configuration # Resolve external module paths
hasExternalHome = user.home != null; hasExternal = user.external != null;
externalPath = resolveExternalPath user.external;
userNixPath = if externalPath != null then externalPath + "/user.nix" else null;
hasExternalUser = isValidPath userNixPath;
# Extract path from fetchGit/fetchTarball if needed # Import external user.nix for home-manager (filter out ugaif.* options)
externalHomePath = externalUserModule =
if hasExternalHome then if hasExternalUser then
if builtins.isAttrs user.home && user.home ? outPath then user.home.outPath else user.home let
else fullModule = import userNixPath { inherit inputs; };
null; in
# Only pass through non-ugaif options to home-manager
# Import external module if it's a path {
externalHomeModule = config,
if lib,
externalHomePath != null pkgs,
&& ( osConfig,
builtins.isPath externalHomePath ...
|| (builtins.isString externalHomePath && lib.hasPrefix "/" externalHomePath) }:
) let
then evaluated = fullModule { inherit config lib pkgs osConfig; };
import (externalHomePath + "/home.nix") { inherit inputs; } in
else if builtins.isAttrs user.home && !(user.home ? outPath) then lib.filterAttrs (name: _: name != "ugaif") evaluated
user.home # Direct attrset configuration
else else
{ }; { };
# Common imports based on flags # Common imports based on user flags
commonImports = lib.optional user.useZshTheme ../sw/theme.nix ++ [ commonImports = lib.optional user.useZshTheme ../sw/theme.nix ++ [
(import ../sw/nvim.nix { inherit user; }) (import ../sw/nvim.nix { inherit user; })
]; ];
# Build imports list
allImports =
user.extraImports
++ commonImports
++ lib.optional hasExternalUser externalUserModule;
in in
if hasExternalHome then lib.mkMerge [
{ {
# External users: Merge external config with common imports imports = allImports;
imports = commonImports ++ [ externalHomeModule ];
} # Always set these required options
else
{
# Local users: Apply full configuration.
imports = user.extraImports ++ commonImports;
home.username = name; home.username = name;
home.homeDirectory = if name == "root" then "/root" else "/home/${name}"; home.homeDirectory = if name == "root" then "/root" else "/home/${name}";
home.stateVersion = "25.11"; home.stateVersion = "25.11";
home.packages = user.homePackages;
} }
(lib.mkIf (!hasExternal) {
# For local users only, add their packages
home.packages = user.homePackages;
})
]
) enabledAccounts; ) enabledAccounts;
}; };
}; };

89
templates/user/README.md
View File

@@ -10,12 +10,14 @@ External user modules allow users to maintain their personal configurations (dot
``` ```
user-dotfiles-repo/ user-dotfiles-repo/
├── home.nix # Required: Home-manager configuration ├── user.nix # Optional: User options AND home-manager configuration
├── nixos.nix # Optional: System-level NixOS configuration ├── nixos.nix # Optional: System-level NixOS configuration
├── README.md # Documentation ├── README.md # Documentation
└── dotfiles/ # Optional: Dotfiles to symlink └── dotfiles/ # Optional: Dotfiles to symlink
``` ```
**Note:** Both `.nix` files are optional, but at least one should be present for the module to be useful.
## Usage ## Usage
### 1. Create Your User Configuration Repository ### 1. Create Your User Configuration Repository
@@ -30,24 +32,22 @@ Copy the templates from this directory to your own Git repository:
{ {
ugaif.users = { ugaif.users = {
myusername = { myusername = {
# Option 1: Set user options in users.nix
description = "My Name"; description = "My Name";
extraGroups = [ "wheel" "networkmanager" ]; extraGroups = [ "wheel" "networkmanager" ];
shell = pkgs.zsh; shell = pkgs.zsh;
# Option 1: External module from Git # Option 2: Or let the external module's user.nix set these options
home = builtins.fetchGit {
# Reference external dotfiles module
external = builtins.fetchGit {
url = "https://github.com/username/dotfiles"; url = "https://github.com/username/dotfiles";
rev = "abc123def456..."; # Full commit hash for reproducibility rev = "abc123def456..."; # Full commit hash for reproducibility
ref = "main"; # Optional: branch/tag name ref = "main"; # Optional: branch/tag name
}; };
# Option 2: Local path for testing # Or use local path for testing
# home = /path/to/local/dotfiles; # external = /path/to/local/dotfiles;
# Option 3: Inline configuration
# home = {
# home.packages = [ pkgs.vim ];
# programs.git.enable = true;
# }; # };
}; };
}; };
@@ -63,7 +63,7 @@ Enable the user in `inventory.nix`:
"my-system" = { "my-system" = {
devices = { devices = {
"hostname" = { "hostname" = {
extraUsers = [ "myusername" ]; ugaif.users.myusername.enable = true;
}; };
}; };
}; };
@@ -72,18 +72,32 @@ Enable the user in `inventory.nix`:
## File Descriptions ## File Descriptions
### home.nix (Required) ### user.nix (Optional)
This file contains your home-manager configuration. It must be a valid NixOS module that accepts `{ inputs, ... }` and returns a home-manager configuration. This file serves dual purpose:
1. Sets `ugaif.users.<username>` options (description, shell, extraGroups, etc.)
2. Provides home-manager configuration (programs.*, home.*, services.*)
**Must export:** **How it works:**
- Home-manager options (programs.*, home.packages, etc.) - The `ugaif.users.<username>` options are extracted and loaded as **data** during module evaluation
- These options override any defaults set in `users.nix` (which uses `lib.mkDefault`)
- The home-manager options (`home.*`, `programs.*`, etc.) are imported as a module for home-manager
- External module options take precedence over `users.nix` base configuration
The same file is imported in two contexts:
- As a NixOS module to read ugaif.users options
- As a home-manager module for home.*, programs.*, services.*, etc.
Simply include both types of options in the same file.
**Receives:** **Receives:**
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.) - `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
- `config` - Home-manager config - `config` - Config (NixOS or home-manager depending on context)
- `lib` - Nixpkgs library
- `pkgs` - Nixpkgs package set - `pkgs` - Nixpkgs package set
- `osConfig` - Access to OS-level configuration - `osConfig` - (home-manager context only) OS-level configuration
**Example:** See `user.nix` template
### nixos.nix (Optional) ### nixos.nix (Optional)
@@ -92,16 +106,29 @@ This file contains system-level NixOS configuration. Only needed for:
- System packages requiring root - System packages requiring root
- Special permissions or system settings - Special permissions or system settings
**Receives:**
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
- `config` - NixOS config
- `lib` - Nixpkgs library
- `pkgs` - Nixpkgs package set
## Examples ## Examples
### Minimal home.nix ### Minimal user.nix
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, ... }: { config, lib, pkgs, ... }:
{ {
# User account options (imported as NixOS module)
ugaif.users.myuser = {
description = "My Name";
shell = pkgs.zsh;
extraGroups = [ "wheel" "networkmanager" ];
};
# Home-manager configuration (imported into home-manager)
home.packages = with pkgs; [ home.packages = with pkgs; [
vim vim
git git
@@ -120,10 +147,14 @@ This file contains system-level NixOS configuration. Only needed for:
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, ... }: { config, lib, pkgs, ... }:
{ {
ugaif.users.myuser = {
description = "My Name";
shell = pkgs.zsh;
};
home.packages = with pkgs; [ ripgrep fd bat ]; home.packages = with pkgs; [ ripgrep fd bat ];
# Symlink dotfiles # Symlink dotfiles
@@ -158,20 +189,22 @@ This file contains system-level NixOS configuration. Only needed for:
External user modules: External user modules:
- Receive the same flake inputs as nixos-systems - Receive the same flake inputs as nixos-systems
- Can use all home-manager options - Can set user options via user.nix (description, shell, extraGroups, etc.)
- Can use all home-manager options via home.nix
- Optionally provide system-level configuration (nixos.nix) - Optionally provide system-level configuration (nixos.nix)
- System zsh theme applied if `useZshTheme = true` (default) - System zsh theme applied if `useZshTheme = true` (default)
- System nvim config applied if `useNvimPlugins = true` (default) - System nvim config applied if `useNvimPlugins = true` (default)
- Merged with inventory.nix user settings (groups, shell, etc.) - Settings from user.nix override base users.nix definitions
## Development Workflow ## Development Workflow
1. Create your user config repository with `home.nix` 1. Create your user config repository with `user.nix`, `home.nix`, and/or `nixos.nix`
2. Test locally: `home = /path/to/local/repo;` 2. Set user options in user.nix OR in the main users.nix
3. Build: `nix build .#nixosConfigurations.hostname.config.system.build.toplevel` 3. Test locally: `external = /path/to/local/repo;`
4. Commit and push changes 4. Build: `nix build .#nixosConfigurations.hostname.config.system.build.toplevel`
5. Update users.nix with commit hash 5. Commit and push changes
6. Deploy to systems 6. Update users.nix with commit hash
7. Deploy to systems
## Benefits ## Benefits

13
templates/user/home.nix
View File

@@ -1,20 +1,29 @@
{ inputs, ... }: { inputs, ... }:
# ============================================================================ # ============================================================================
# User Home Manager Configuration Template # User Home Manager Configuration Template (Optional)
# ============================================================================ # ============================================================================
# This file provides home-manager configuration for a user. # This file provides home-manager configuration for a user.
# It will be imported into the NixOS system's home-manager configuration. # It will be imported into the NixOS system's home-manager configuration.
# #
# This file is optional - if not present, no home-manager configuration
# will be loaded from this external module.
#
# Usage in users.nix: # Usage in users.nix:
# myusername = { # myusername = {
# # Set user options here OR in the external module's user.nix
# description = "My Name"; # description = "My Name";
# home = builtins.fetchGit { # shell = pkgs.zsh;
# extraGroups = [ "wheel" "networkmanager" ];
#
# external = builtins.fetchGit {
# url = "https://github.com/username/dotfiles"; # url = "https://github.com/username/dotfiles";
# rev = "commit-hash"; # rev = "commit-hash";
# }; # };
# }; # };
# #
# Or use user.nix in your external module to set user options.
#
# This module receives the same `inputs` flake inputs as the main # This module receives the same `inputs` flake inputs as the main
# nixos-systems configuration (nixpkgs, home-manager, etc.). # nixos-systems configuration (nixpkgs, home-manager, etc.).

3
templates/user/nixos.nix
View File

@@ -11,6 +11,9 @@
# - Special system permissions or configurations # - Special system permissions or configurations
# - Installing system packages that require root # - Installing system packages that require root
# #
# Note: User options (description, shell, extraGroups, etc.) should be set
# in the main users.nix file, not here.
#
# This module receives the same `inputs` flake inputs as the main # This module receives the same `inputs` flake inputs as the main
# nixos-systems configuration. # nixos-systems configuration.

93
templates/user/user.nix Normal file
View File

@@ -0,0 +1,93 @@
{ inputs, ... }:
# ============================================================================
# User Configuration (Optional)
# ============================================================================
# This file can configure BOTH:
# 1. User account options (ugaif.users.<username>) when imported as NixOS module
# 2. Home-manager configuration (home.*, programs.*, services.*) when imported
# into home-manager
#
# This file is optional - if not present, these options should be set
# directly in the main users.nix file.
#
# This module receives the same `inputs` flake inputs as the main
# nixos-systems configuration (nixpkgs, home-manager, etc.).
{
config,
lib,
pkgs,
osConfig ? null, # Only available in home-manager context
...
}:
{
# ========== User Account Configuration ==========
# These are imported as a NixOS module to set ugaif.users options
# Replace "myusername" with your actual username
ugaif.users.myusername = {
description = "Your Full Name";
extraGroups = [
"wheel" # Sudo access
"networkmanager" # Network configuration
# "docker" # Docker access (if needed)
];
shell = pkgs.zsh;
# Optional: Override editor
# editor = pkgs.helix;
# Optional: Disable system theme/nvim plugins
# useZshTheme = false;
# useNvimPlugins = false;
# Optional: Add system-level packages
# extraPackages = with pkgs; [ docker ];
};
# Note: You don't need to set 'enable = true' - that's controlled
# per-host in inventory.nix
# ========== Home Manager Configuration ==========
# These are imported into home-manager for user environment
# System theme (zsh) and nvim config are applied automatically based on flags above
# Packages
home.packages = with pkgs; [
# Add your preferred packages here
# ripgrep
# fd
# bat
];
# ========== Programs ==========
# Git configuration
programs.git = {
enable = true;
userName = "Your Name";
userEmail = "your.email@example.com";
extraConfig = {
init.defaultBranch = "main";
};
};
# ========== Shell Environment ==========
home.sessionVariables = {
# EDITOR is set automatically based on ugaif.users.*.editor
# Add your custom environment variables here
};
# ========== Dotfiles ==========
# You can manage dotfiles with home.file
# home.file.".bashrc".source = ./dotfiles/bashrc;
# home.file.".vimrc".source = ./dotfiles/vimrc;
# Or use programs.* options for better integration
}

17
users.nix
View File

@@ -11,15 +11,16 @@
# To generate a password hash, run: mkpasswd -m sha-512 # To generate a password hash, run: mkpasswd -m sha-512
# Set enabled = true on systems where the user should exist # Set enabled = true on systems where the user should exist
# #
# External Home Configuration: # External User Configuration:
# Users can specify external home-manager configuration via the 'home' attribute: # Users can specify external configuration modules via the 'external' attribute:
# home = builtins.fetchGit { url = "..."; rev = "..."; }; # external = builtins.fetchGit { url = "..."; rev = "..."; };
# home = /path/to/local/config; # external = /path/to/local/config;
# home = { home.packages = [ ... ]; }; # Direct attrset
# #
# External repositories should contain: # External repositories can contain:
# - home.nix (required): Home-manager configuration # - user.nix (optional): Sets ugaif.users.<name> options AND home-manager config
# - nixos.nix (optional): System-level NixOS configuration # - nixos.nix (optional): System-level NixOS configuration
#
# User options can be set either in users.nix OR in the external module's user.nix.
ugaif.users = { ugaif.users = {
root = { root = {
isNormalUser = false; isNormalUser = false;
@@ -48,7 +49,7 @@
]; ];
home = builtins.fetchGit { home = builtins.fetchGit {
url = "https://git.factory.uga.edu/hdh20267/hdh20267-nix"; url = "https://git.factory.uga.edu/hdh20267/hdh20267-nix";
rev = "ea99aa55680cc937f186aef0efc0df307e79d56f"; rev = "db96137bb4cb16acefcf59d58c9f848924f2ad43";
}; };
}; };
sv22900 = { sv22900 = {