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

docs: General documentation update

Browse Source
This commit is contained in:
Hunter David Halloran
2025-12-17 19:39:02 -05:00
committed by Hunter Halloran
parent 9be51b2589
commit d97ece898c
12 changed files with 287 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/DEVELOPMENT.md
View File

@@ -305,16 +305,15 @@ nix-laptop = {
### User-Specific Packages
Add to user's home-manager configuration in `users.nix` or external dotfiles:
Add to user's home-manager configuration in their external `user.nix`:
```nix
myuser = {
homePackages = with pkgs; [
ripgrep
fd
bat
];
};
# In external user.nix
home.packages = with pkgs; [
ripgrep
fd
bat
];
```
### Search for Packages

132
docs/EXTERNAL_MODULES.md
View File

@@ -109,16 +109,18 @@ External user modules provide home-manager configurations (dotfiles, packages, p
```nix
ugaif.users = {
myuser = {
description = "My Name";
extraGroups = [ "wheel" "networkmanager" ];
# External user module (dotfiles, home-manager, and user options)
myuser = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
# Inline user definition
inlineuser = {
description = "Inline User";
extraGroups = [ "wheel" ];
shell = pkgs.zsh;
hashedPassword = "$6$...";
# External home-manager configuration
home = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
};
};
```
@@ -127,20 +129,35 @@ ugaif.users = {
```
dotfiles/
├── home.nix # Required: Home-manager config
├── user.nix # Required: User options AND home-manager config
├── nixos.nix # Optional: System-level config
└── dotfiles/ # Optional: Actual dotfiles
└── config/ # Optional: Actual dotfiles
├── bashrc
└── vimrc
```
**home.nix (required):**
**user.nix (required):**
```nix
{ inputs, ... }:
{ config, lib, pkgs, osConfig, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
# Home-manager configuration
home.packages = with pkgs; [ vim git htop ];
# ========== User Account Configuration ==========
ugaif.users.myusername = {
description = "Your Full Name";
shell = pkgs.zsh;
hashedPassword = "!";
opensshKeys = [ "ssh-ed25519 AAAA..." ];
useZshTheme = true;
useNvimPlugins = true;
};
# ========== Home Manager Configuration ==========
# Packages
home.packages = with pkgs; [
vim
git
htop
] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
programs.git = {
enable = true;
@@ -166,7 +183,7 @@ dotfiles/
### What User Modules Receive
**In home.nix:**
**In user.nix:**
- **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.)
- **`config`** - Home-manager configuration
- **`lib`** - Nixpkgs library functions
@@ -187,8 +204,7 @@ username = {
description = "Full Name";
# External configuration
home = builtins.fetchGit { ... };
external = builtins.fetchGit { ... };
# System settings
extraGroups = [ "wheel" "networkmanager" ];
hashedPassword = "$6$...";
@@ -325,16 +341,24 @@ They can use all standard NixOS options plus `ugaif.*` namespace options.
### User Module Integration
External user modules are loaded separately for home-manager (`home.nix`) and NixOS (`nixos.nix` if it exists):
External user modules are loaded in two contexts:
**Home-manager:**
**User options (NixOS module context):**
```nix
import (externalHomePath + "/home.nix") { inherit inputs; }
import (externalPath + "/user.nix") { inherit inputs; }
# Evaluated as NixOS module to extract ugaif.users.<username> options
```
**NixOS (optional):**
**Home-manager configuration:**
```nix
import (externalHomePath + "/nixos.nix") { inherit inputs; }
import (externalPath + "/user.nix") { inherit inputs; }
# Imported into home-manager for home.*, programs.*, services.* options
```
**System-level config (optional):**
```nix
import (externalPath + "/nixos.nix") { inherit inputs; }
# If present, imported as NixOS module for system-level configuration
```
### Combining External and Local Config
@@ -357,27 +381,21 @@ nix-lxc = {
};
```
## Examples
### Minimal System Module
**default.nix:**
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{
ugaif.sw.type = "headless";
services.nginx.enable = true;
}
```
### Minimal User Module
**home.nix:**
**user.nix:**
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
# User account options
ugaif.users.myusername = {
description = "My Name";
shell = pkgs.zsh;
hashedPassword = "!";
};
# Home-manager config
home.packages = with pkgs; [ vim git ];
}
```
@@ -386,7 +404,7 @@ nix-lxc = {
```
dotfiles/
├── home.nix
├── user.nix
├── nixos.nix
└── config/
├── bashrc
@@ -394,12 +412,35 @@ dotfiles/
└── gitconfig
```
**home.nix:**
**user.nix:**
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
home.packages = with pkgs; [ ripgrep fd bat ];
# User account configuration
ugaif.users.myusername = {
description = "My Full Name";
shell = pkgs.zsh;
extraGroups = [ "wheel" "networkmanager" ];
hashedPassword = "!";
opensshKeys = [ "ssh-ed25519 AAAA..." ];
useZshTheme = true;
useNvimPlugins = true;
};
# Home-manager configuration
home.packages = with pkgs; [
ripgrep
fd
bat
] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
programs.git = {
enable = true;
userName = "My Full Name";
userEmail = "me@example.com";
extraConfig.init.defaultBranch = "main";
};
home.file = {
".bashrc".source = ./config/bashrc;
@@ -411,8 +452,9 @@ dotfiles/
## See Also
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration guide
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options reference
- [INVENTORY.md](INVENTORY.md) - Host configuration guide
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
- [templates/system/](../templates/system/) - System module template
- [templates/user/](../templates/user/) - User module template
- [README.md](../README.md) - Main documentation

18
docs/NAMESPACE.md
View File

@@ -199,6 +199,7 @@ ugaif.users = {
Each user in `users.nix` can be configured with:
```nix
# Option 1: Define inline in users.nix
ugaif.users.myuser = {
description = "Full Name";
isNormalUser = true; # Default: true
@@ -206,18 +207,18 @@ ugaif.users.myuser = {
shell = pkgs.zsh; # Login shell
hashedPassword = "$6$..."; # Hashed password
opensshKeys = [ "ssh-ed25519 ..." ]; # SSH public keys
homePackages = with pkgs; [ ... ]; # User packages
useZshTheme = true; # Use system Zsh theme
useNvimPlugins = true; # Use system Neovim config
# External home-manager configuration (optional)
home = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
enable = false; # Enable per-system in inventory.nix
};
# Option 2: Use external configuration (recommended)
# The external user.nix can set ugaif.users.myuser options directly
ugaif.users.anotheruser.external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
```
## System Configuration (`ugaif.system`)
@@ -271,5 +272,6 @@ nix-wsl = {
## See Also
- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
- [USER_CONFIGURATION.md](../USER_CONFIGURATION.md) - User management guide
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
- [README.md](../README.md) - Main documentation

81
docs/USER_CONFIGURATION.md
View File

@@ -27,6 +27,7 @@ Users are defined in `users.nix` but are **not enabled by default** on all syste
```nix
ugaif.users = {
# Option 1: Inline definition
myuser = {
description = "My Full Name";
extraGroups = [ "wheel" "networkmanager" ];
@@ -36,6 +37,12 @@ ugaif.users = {
"ssh-ed25519 AAAA... user@machine"
];
};
# Option 2: External configuration (recommended for personalization)
myuser.external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123..."; # Pin to specific commit
};
};
```
@@ -93,14 +100,6 @@ username = {
# === External Configuration ===
external = builtins.fetchGit { ... }; # External user module (see below)
# OR (if not using external config):
homePackages = with pkgs; [ # User packages
ripgrep
fd
bat
];
extraImports = [ ./my-module.nix ]; # Additional home-manager modules
# === Theme Integration ===
useZshTheme = true; # Apply system Zsh theme (default: true)
useNvimPlugins = true; # Apply system Neovim config (default: true)
@@ -137,7 +136,7 @@ myuser = {
```
dotfiles/
├── user.nix # Optional: User options AND home-manager config
├── user.nix # Required: User options AND home-manager config
├── nixos.nix # Optional: System-level configuration
└── config/ # Optional: Your dotfiles
├── bashrc
@@ -145,32 +144,42 @@ dotfiles/
└── ...
```
**Both `.nix` files are optional, but at least one should be present.**
**At least `user.nix` should be present for a functional user module.**
**user.nix (optional):**
**user.nix (required):**
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
# User account options (imported as NixOS module)
# ========== User Account Configuration ==========
# These options define the user account itself
ugaif.users.myuser = {
description = "My Full Name";
extraGroups = [ "wheel" "docker" ];
shell = pkgs.zsh;
hashedPassword = "!";
opensshKeys = [
"ssh-ed25519 AAAA... user@host"
];
useZshTheme = true;
useNvimPlugins = true;
};
# Home-manager configuration (imported into home-manager)
# ========== Home Manager Configuration ==========
# User environment, packages, and dotfiles
home.packages = with pkgs; [
vim
ripgrep
];
] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
programs.git = {
enable = true;
userName = "My Name";
userEmail = "me@example.com";
extraConfig = {
init.defaultBranch = "main";
};
};
home.file.".bashrc".source = ./config/bashrc;
@@ -199,13 +208,15 @@ dotfiles/
### How External Modules Are Loaded
The `user.nix` module is used in two ways:
The `user.nix` module serves a dual purpose and is imported in **two contexts**:
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`).
1. **NixOS Module Context (User Options)**: The module is imported as a NixOS module where `ugaif.users.<username>` options are read to define the user account (description, shell, groups, SSH keys, etc.). These options override any defaults set in `users.nix`.
2. **Home-Manager Configuration**: The entire module (including `home.*`, `programs.*`, `services.*` options) is imported into home-manager as a configuration module.
2. **Home-Manager Context**: The same module is imported into home-manager where `home.*`, `programs.*`, and `services.*` options configure the user's environment, packages, and dotfiles.
This means you can define both user account settings AND home-manager configuration in a single file.
**Key insight:** A single `user.nix` file contains both account configuration AND home environment configuration. The system automatically imports it in the appropriate contexts.
**Example:** The user account options (like `shell`, `extraGroups`) are read during NixOS evaluation, while home-manager options (like `home.packages`, `programs.git`) are used when building the user's home environment.
**In nixos.nix:**
- `inputs` - Flake inputs
@@ -220,17 +231,7 @@ This means you can define both user account settings AND home-manager configurat
external = /home/username/dev/dotfiles;
```
**Note:** User options can be set in users.nix OR in the external module's user.nix file.
**No external config:**
```nix
# Configure everything directly in users.nix
myuser = {
description = "My Name";
homePackages = with pkgs; [ vim git ];
# external is null by default
};
```
**Note:** User options can be set in users.nix OR in the external module's user.nix file. For custom packages and environment configuration without external modules, create a local module and reference it with `extraImports`.
### Create User Template
@@ -380,7 +381,7 @@ admin = {
};
```
### User with External Dotfiles
### User with External Configuration
```nix
developer = {
@@ -388,7 +389,7 @@ developer = {
extraGroups = [ "wheel" "docker" ];
shell = pkgs.zsh;
hashedPassword = "$6$...";
home = builtins.fetchGit {
external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123def456...";
};
@@ -403,7 +404,7 @@ wsl-user = {
extraGroups = [ "wheel" ];
shell = pkgs.zsh;
hashedPassword = "$6$...";
home = builtins.fetchGit {
external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
@@ -429,7 +430,7 @@ poweruser = {
hashedPassword = "$6$...";
useZshTheme = false; # Don't apply system theme
useNvimPlugins = false; # Don't apply system nvim config
home = builtins.fetchGit {
external = builtins.fetchGit {
url = "https://github.com/username/custom-dotfiles";
rev = "abc123...";
};
@@ -492,19 +493,19 @@ git ls-remote https://github.com/username/dotfiles
```
**Verify structure:**
- Must have `home.nix` at repository root
- Must have `user.nix` at repository root
- `nixos.nix` is optional
- Check file permissions
**Test with local path first:**
```nix
home = /path/to/local/dotfiles;
external = /path/to/local/dotfiles;
```
## See Also
- [docs/EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
- [INVENTORY.md](INVENTORY.md) - Host configuration guide
- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
- [templates/user/](../templates/user/) - User module template
- [README.md](../README.md) - Main documentation