docs: Copilot update all docs files

2026-01-05 10:05:41 -05:00
parent 0378268dcc
commit f07ccc071e
8 changed files with 2052 additions and 1136 deletions
--- a/docs/USER_CONFIGURATION.md
+++ b/docs/USER_CONFIGURATION.md
@@ -1,103 +1,585 @@
 # User Configuration Guide

-Complete guide to managing user accounts in nixos-systems.
+Comprehensive guide to managing user accounts in Athenix.

 ## Table of Contents

 - [Overview](#overview)
 - [Quick Start](#quick-start)
- [User Account Options](#user-account-options)
- [External User Configurations](#external-user-configurations)
+- [Defining Users](#defining-users)
 - [Enabling Users on Hosts](#enabling-users-on-hosts)
+- [External User Configurations](#external-user-configurations)
 - [Password Management](#password-management)
 - [SSH Keys](#ssh-keys)
+- [User Groups](#user-groups)
 - [Examples](#examples)

 ## Overview

-Users are defined in `users.nix` but are **not enabled by default** on all systems. Each system must explicitly enable users in `inventory.nix`.
+User accounts are defined in `users.nix` but are **not enabled by default**. Each host must explicitly enable users in `inventory.nix`.

-**Default enabled users:**
- `root` - System administrator
- `engr-ugaif` - Innovation Factory default account
+**Always-enabled users:**
+- `root` - System administrator (enable: true)
+- `engr-ugaif` - Innovation Factory default account (enable: true)
+
+All other users are disabled by default and must be explicitly enabled per-host.

 ## Quick Start

 ### 1. Define User in users.nix

 ```nix
-athenix.users = {
-  # Option 1: Inline definition
-  myuser = {
-    description = "My Full Name";
-    extraGroups = [ "wheel" "networkmanager" ];
-    shell = pkgs.zsh;
-    hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
-    opensshKeys = [
-      "ssh-ed25519 AAAA... user@machine"
-    ];
-  };
-  
-  # Option 2: External configuration (recommended for personalization)
-  myuser.external = builtins.fetchGit {
-    url = "https://git.factory.uga.edu/username/dotfiles";
-    rev = "abc123...";  # Pin to specific commit
-  };
+athenix.users.myuser = {
+  description = "John Doe";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";  # Generate with: mkpasswd -m sha-512
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
 };
 ```

-### 2. Enable User on Hosts
-
-In `inventory.nix`:
+### 2. Enable on Hosts in inventory.nix

 ```nix
 nix-laptop = {
-  devices = 2;
-  overrides.athenix.users.myuser.enable = true;  # Enables on all nix-laptop hosts
-};
-
-# Or for specific devices
-nix-desktop = {
-  devices = {
-    "1".athenix.users.myuser.enable = true;
-    "2".athenix.users.otheruser.enable = true;
-  };
-};
-
-# Or use convenience option
-nix-wsl = {
-  devices."alice".athenix.forUser = "alice-user";  # Automatically enables user
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
 };
 ```

-## User Account Options
+### 3. Users can now log in

-Each user in `users.nix` can have the following options:
+Users defined and enabled this way are automatically created on the system.
+
+## Defining Users
+
+Define users in `users.nix` under `athenix.users`:
+
+### Inline User Definition

 ```nix
-username = {
-  # === Identity ===
-  description = "Full Name";              # User's full name
+athenix.users.myuser = {
+  description = "My Full Name";
+  extraGroups = [ "wheel" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "$6$...";
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+  useZshTheme = true;
+  useNvimPlugins = true;
+};
+```
+
+### External User Configuration
+
+Reference an external Git repository (recommended for personal dotfiles):
+
+```nix
+athenix.users.myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
+  rev = "abc123...";  # Pin to specific commit
+};
+```
+
+The external repository should contain:
+- `user.nix` (required) - User account options AND home-manager configuration
+- `nixos.nix` (optional) - System-level configuration
+
+See [External User Configurations](#external-user-configurations) section below.
+
+## User Account Options
+
+### `description`
+
+Full name or description of the user.
+
+**Type:** String
+
+```nix
+athenix.users.myuser.description = "John Doe";
+```
+
+### `extraGroups`
+
+Additional Unix groups for the user. Default is empty.
+
+**Type:** List of strings
+
+**Common groups:**
+- `"wheel"` - Sudo access
+- `"networkmanager"` - Network configuration
+- `"docker"` - Docker and Podman access
+- `"video"` - Video device access (GPU, displays)
+- `"audio"` - Audio device access
+- `"input"` - Input devices (keyboards, mice)
+- `"kvm"` - KVM virtual machine access
+- `"libvirtd"` - Libvirt daemon access
+
+```nix
+athenix.users.myuser.extraGroups = [
+  "wheel"
+  "networkmanager"
+  "docker"
+  "video"
+];
+```
+
+### `shell`
+
+Login shell for the user.
+
+**Type:** Package
+
+**Default:** `pkgs.bash`
+
+```nix
+athenix.users.myuser.shell = pkgs.zsh;
+# or
+athenix.users.myuser.shell = pkgs.fish;
+```
+
+### `hashedPassword`
+
+Password hash for the user. Use `!` to disable password login (SSH keys only).
+
+**Type:** String (SHA-512 hash)
+
+**Generation:**
+```bash
+# Generate a hashed password
+mkpasswd -m sha-512
+
+# Or interactively
+mkpasswd -m sha-512 -c
+```
+
+```nix
+athenix.users.myuser.hashedPassword = "$6$...";
+
+# Disable password login (require SSH keys)
+athenix.users.myuser.hashedPassword = "!";
+```
+
+### `opensshKeys`
+
+SSH public keys for remote access. Users without SSH keys require password login.
+
+**Type:** List of strings
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@laptop"
+  "ssh-rsa AAAA... user@desktop"
+];
+```
+
+**Getting your SSH public key:**
+```bash
+# Print your public key
+cat ~/.ssh/id_ed25519.pub
+
+# Generate a new key if needed
+ssh-keygen -t ed25519 -C "user@host"
+```
+
+### `useZshTheme`
+
+Apply system Zsh theme configuration to this user (if using Zsh as shell).
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useZshTheme = true;
+```
+
+### `useNvimPlugins`
+
+Apply system Neovim configuration and plugins to this user.
+
+**Type:** Boolean
+
+**Default:** `true`
+
+```nix
+athenix.users.myuser.useNvimPlugins = true;
+```
+
+## Enabling Users on Hosts
+
+Users are **not enabled by default**. Enable them in `inventory.nix`:
+
+### Enable on All Devices in a Group
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### Enable on Specific Devices
+
+```nix
+nix-desktop = {
+  devices = {
+    "1".athenix.users.admin.enable = true;
+    "2".athenix.users.staff.enable = true;
+    "3".athenix.users.staff.enable = true;
+  };
+};
+```
+
+### Enable Multiple Users
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides = {
+    athenix.users.student.enable = true;
+    athenix.users.teacher.enable = true;
+  };
+};
+```
+
+### Using `athenix.forUser` Convenience
+
+Quick setup for single-user systems (especially WSL):
+
+```nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+    "bob".athenix.forUser = "bob-uga";
+  };
+};
+```
+
+This automatically enables the user and sets it as the default WSL user.
+
+## External User Configurations
+
+External user configurations (dotfiles) allow users to maintain their own home-manager setup in separate repositories.
+
+### Repository Structure
+
+```
+my-dotfiles/
+├── user.nix      # Required: User options + home-manager config
+├── nixos.nix     # Optional: System-level configuration
+└── config/       # Optional: Your actual dotfiles
+    ├── bashrc
+    ├── zshrc
+    ├── vimrc
+    └── ...
+```
+
+### user.nix (Required)
+
+This file must provide BOTH user account options AND home-manager configuration:
+
+```nix
+{ inputs, ... }:
+{ config, lib, pkgs, osConfig ? null, ... }:
+{
+  # ========== User Account Configuration ==========
+  # These options define the user account itself
+  athenix.users.myusername = {
+    description = "My Full Name";
+    extraGroups = [ "wheel" "docker" "networkmanager" ];
+    shell = pkgs.zsh;
+    hashedPassword = "!";  # SSH keys only
+    opensshKeys = [
+      "ssh-ed25519 AAAA... user@host"
+    ];
+    useZshTheme = true;
+    useNvimPlugins = true;
+  };
+
+  # ========== Home Manager Configuration ==========
+  # User environment, packages, and dotfiles
  
-  # === System Access ===
-  isNormalUser = true;                    # Default: true (false for root)
-  extraGroups = [                         # Additional Unix groups
-    "wheel"                               # Sudo access
-    "networkmanager"                      # Network configuration
-    "docker"                              # Docker access
-    "video"                               # Video device access
-    "audio"                               # Audio device access
+  home.packages = with pkgs; [
+    vim
+    ripgrep
+    fzf
+  ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox;
+
+  programs.git = {
+    enable = true;
+    userName = "My Name";
+    userEmail = "me@example.com";
+    extraConfig = {
+      init.defaultBranch = "main";
+      core.editor = "vim";
+    };
+  };
+
+  programs.zsh = {
+    enable = true;
+    initExtra = ''
+      # Your Zsh configuration
+    '';
+  };
+
+  # Manage dotfiles
+  home.file.".config/zshrc".source = ./config/zshrc;
+  home.file.".config/bashrc".source = ./config/bashrc;
+  home.file.".vimrc".source = ./config/vimrc;
+}
+```
+
+### nixos.nix (Optional)
+
+System-level configuration for this user (rarely needed):
+
+```nix
+{ inputs, ... }:
+{ config, lib, pkgs, ... }:
+{
+  # System-level configuration for this user
+  users.users.myusername.extraGroups = [ "docker" ];
+  environment.systemPackages = [ pkgs.docker ];
+}
+```
+
+### Using External User Configuration
+
+In `users.nix`:
+
+```nix
+athenix.users.myuser.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/username/dotfiles";
+  rev = "abc123...";  # Pin to specific commit
+};
+```
+
+Then enable on hosts in `inventory.nix`:
+
+```nix
+nix-laptop = {
+  devices = 5;
+  overrides.athenix.users.myuser.enable = true;
+};
+```
+
+### External Module Parameters
+
+The `user.nix` module receives:
+
+- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
+- **`config`** - Home-manager configuration
+- **`lib`** - Nixpkgs library functions
+- **`pkgs`** - Package set
+- **`osConfig`** - OS-level configuration (read-only, can be used for conditional setup)
+
+### Creating External User Configuration
+
+Use the template:
+
+```bash
+nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
+```
+
+## Password Management
+
+### Generate Password Hash
+
+```bash
+# Interactive (won't echo)
+mkpasswd -m sha-512 -c
+
+# From string
+echo "mypassword" | mkpasswd -m sha-512 -s
+```
+
+### Disable Password Login
+
+Set `hashedPassword = "!"` and provide SSH keys:
+
+```nix
+athenix.users.myuser = {
+  description = "SSH-only user";
+  hashedPassword = "!";
+  opensshKeys = [ "ssh-ed25519 AAAA..." ];
+};
+```
+
+### Update User Password on Running System
+
+```bash
+# As the user
+passwd
+
+# As root (to change another user's password)
+sudo passwd username
+```
+
+## SSH Keys
+
+### Add SSH Keys to a User
+
+```nix
+athenix.users.myuser.opensshKeys = [
+  "ssh-ed25519 AAAA... user@laptop"
+  "ssh-ed25519 BBBB... user@desktop"
+];
+```
+
+### Get Your SSH Public Key
+
+```bash
+# Display your public key
+cat ~/.ssh/id_ed25519.pub
+
+# Or for RSA
+cat ~/.ssh/id_rsa.pub
+```
+
+### Generate New SSH Key
+
+```bash
+# Ed25519 (recommended)
+ssh-keygen -t ed25519 -C "user@host"
+
+# RSA (older systems)
+ssh-keygen -t rsa -b 4096 -C "user@host"
+```
+
+## User Groups
+
+### wheel
+
+Allows passwordless sudo access.
+
+```nix
+athenix.users.myuser.extraGroups = [ "wheel" ];
+```
+
+### networkmanager
+
+Configure network connections (requires `networkmanager` to be enabled):
+
+```nix
+athenix.users.myuser.extraGroups = [ "networkmanager" ];
+```
+
+### docker
+
+Access Docker daemon (must have Docker enabled on system):
+
+```nix
+athenix.users.myuser.extraGroups = [ "docker" ];
+```
+
+### video and audio
+
+Access GPU and audio devices:
+
+```nix
+athenix.users.myuser.extraGroups = [ "video" "audio" ];
+```
+
+## Examples
+
+### Example 1: Basic Lab User
+
+```nix
+# users.nix
+athenix.users.student = {
+  description = "Student Account";
+  extraGroups = [ "networkmanager" ];
+  shell = pkgs.bash;
+  hashedPassword = "$6$...";
+  opensshKeys = [];  # Password login only
+};
+
+# inventory.nix
+nix-laptop = {
+  devices = 20;
+  overrides.athenix.users.student.enable = true;
+};
+```
+
+### Example 2: Developer with SSH Keys
+
+```nix
+# users.nix
+athenix.users.developer = {
+  description = "Developer";
+  extraGroups = [ "wheel" "docker" "networkmanager" ];
+  shell = pkgs.zsh;
+  hashedPassword = "!";
+  opensshKeys = [
+    "ssh-ed25519 AAAA... dev@laptop"
  ];
-  shell = pkgs.zsh;                       # Login shell (default: pkgs.bash)
-  hashedPassword = "$6$...";              # Hashed password (see below)
-  
-  # === SSH Access ===
-  opensshKeys = [                         # SSH public keys
-    "ssh-ed25519 AAAA... user@host"
-    "ssh-rsa AAAA... user@otherhost"
-  ];
-  
-  # === External Configuration ===
+  useZshTheme = true;
+  useNvimPlugins = true;
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = 3;
+  overrides.athenix.users.developer.enable = true;
+};
+```
+
+### Example 3: WSL User with Dotfiles
+
+```nix
+# users.nix
+athenix.users.alice.external = builtins.fetchGit {
+  url = "https://git.factory.uga.edu/alice/dotfiles";
+  rev = "abc123...";
+};
+
+# inventory.nix
+nix-wsl = {
+  devices = {
+    "alice".athenix.forUser = "alice-uga";
+  };
+};
+```
+
+### Example 4: Multiple Users on Single System
+
+```nix
+# users.nix
+athenix.users = {
+  admin = {
+    description = "System Administrator";
+    extraGroups = [ "wheel" ];
+    shell = pkgs.bash;
+    hashedPassword = "!";
+    opensshKeys = [ "ssh-ed25519 AAAA..." ];
+  };
+  guest = {
+    description = "Guest User";
+    extraGroups = [];
+    shell = pkgs.bash;
+    hashedPassword = "$6$...";
+  };
+};
+
+# inventory.nix
+nix-desktop = {
+  devices = {
+    "admin-station" = {
+      athenix.users.admin.enable = true;
+    };
+    "guest-station" = {
+      athenix.users.guest.enable = true;
+    };
+  };
+};
+```
+
+## See Also
+
+- [INVENTORY.md](INVENTORY.md) - Host configuration
+- [NAMESPACE.md](NAMESPACE.md) - All configuration options
+- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules in detail
+- [README.md](../README.md) - Main documentation
  external = builtins.fetchGit { ... };   # External user module (see below)
  
  # === Theme Integration ===