docs: General documentation update

2025-12-17 19:39:02 -05:00
parent 9be51b2589
commit d97ece898c
12 changed files with 287 additions and 223 deletions
--- a/templates/default.nix
+++ b/templates/default.nix
@@ -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.
    '';
--- a/templates/user/README.md
+++ b/templates/user/README.md
@@ -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

--- a/templates/user/nixos.nix
+++ b/templates/user/nixos.nix
@@ -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
 }
--- a/templates/user/user.nix
+++ b/templates/user/user.nix
@@ -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)
 }