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

Merge pull request #10 from UGA-Innovation-Factory/documentation-patch

Browse Source 
documentation update
This commit is contained in:
Hunter David Halloran
2025-12-17 19:41:44 -05:00
committed by GitHub
parent fb6ac75f3c ab3b4a017d
commit 6ee51cd747
11 changed files with 272 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.github/copilot-instructions.md vendored
View File

@@ -107,7 +107,7 @@ ugaif.forUser = "username"; # Convenience: enable user + set WSL user
#### Creating External Modules #### Creating External Modules
1. Use templates: `nix flake init -t github:UGA-Innovation-Factory/nixos-systems#{user|system}` 1. Use templates: `nix flake init -t github:UGA-Innovation-Factory/nixos-systems#{user|system}`
2. User modules: Provide `home.nix` (required) and `nixos.nix` (optional) 2. User modules: Provide `user.nix` (required) and `nixos.nix` (optional)
3. System modules: Provide `default.nix` that accepts `{ inputs, ... }` 3. System modules: Provide `default.nix` that accepts `{ inputs, ... }`
4. Reference in `inventory.nix` or `users.nix` using `builtins.fetchGit` 4. Reference in `inventory.nix` or `users.nix` using `builtins.fetchGit`
@@ -135,13 +135,12 @@ This repository supports external configurations via Git repositories:
### User Configurations (Dotfiles) ### User Configurations (Dotfiles)
```nix ```nix
# In users.nix # In users.nix
myuser = { myuser.external = builtins.fetchGit {
description = "My Name"; url = "https://github.com/username/dotfiles";
home = builtins.fetchGit { rev = "abc123..."; # Pin to specific commit
url = "https://github.com/username/dotfiles";
rev = "abc123..."; # Pin to specific commit
};
}; };
# The external user.nix file contains BOTH user account options
# (ugaif.users.myuser) AND home-manager configuration
``` ```
### System Configurations ### System Configurations
@@ -157,7 +156,7 @@ nix-lxc = {
**Key Points:** **Key Points:**
- External modules receive `{ inputs }` parameter with flake inputs - External modules receive `{ inputs }` parameter with flake inputs
- User modules must provide `home.nix` (home-manager config) - User modules must provide `user.nix` (user options AND home-manager config)
- System modules must provide `default.nix` (NixOS module) - System modules must provide `default.nix` (NixOS module)
- Always pin to specific commit hash (`rev`) for reproducibility - Always pin to specific commit hash (`rev`) for reproducibility

13
README.md
View File

@@ -175,14 +175,13 @@ nix-desktop = {
Users and systems can reference external Git repositories for configuration: Users and systems can reference external Git repositories for configuration:
```nix ```nix
# In users.nix - External dotfiles # In users.nix - External dotfiles with user configuration
myuser = { myuser.external = builtins.fetchGit {
description = "My Name"; url = "https://github.com/username/dotfiles";
home = builtins.fetchGit { rev = "abc123...";
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
}; };
# The external user.nix file contains both ugaif.users.myuser options
# AND home-manager configuration
# In inventory.nix - External system config # In inventory.nix - External system config
nix-lxc = { nix-lxc = {

15
docs/DEVELOPMENT.md
View File

@@ -305,16 +305,15 @@ nix-laptop = {
### User-Specific Packages ### 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 ```nix
myuser = { # In external user.nix
homePackages = with pkgs; [ home.packages = with pkgs; [
ripgrep ripgrep
fd fd
bat bat
]; ];
};
``` ```
### Search for Packages ### 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 ```nix
ugaif.users = { ugaif.users = {
myuser = { # External user module (dotfiles, home-manager, and user options)
description = "My Name"; myuser = builtins.fetchGit {
extraGroups = [ "wheel" "networkmanager" ]; url = "https://github.com/username/dotfiles";
hashedPassword = "$6$..."; rev = "abc123...";
};
# External home-manager configuration # Inline user definition
home = builtins.fetchGit { inlineuser = {
url = "https://github.com/username/dotfiles"; description = "Inline User";
rev = "abc123..."; extraGroups = [ "wheel" ];
}; shell = pkgs.zsh;
hashedPassword = "$6$...";
}; };
}; };
``` ```
@@ -127,20 +129,35 @@ ugaif.users = {
``` ```
dotfiles/ dotfiles/
├── home.nix # Required: Home-manager config ├── user.nix # Required: User options AND home-manager config
├── nixos.nix # Optional: System-level config ├── nixos.nix # Optional: System-level config
└── dotfiles/ # Optional: Actual dotfiles └── config/ # Optional: Actual dotfiles
├── bashrc ├── bashrc
└── vimrc └── vimrc
``` ```
**home.nix (required):** **user.nix (required):**
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, osConfig, ... }: { config, lib, pkgs, osConfig ? null, ... }:
{ {
# Home-manager configuration # ========== User Account Configuration ==========
home.packages = with pkgs; [ vim git htop ]; 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 = { programs.git = {
enable = true; enable = true;
@@ -166,7 +183,7 @@ dotfiles/
### What User Modules Receive ### What User 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`** - Home-manager configuration
- **`lib`** - Nixpkgs library functions - **`lib`** - Nixpkgs library functions
@@ -187,8 +204,7 @@ username = {
description = "Full Name"; description = "Full Name";
# External configuration # External configuration
home = builtins.fetchGit { ... }; external = builtins.fetchGit { ... };
# System settings # System settings
extraGroups = [ "wheel" "networkmanager" ]; extraGroups = [ "wheel" "networkmanager" ];
hashedPassword = "$6$..."; hashedPassword = "$6$...";
@@ -325,16 +341,24 @@ They can use all standard NixOS options plus `ugaif.*` namespace options.
### User Module Integration ### 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 ```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 ```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 ### 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 ### Minimal User Module
**home.nix:** **user.nix:**
```nix ```nix
{ inputs, ... }: { 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 ]; home.packages = with pkgs; [ vim git ];
} }
``` ```
@@ -386,7 +404,7 @@ nix-lxc = {
``` ```
dotfiles/ dotfiles/
├── home.nix ├── user.nix
├── nixos.nix ├── nixos.nix
└── config/ └── config/
├── bashrc ├── bashrc
@@ -394,12 +412,35 @@ dotfiles/
└── gitconfig └── gitconfig
``` ```
**home.nix:** **user.nix:**
```nix ```nix
{ inputs, ... }: { 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 = { home.file = {
".bashrc".source = ./config/bashrc; ".bashrc".source = ./config/bashrc;
@@ -411,8 +452,9 @@ dotfiles/
## See Also ## See Also
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration guide - [INVENTORY.md](INVENTORY.md) - Host configuration guide
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options reference - [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide
- [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
- [templates/system/](../templates/system/) - System module template - [templates/system/](../templates/system/) - System module template
- [templates/user/](../templates/user/) - User module template - [templates/user/](../templates/user/) - User module template
- [README.md](../README.md) - Main documentation - [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: Each user in `users.nix` can be configured with:
```nix ```nix
# Option 1: Define inline in users.nix
ugaif.users.myuser = { ugaif.users.myuser = {
description = "Full Name"; description = "Full Name";
isNormalUser = true; # Default: true isNormalUser = true; # Default: true
@@ -206,18 +207,18 @@ ugaif.users.myuser = {
shell = pkgs.zsh; # Login shell shell = pkgs.zsh; # Login shell
hashedPassword = "$6$..."; # Hashed password hashedPassword = "$6$..."; # Hashed password
opensshKeys = [ "ssh-ed25519 ..." ]; # SSH public keys opensshKeys = [ "ssh-ed25519 ..." ]; # SSH public keys
homePackages = with pkgs; [ ... ]; # User packages
useZshTheme = true; # Use system Zsh theme useZshTheme = true; # Use system Zsh theme
useNvimPlugins = true; # Use system Neovim config 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 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`) ## System Configuration (`ugaif.system`)
@@ -271,5 +272,6 @@ nix-wsl = {
## See Also ## See Also
- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide - [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 - [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 ```nix
ugaif.users = { ugaif.users = {
# Option 1: Inline definition
myuser = { myuser = {
description = "My Full Name"; description = "My Full Name";
extraGroups = [ "wheel" "networkmanager" ]; extraGroups = [ "wheel" "networkmanager" ];
@@ -36,6 +37,12 @@ ugaif.users = {
"ssh-ed25519 AAAA... user@machine" "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 Configuration ===
external = builtins.fetchGit { ... }; # External user module (see below) 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 === # === Theme Integration ===
useZshTheme = true; # Apply system Zsh theme (default: true) useZshTheme = true; # Apply system Zsh theme (default: true)
useNvimPlugins = true; # Apply system Neovim config (default: true) useNvimPlugins = true; # Apply system Neovim config (default: true)
@@ -137,7 +136,7 @@ myuser = {
``` ```
dotfiles/ 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 ├── nixos.nix # Optional: System-level configuration
└── config/ # Optional: Your dotfiles └── config/ # Optional: Your dotfiles
├── bashrc ├── 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 ```nix
{ inputs, ... }: { 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 = { ugaif.users.myuser = {
description = "My Full Name"; description = "My Full Name";
extraGroups = [ "wheel" "docker" ]; extraGroups = [ "wheel" "docker" ];
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "!";
opensshKeys = [
"ssh-ed25519 AAAA... user@host"
];
useZshTheme = true; useZshTheme = true;
useNvimPlugins = true;
}; };
# Home-manager configuration (imported into home-manager) # ========== Home Manager Configuration ==========
# User environment, packages, and dotfiles
home.packages = with pkgs; [ home.packages = with pkgs; [
vim vim
ripgrep ripgrep
]; ] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
programs.git = { programs.git = {
enable = true; enable = true;
userName = "My Name"; userName = "My Name";
userEmail = "me@example.com"; userEmail = "me@example.com";
extraConfig = {
init.defaultBranch = "main";
};
}; };
home.file.".bashrc".source = ./config/bashrc; home.file.".bashrc".source = ./config/bashrc;
@@ -199,13 +208,15 @@ dotfiles/
### How External Modules Are Loaded ### 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:** **In nixos.nix:**
- `inputs` - Flake inputs - `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; external = /home/username/dev/dotfiles;
``` ```
**Note:** User options can be set in users.nix OR in the external module's user.nix file. **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`.
**No external config:**
```nix
# Configure everything directly in users.nix
myuser = {
description = "My Name";
homePackages = with pkgs; [ vim git ];
# external is null by default
};
```
### Create User Template ### Create User Template
@@ -380,7 +381,7 @@ admin = {
}; };
``` ```
### User with External Dotfiles ### User with External Configuration
```nix ```nix
developer = { developer = {
@@ -388,7 +389,7 @@ developer = {
extraGroups = [ "wheel" "docker" ]; extraGroups = [ "wheel" "docker" ];
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "$6$..."; hashedPassword = "$6$...";
home = builtins.fetchGit { external = builtins.fetchGit {
url = "https://github.com/username/dotfiles"; url = "https://github.com/username/dotfiles";
rev = "abc123def456..."; rev = "abc123def456...";
}; };
@@ -403,7 +404,7 @@ wsl-user = {
extraGroups = [ "wheel" ]; extraGroups = [ "wheel" ];
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "$6$..."; hashedPassword = "$6$...";
home = builtins.fetchGit { external = builtins.fetchGit {
url = "https://github.com/username/dotfiles"; url = "https://github.com/username/dotfiles";
rev = "abc123..."; rev = "abc123...";
}; };
@@ -429,7 +430,7 @@ poweruser = {
hashedPassword = "$6$..."; hashedPassword = "$6$...";
useZshTheme = false; # Don't apply system theme useZshTheme = false; # Don't apply system theme
useNvimPlugins = false; # Don't apply system nvim config useNvimPlugins = false; # Don't apply system nvim config
home = builtins.fetchGit { external = builtins.fetchGit {
url = "https://github.com/username/custom-dotfiles"; url = "https://github.com/username/custom-dotfiles";
rev = "abc123..."; rev = "abc123...";
}; };
@@ -492,19 +493,19 @@ git ls-remote https://github.com/username/dotfiles
``` ```
**Verify structure:** **Verify structure:**
- Must have `home.nix` at repository root - Must have `user.nix` at repository root
- `nixos.nix` is optional - `nixos.nix` is optional
- Check file permissions - Check file permissions
**Test with local path first:** **Test with local path first:**
```nix ```nix
home = /path/to/local/dotfiles; external = /path/to/local/dotfiles;
``` ```
## See Also ## See Also
- [docs/EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide - [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration - [INVENTORY.md](INVENTORY.md) - Host configuration guide
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options - [NAMESPACE.md](NAMESPACE.md) - Configuration options reference
- [templates/user/](../templates/user/) - User module template - [templates/user/](../templates/user/) - User module template
- [README.md](../README.md) - Main documentation - [README.md](../README.md) - Main documentation

6
templates/default.nix
View File

@@ -20,7 +20,7 @@
user = { user = {
path = ./user; path = ./user;
description = "External user home-manager configuration"; description = "External user configuration module";
welcomeText = '' welcomeText = ''
# User Configuration Template # User Configuration Template
@@ -29,10 +29,10 @@
## Quick Start ## Quick Start
1. Edit `home.nix` with your home-manager configuration 1. Edit `user.nix` with user account options and home-manager configuration
2. (Optional) Edit `nixos.nix` for system-level configuration 2. (Optional) Edit `nixos.nix` for system-level configuration
3. Commit to a Git repository 3. Commit to a Git repository
4. Reference in users.nix using the `flakeUrl` field 4. Reference in users.nix using external = builtins.fetchGit { ... }
See README.md for detailed documentation. See README.md for detailed documentation.
''; '';

106
templates/user/README.md
View File

@@ -10,46 +10,47 @@ External user modules allow users to maintain their personal configurations (dot
``` ```
user-dotfiles-repo/ user-dotfiles-repo/
├── user.nix # Optional: User options AND home-manager configuration ├── user.nix # Required: 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 └── config/ # Optional: Dotfiles to symlink
├── bashrc
└── vimrc
``` ```
**Note:** Both `.nix` files are optional, but at least one should be present for the module to be useful. **Note:** The `user.nix` file is required for a functional user module. It should contain both `ugaif.users.<username>` options and home-manager configuration.
## Usage ## Usage
### 1. Create Your User Configuration Repository ### 1. Create Your User Configuration Repository
Copy the templates from this directory to your own Git repository: Copy the templates from this directory to your own Git repository:
- `home.nix` - Required for home-manager configuration - `user.nix` - Required: Contains both user account options and home-manager configuration
- `nixos.nix` - Optional for system-level configuration - `nixos.nix` - Optional: System-level NixOS configuration (e.g., system services, extra groups)
### 2. Reference It in users.nix ### 2. Reference It in users.nix
```nix ```nix
{ {
ugaif.users = { ugaif.users = {
myusername = { # Option 1: Define inline (without external module)
# Option 1: Set user options in users.nix inlineuser = {
description = "My Name"; description = "My Name";
extraGroups = [ "wheel" "networkmanager" ]; extraGroups = [ "wheel" "networkmanager" ];
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "$6$...";
# Option 2: Or let the external module's user.nix set these options
# Reference external dotfiles module
external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123def456..."; # Full commit hash for reproducibility
ref = "main"; # Optional: branch/tag name
};
# Or use local path for testing
# external = /path/to/local/dotfiles;
# };
}; };
# Option 2: Use external module (recommended for personal configs)
# The external user.nix will set ugaif.users.myusername options
myusername.external = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123def456..."; # Full commit hash for reproducibility
ref = "main"; # Optional: branch/tag name
};
# Or use local path for testing
# myusername.external = /path/to/local/dotfiles;
}; };
} }
``` ```
@@ -72,30 +73,26 @@ Enable the user in `inventory.nix`:
## File Descriptions ## File Descriptions
### user.nix (Optional) ### user.nix (Required)
This file serves dual purpose: This file serves a dual purpose and is imported in **two contexts**:
1. Sets `ugaif.users.<username>` options (description, shell, extraGroups, etc.)
2. Provides home-manager configuration (programs.*, home.*, services.*) 1. **NixOS Module Context**: Imported to read `ugaif.users.<username>` options that define the user account (description, shell, groups, SSH keys, etc.)
2. **Home-Manager Context**: Imported to configure the user environment with `home.*`, `programs.*`, and `services.*` options
**How it works:** **How it works:**
- The `ugaif.users.<username>` options are extracted and loaded as **data** during module evaluation - The same file is evaluated twice in different contexts
- These options override any defaults set in `users.nix` (which uses `lib.mkDefault`) - User account options (`ugaif.users.<username>`) are read during NixOS evaluation
- The home-manager options (`home.*`, `programs.*`, etc.) are imported as a module for home-manager - Home-manager options are used when building the user's environment
- External module options take precedence over `users.nix` base configuration - External module options override any defaults set in `users.nix`
- You can conditionally include packages/config based on system type using `osConfig`
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` - Config (NixOS or home-manager depending on context) - `config` - Configuration (NixOS or home-manager depending on context)
- `lib` - Nixpkgs library - `lib` - Nixpkgs library functions
- `pkgs` - Nixpkgs package set - `pkgs` - Nixpkgs package set
- `osConfig` - (home-manager context only) OS-level configuration - `osConfig` - (home-manager context only) Read-only access to OS configuration
**Example:** See `user.nix` template **Example:** See `user.nix` template
@@ -118,17 +115,20 @@ This file contains system-level NixOS configuration. Only needed for:
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, ... }: { config, lib, pkgs, osConfig ? null, ... }:
{ {
# User account options (imported as NixOS module) # User account options
ugaif.users.myuser = { ugaif.users.myuser = {
description = "My Name"; description = "My Name";
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "!";
extraGroups = [ "wheel" "networkmanager" ]; extraGroups = [ "wheel" "networkmanager" ];
opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
useZshTheme = true;
useNvimPlugins = true;
}; };
# Home-manager configuration (imported into home-manager) # Home-manager configuration
home.packages = with pkgs; [ home.packages = with pkgs; [
vim vim
git git
@@ -139,6 +139,7 @@ This file contains system-level NixOS configuration. Only needed for:
enable = true; enable = true;
userName = "My Name"; userName = "My Name";
userEmail = "me@example.com"; userEmail = "me@example.com";
extraConfig.init.defaultBranch = "main";
}; };
} }
``` ```
@@ -147,24 +148,31 @@ This file contains system-level NixOS configuration. Only needed for:
```nix ```nix
{ inputs, ... }: { inputs, ... }:
{ config, lib, pkgs, ... }: { config, lib, pkgs, osConfig ? null, ... }:
{ {
ugaif.users.myuser = { ugaif.users.myuser = {
description = "My Name"; description = "My Name";
shell = pkgs.zsh; shell = pkgs.zsh;
hashedPassword = "!";
extraGroups = [ "wheel" ];
opensshKeys = [ "ssh-ed25519 AAAA..." ];
}; };
home.packages = with pkgs; [ ripgrep fd bat ]; home.packages = with pkgs; [
ripgrep
fd
bat
] ++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
# Symlink dotfiles # Symlink dotfiles
home.file.".bashrc".source = ./dotfiles/bashrc; home.file.".bashrc".source = ./config/bashrc;
home.file.".vimrc".source = ./dotfiles/vimrc; home.file.".vimrc".source = ./config/vimrc;
programs.git = { programs.git = {
enable = true; enable = true;
userName = "My Name"; userName = "My Name";
userEmail = "me@example.com"; userEmail = "me@example.com";
extraConfig.init.defaultBranch = "main";
}; };
} }
``` ```
@@ -189,11 +197,13 @@ 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 set user options via user.nix (description, shell, home-manager, etc.) - Define both user account options AND home-manager config in user.nix
- Single file is imported in two contexts (NixOS module + home-manager module)
- Can access OS configuration via `osConfig` parameter in home-manager context
- 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)
- Settings from user.nix override base users.nix definitions - Settings from external user.nix override base users.nix definitions
## Development Workflow ## Development Workflow

9
templates/user/nixos.nix
View File

@@ -4,16 +4,15 @@
# User NixOS System Configuration (Optional) # User NixOS System Configuration (Optional)
# ============================================================================ # ============================================================================
# This file provides system-level NixOS configuration for a user. # This file provides system-level NixOS configuration for a user.
# It's optional - most user configuration should go in home.nix. # It's optional - most user configuration should go in user.nix.
# #
# Use this for: # Use this for:
# - System-level services that depend on the user (e.g., user systemd services) # - System-level services that depend on the user (e.g., user systemd services)
# - 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 # Note: User options (description, shell, extraGroups, etc.) AND home-manager
# in your external module's user.nix or in the main users.nix file, not in # configuration should be set in user.nix, not in this nixos.nix.
# this nixos.nix.
# #
# 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.
@@ -47,5 +46,5 @@
# Example: Add user to additional groups # Example: Add user to additional groups
# users.users.myusername.extraGroups = [ "docker" ]; # users.users.myusername.extraGroups = [ "docker" ];
# Most configuration should be in home.nix instead of here # Most configuration should be in user.nix instead of here
} }

74
templates/user/user.nix
View File

@@ -1,16 +1,15 @@
{ inputs, ... }: { inputs, ... }:
# ============================================================================ # ============================================================================
# User Configuration (Optional) # User Configuration
# ============================================================================ # ============================================================================
# This file can configure BOTH: # This file configures BOTH:
# 1. User account options (ugaif.users.<username>) when imported as NixOS module # 1. User account options (ugaif.users.<username>)
# 2. Home-manager configuration (home.*, programs.*, services.*) when imported # 2. Home-manager configuration (home.*, programs.*, services.*)
# into home-manager
# #
# This file is optional - if not present, the system will use the defaults # The same file is imported in two contexts:
# from the main users.nix file. Use this file to override or extend those # - As a NixOS module to read ugaif.users.<username> options
# default user and home-manager options for this user. # - As a home-manager module for user environment configuration
# #
# 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.).
@@ -25,45 +24,44 @@
{ {
# ========== User Account Configuration ========== # ========== User Account Configuration ==========
# These are imported as a NixOS module to set ugaif.users options
# Replace "myusername" with your actual username # Replace "myusername" with your actual username
ugaif.users.myusername = { ugaif.users.myusername = {
description = "Your Full Name"; description = "Your Full Name";
shell = pkgs.zsh;
hashedPassword = "!"; # Locked password - use SSH keys only
extraGroups = [ extraGroups = [
"wheel" # Sudo access "wheel" # Sudo access
"networkmanager" # Network configuration "networkmanager" # Network configuration
# "docker" # Docker access (if needed) # "docker" # Docker access (if needed)
]; ];
shell = pkgs.zsh; opensshKeys = [
# Add your SSH public keys here
# "ssh-ed25519 AAAA... user@machine"
];
# Optional: Override editor useZshTheme = true; # Apply system Zsh theme
# editor = pkgs.helix; useNvimPlugins = true; # Apply system Neovim plugins
# 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 # Note: You don't need to set 'enable = true' - that's controlled
# per-host in inventory.nix # per-host in inventory.nix via ugaif.users.myusername.enable
# ========== Home Manager Configuration ========== # ========== 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 # Packages
home.packages = with pkgs; [ home.packages =
# Add your preferred packages here with pkgs;
# ripgrep [
# fd htop
# bat ripgrep
]; fd
bat
]
++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
# Conditionally add packages based on system type
# ========== Programs ========== # ========== Programs ==========
@@ -77,18 +75,28 @@
}; };
}; };
# Zsh configuration
programs.zsh = {
enable = true;
# System theme is applied automatically if useZshTheme = true
};
# ========== Shell Environment ========== # ========== Shell Environment ==========
home.sessionVariables = { home.sessionVariables = {
# EDITOR is set automatically based on ugaif.users.*.editor EDITOR = "nvim";
# Add your custom environment variables here # Add your custom environment variables here
}; };
# ========== XDG Configuration ==========
xdg.enable = true;
# ========== Dotfiles ========== # ========== Dotfiles ==========
# You can manage dotfiles with home.file # You can manage dotfiles with home.file
# home.file.".bashrc".source = ./dotfiles/bashrc; # home.file.".bashrc".source = ./config/bashrc;
# home.file.".vimrc".source = ./dotfiles/vimrc; # home.file.".vimrc".source = ./config/vimrc;
# Or use programs.* options for better integration # Or use programs.* options for better integration (recommended)
} }

11
users.nix
View File

@@ -16,11 +16,16 @@
# external = builtins.fetchGit { url = "..."; rev = "..."; }; # external = builtins.fetchGit { url = "..."; rev = "..."; };
# external = /path/to/local/config; # external = /path/to/local/config;
# #
# External repositories can contain: # External repositories should contain:
# - user.nix (optional): Sets ugaif.users.<name> options AND home-manager config # - user.nix (required): Defines 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. # The user.nix file is imported in TWO contexts:
# 1. As a NixOS module to read ugaif.users.<name> options (account settings)
# 2. As a home-manager module for home.*, programs.*, services.* (user environment)
#
# User options can be set in users.nix OR in the external module's user.nix.
# External module options take precedence over users.nix defaults.
ugaif.users = { ugaif.users = {
root = { root = {
isNormalUser = false; isNormalUser = false;