docs: General documentation update
This commit is contained in:
Hunter Halloran
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user