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
.github/copilot-instructions.md vendored
View File

@@ -107,7 +107,7 @@ ugaif.forUser = "username"; # Convenience: enable user + set WSL user
#### Creating External Modules
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, ... }`
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)
```nix
# In users.nix
myuser = {
description = "My Name";
home = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123..."; # Pin to specific commit
};
myuser.external = builtins.fetchGit {
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
@@ -157,7 +156,7 @@ nix-lxc = {
**Key Points:**
- 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)
- 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:
```nix
# In users.nix - External dotfiles
myuser = {
description = "My Name";
home = builtins.fetchGit {
url = "https://github.com/username/dotfiles";
rev = "abc123...";
};
# In users.nix - External dotfiles with user configuration
myuser.external = builtins.fetchGit {
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
nix-lxc = {

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

30
flake.lock generated
View File

@@ -115,11 +115,11 @@
]
},
"locked": {
"lastModified": 1765326679,
"narHash": "sha256-fTLX9kDwLr9Y0rH/nG+h1XG5UU+jBcy0PFYn5eneRX8=",
"lastModified": 1765794845,
"narHash": "sha256-YD5QWlGnusNbZCqR3pxG8tRxx9yUXayLZfAJRWspq2s=",
"owner": "nix-community",
"repo": "disko",
"rev": "d64e5cdca35b5fad7c504f615357a7afe6d9c49e",
"rev": "7194cfe5b7a3660726b0fe7296070eaef601cae9",
"type": "github"
},
"original": {
@@ -318,11 +318,11 @@
]
},
"locked": {
"lastModified": 1765384171,
"narHash": "sha256-FuFtkJrW1Z7u+3lhzPRau69E0CNjADku1mLQQflUORo=",
"lastModified": 1765979862,
"narHash": "sha256-/r9/1KamvbHJx6I40H4HsSXnEcBAkj46ZwibhBx9kg0=",
"owner": "nix-community",
"repo": "home-manager",
"rev": "44777152652bc9eacf8876976fa72cc77ca8b9d8",
"rev": "d3135ab747fd9dac250ffb90b4a7e80634eacbe9",
"type": "github"
},
"original": {
@@ -486,11 +486,11 @@
]
},
"locked": {
"lastModified": 1765483419,
"narHash": "sha256-w6wznH1lBzlSH3+pWDkE+L6xA0F02drFAzu2E7PD/Jo=",
"lastModified": 1765841014,
"narHash": "sha256-55V0AJ36V5Egh4kMhWtDh117eE3GOjwq5LhwxDn9eHg=",
"owner": "nix-community",
"repo": "NixOS-WSL",
"rev": "0c040f28b44b18e0d4240e027096078e34dbb029",
"rev": "be4af8042e7a61fa12fda58fe9a3b3babdefe17b",
"type": "github"
},
"original": {
@@ -518,11 +518,11 @@
},
"nixpkgs-old-kernel": {
"locked": {
"lastModified": 1764939437,
"narHash": "sha256-4TLFHUwXraw9Df5mXC/vCrJgb50CRr3CzUzF0Mn3CII=",
"lastModified": 1765687488,
"narHash": "sha256-7YAJ6xgBAQ/Nr+7MI13Tui1ULflgAdKh63m1tfYV7+M=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "00d2457e2f608b4be6fe8b470b0a36816324b0ae",
"rev": "d02bcc33948ca19b0aaa0213fe987ceec1f4ebe1",
"type": "github"
},
"original": {
@@ -534,11 +534,11 @@
},
"nixpkgs_2": {
"locked": {
"lastModified": 1765311797,
"narHash": "sha256-mSD5Ob7a+T2RNjvPvOA1dkJHGVrNVl8ZOrAwBjKBDQo=",
"lastModified": 1765838191,
"narHash": "sha256-m5KWt1nOm76ILk/JSCxBM4MfK3rYY7Wq9/TZIIeGnT8=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "09eb77e94fa25202af8f3e81ddc7353d9970ac1b",
"rev": "c6f52ebd45e5925c188d1a20119978aa4ffd5ef6",
"type": "github"
},
"original": {

6
templates/default.nix
View File

@@ -20,7 +20,7 @@
user = {
path = ./user;
description = "External user home-manager configuration";
description = "External user configuration module";
welcomeText = ''
# User Configuration Template
@@ -29,10 +29,10 @@
## 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
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.
'';

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.nix # Optional: User options AND home-manager configuration
├── user.nix # Required: User options AND home-manager configuration
├── nixos.nix # Optional: System-level NixOS configuration
├── 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
### 1. Create Your User Configuration Repository
Copy the templates from this directory to your own Git repository:
- `home.nix` - Required for home-manager configuration
- `nixos.nix` - Optional for system-level configuration
- `user.nix` - Required: Contains both user account options and home-manager configuration
- `nixos.nix` - Optional: System-level NixOS configuration (e.g., system services, extra groups)
### 2. Reference It in users.nix
```nix
{
ugaif.users = {
myusername = {
# Option 1: Set user options in users.nix
# Option 1: Define inline (without external module)
inlineuser = {
description = "My Name";
extraGroups = [ "wheel" "networkmanager" ];
shell = pkgs.zsh;
# 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;
# };
hashedPassword = "$6$...";
};
# 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
### user.nix (Optional)
### user.nix (Required)
This file serves dual purpose:
1. Sets `ugaif.users.<username>` options (description, shell, extraGroups, etc.)
2. Provides home-manager configuration (programs.*, home.*, services.*)
This file serves a dual purpose and is imported in **two contexts**:
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:**
- 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.
- The same file is evaluated twice in different contexts
- User account options (`ugaif.users.<username>`) are read during NixOS evaluation
- Home-manager options are used when building the user's environment
- External module options override any defaults set in `users.nix`
- You can conditionally include packages/config based on system type using `osConfig`
**Receives:**
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
- `config` - Config (NixOS or home-manager depending on context)
- `lib` - Nixpkgs library
- `config` - Configuration (NixOS or home-manager depending on context)
- `lib` - Nixpkgs library functions
- `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
@@ -118,17 +115,20 @@ This file contains system-level NixOS configuration. Only needed for:
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
# User account options (imported as NixOS module)
# User account options
ugaif.users.myuser = {
description = "My Name";
shell = pkgs.zsh;
hashedPassword = "!";
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; [
vim
git
@@ -139,6 +139,7 @@ This file contains system-level NixOS configuration. Only needed for:
enable = true;
userName = "My Name";
userEmail = "me@example.com";
extraConfig.init.defaultBranch = "main";
};
}
```
@@ -147,24 +148,31 @@ This file contains system-level NixOS configuration. Only needed for:
```nix
{ inputs, ... }:
{ config, lib, pkgs, ... }:
{ config, lib, pkgs, osConfig ? null, ... }:
{
ugaif.users.myuser = {
description = "My Name";
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
home.file.".bashrc".source = ./dotfiles/bashrc;
home.file.".vimrc".source = ./dotfiles/vimrc;
home.file.".bashrc".source = ./config/bashrc;
home.file.".vimrc".source = ./config/vimrc;
programs.git = {
enable = true;
userName = "My Name";
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:
- 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)
- System zsh theme applied if `useZshTheme = 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

9
templates/user/nixos.nix
View File

@@ -4,16 +4,15 @@
# User NixOS System Configuration (Optional)
# ============================================================================
# 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:
# - System-level services that depend on the user (e.g., user systemd services)
# - Special system permissions or configurations
# - Installing system packages that require root
#
# Note: User options (description, shell, extraGroups, etc.) should be set
# in your external module's user.nix or in the main users.nix file, not in
# this nixos.nix.
# Note: User options (description, shell, extraGroups, etc.) AND home-manager
# configuration should be set in user.nix, not in this nixos.nix.
#
# This module receives the same `inputs` flake inputs as the main
# nixos-systems configuration.
@@ -47,5 +46,5 @@
# Example: Add user to additional groups
# 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, ... }:
# ============================================================================
# User Configuration (Optional)
# User Configuration
# ============================================================================
# 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 configures BOTH:
# 1. User account options (ugaif.users.<username>)
# 2. Home-manager configuration (home.*, programs.*, services.*)
#
# This file is optional - if not present, the system will use the defaults
# from the main users.nix file. Use this file to override or extend those
# default user and home-manager options for this user.
# The same file is imported in two contexts:
# - As a NixOS module to read ugaif.users.<username> options
# - As a home-manager module for user environment configuration
#
# This module receives the same `inputs` flake inputs as the main
# nixos-systems configuration (nixpkgs, home-manager, etc.).
@@ -25,45 +24,44 @@
{
# ========== 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";
shell = pkgs.zsh;
hashedPassword = "!"; # Locked password - use SSH keys only
extraGroups = [
"wheel" # Sudo access
"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
# editor = pkgs.helix;
# Optional: Disable system theme/nvim plugins
# useZshTheme = false;
# useNvimPlugins = false;
# Optional: Add system-level packages
# extraPackages = with pkgs; [ docker ];
useZshTheme = true; # Apply system Zsh theme
useNvimPlugins = true; # Apply system Neovim plugins
};
# 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 ==========
# 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
];
home.packages =
with pkgs;
[
htop
ripgrep
fd
bat
]
++ lib.optional (osConfig.ugaif.sw.type or null == "desktop") firefox;
# Conditionally add packages based on system type
# ========== Programs ==========
@@ -77,18 +75,28 @@
};
};
# Zsh configuration
programs.zsh = {
enable = true;
# System theme is applied automatically if useZshTheme = true
};
# ========== Shell Environment ==========
home.sessionVariables = {
# EDITOR is set automatically based on ugaif.users.*.editor
EDITOR = "nvim";
# Add your custom environment variables here
};
# ========== XDG Configuration ==========
xdg.enable = true;
# ========== Dotfiles ==========
# You can manage dotfiles with home.file
# home.file.".bashrc".source = ./dotfiles/bashrc;
# home.file.".vimrc".source = ./dotfiles/vimrc;
# home.file.".bashrc".source = ./config/bashrc;
# 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 = /path/to/local/config;
#
# External repositories can contain:
# - user.nix (optional): Sets ugaif.users.<name> options AND home-manager config
# External repositories should contain:
# - user.nix (required): Defines ugaif.users.<name> options AND home-manager config
# - 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 = {
root = {
isNormalUser = false;