diff --git a/README.md b/README.md index b02bcbc..0d1dc3b 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,156 @@ -# UGA Innovation Factory - Athenix +# Athenix - UGA Innovation Factory NixOS Configuration [![CI](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions/workflows/ci.yml/badge.svg)](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions) -This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, Surface tablets, and containers. It provides a declarative, reproducible system configuration using Nix flakes. +Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes. -## Documentation +## Quick Navigation -- **[Quick Start](#quick-start)** - Get started in 5 minutes -- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Configure hosts and fleet inventory -- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - Configuration options reference (`athenix.*`) -- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User account management -- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External configuration modules -- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs and container images -- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development and testing workflow +- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Define and configure hosts +- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - All `athenix.*` options reference +- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User accounts and dotfiles +- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External system and user configurations +- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs, containers, and artifacts +- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflow and testing -## Quick Start +## Getting Started ### For End Users -Update your system to the latest configuration: +Update your system: ```bash update-system ``` -This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds. - -**Note:** If you use external user configurations (personal dotfiles), run: -```bash -sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure -``` +This automatically rebuilds your system with the latest configuration from the repository. ### For Administrators +Make configuration changes: + ```bash -# 1. Make changes to configuration files +# Edit inventory vim inventory.nix -# 2. Test configuration +# Validate changes nix flake check -# 3. Format code +# Format code nix fmt -# 4. Commit and push -git add . -git commit -m "Description of changes" -git push +# Commit and push +git add . && git commit -m "Your message" && git push ``` -Users can now run `update-system` to get the changes. - -**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.** +Users automatically get changes when they run `update-system`. ## Repository Structure ``` -nixos-systems/ -├── flake.nix # Flake entry point -├── inventory.nix # Fleet inventory - Define hosts here -├── users.nix # User accounts - Define users here -├── hosts/ # Host generation logic -│ ├── types/ # Hardware types (desktop, laptop, surface, lxc, wsl, ephemeral) -│ └── ... -├── sw/ # Software configurations by system type -│ ├── desktop/ # Full desktop environment -│ ├── tablet-kiosk/ # Surface kiosk mode -│ ├── stateless-kiosk/# Diskless PXE kiosks -│ ├── headless/ # Servers and containers -│ └── ... -├── installer/ # ISO and container builds -├── templates/ # Templates for external configs -│ ├── system/ # System configuration template -│ └── user/ # User configuration template -├── docs/ # Documentation -│ ├── INVENTORY.md # Host configuration guide -│ ├── NAMESPACE.md # Option reference -│ ├── BUILDING.md # Building artifacts -│ └── DEVELOPMENT.md # Development guide -└── assets/ # Assets (Plymouth theme, etc.) +flake.nix # Flake entry point (inputs + outputs) +inventory.nix # Fleet inventory and host definitions +users.nix # User account definitions + +flake.lock # Locked dependency versions + +hosts/ # Host generation logic +├── default.nix # Main host generator +├── boot.nix # Boot and filesystem configuration +├── common.nix # Common system configuration +├── user-config.nix # User configuration integration +└── types/ # Hardware type modules + ├── nix-desktop.nix + ├── nix-laptop.nix + ├── nix-surface.nix + ├── nix-lxc.nix + ├── nix-wsl.nix + └── nix-ephemeral.nix + +sw/ # Software configurations by system type +├── default.nix # Software module entry point +├── python.nix # Python tools (pixi, uv) +├── nvim.nix # Neovim configuration +├── ghostty.nix # Ghostty terminal +├── theme.nix # System theme configuration +├── updater.nix # System update scripts +├── update-ref.nix # Update reference tracking +├── builders/ # Build server configuration +├── desktop/ # Desktop environment +├── headless/ # Server/container without GUI +├── tablet-kiosk/ # Surface tablet kiosk mode +└── stateless-kiosk/ # Diskless PXE netboot systems + +installer/ # Build artifacts +├── default.nix # Build configuration +├── artifacts.nix # ISO/LXC/Proxmox definitions +├── auto-install.nix # Installer scripts +├── modules.nix # Installer-specific modules +├── deploy-proxmox-lxc.sh # Proxmox deployment script +└── PROXMOX_LXC.md # Proxmox guide + +templates/ # Templates for external modules +├── user/ # User configuration template +│ ├── user.nix # User options + home-manager config +│ └── README.md +└── system/ # System configuration template + ├── default.nix # NixOS module + └── README.md + +docs/ # Documentation +├── README.md # This file +├── INVENTORY.md # Host configuration guide +├── NAMESPACE.md # Option reference +├── USER_CONFIGURATION.md # User management +├── EXTERNAL_MODULES.md # External module integration +├── BUILDING.md # Build and deployment +└── DEVELOPMENT.md # Development workflow + +assets/ # Assets +└── plymouth-theme/ # Boot splash theme ``` ## Configuration Overview -All Innovation Factory options use the `athenix.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference. +All Innovation Factory-specific options use the `athenix` namespace to avoid conflicts with NixOS options. -**Quick examples:** +### Common Options ```nix -# Host configuration -athenix.host.filesystem.device = "/dev/nvme0n1"; -athenix.host.filesystem.swapSize = "64G"; +# Host filesystem and hardware +athenix.host = { + filesystem.device = "/dev/sda"; + filesystem.swapSize = "32G"; + buildMethods = [ "installer-iso" ]; + useHostPrefix = true; +}; -# Software configuration -athenix.sw.type = "desktop"; # or "headless", "tablet-kiosk" -athenix.sw.extraPackages = with pkgs; [ vim docker ]; +# System type and packages +athenix.sw = { + type = "desktop"; # desktop, tablet-kiosk, stateless-kiosk, headless, builders + extraPackages = with pkgs; [ vim docker ]; +}; # User management athenix.users.myuser.enable = true; athenix.forUser = "myuser"; # Convenience shortcut ``` -## Prerequisites - -To work with this repository, install Nix with flakes support: - -```bash -# Recommended: Determinate Systems installer (includes flakes) -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install - -# Alternative: Official installer (requires enabling flakes manually) -sh <(curl -L https://nixos.org/nix/install) --daemon -``` +See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference. ## Common Tasks -### Adding a New User - -1. Edit `users.nix`: - -```nix -myuser = { - description = "My Full Name"; - extraGroups = [ "wheel" "networkmanager" ]; - shell = pkgs.zsh; - hashedPassword = "$6$..."; # Generate with: mkpasswd -m sha-512 - opensshKeys = [ "ssh-ed25519 AAAA... user@host" ]; -}; -``` - -2. Enable on hosts in `inventory.nix`: - -```nix -nix-laptop = { - devices = 2; - overrides.athenix.users.myuser.enable = true; -}; -``` - -**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete user management guide.** - ### Adding Hosts Edit `inventory.nix`: ```nix -# Simple: Create 5 laptops +# Simple: Create 5 identical laptops nix-laptop = { - devices = 5; # Creates nix-laptop1 through nix-laptop5 + devices = 5; }; -# With configuration +# With custom configuration per device nix-surface = { devices = { "1".athenix.sw.kioskUrl = "https://dashboard1.example.com"; @@ -158,107 +158,134 @@ nix-surface = { }; }; -# With overrides for all devices +# With common overrides nix-desktop = { devices = 3; overrides = { athenix.users.student.enable = true; - athenix.sw.extraPackages = with pkgs; [ vim ]; }; }; ``` -**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.** +**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete guide.** + +### Managing Users + +Edit `users.nix`: + +```nix +athenix.users.myuser = { + description = "My Name"; + extraGroups = [ "wheel" "networkmanager" ]; + shell = pkgs.zsh; + hashedPassword = "$6$..."; # mkpasswd -m sha-512 + opensshKeys = [ "ssh-ed25519 AAAA..." ]; +}; +``` + +Enable in `inventory.nix`: + +```nix +nix-laptop = { + overrides.athenix.users.myuser.enable = true; +}; +``` + +**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete guide.** ### Using External Configurations -Users and systems can reference external Git repositories for configuration: +Reference external repositories for user dotfiles or system configurations: ```nix -# In users.nix - External dotfiles with user configuration -myuser.external = builtins.fetchGit { - url = "https://git.factory.uga.edu/username/dotfiles"; +# User dotfiles (in users.nix) +hdh20267.external = builtins.fetchGit { + url = "https://git.factory.uga.edu/hdh20267/dotfiles"; rev = "abc123..."; }; -# The external user.nix file contains both athenix.users.myuser options -# AND home-manager configuration -# In inventory.nix - External system config +# System configuration (in inventory.nix) nix-lxc = { - devices."server" = builtins.fetchGit { + devices."special" = builtins.fetchGit { url = "https://git.factory.uga.edu/org/server-config"; rev = "abc123..."; }; }; ``` -**Create templates:** -```bash -# User configuration (dotfiles) -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user - -# System configuration -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system -``` - **See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.** ### Building Installation Media ```bash -# Build installer ISO -nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1 +# Build installer ISO for a specific host +nix build .#installer-iso-nix-laptop1 # Build LXC container nix build .#lxc-nix-builder # List all available artifacts -nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git +nix flake show ``` -**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.** +**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.** ## System Types +Set via `athenix.sw.type`: + - **`desktop`** - Full GNOME desktop environment -- **`tablet-kiosk`** - Surface tablets in kiosk mode -- **`stateless-kiosk`** - Diskless PXE boot kiosks -- **`headless`** - Servers and containers (no GUI) +- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser +- **`stateless-kiosk`** - Diskless PXE-booted systems +- **`headless`** - Servers and containers without GUI +- **`builders`** - Build servers -Set via `athenix.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options. +## Development Workflow -## Development - -**Quick commands:** ```bash -nix flake check # Validate all configurations -nix fmt # Format code -nix flake update # Update dependencies -nix build .#installer-iso-nix-laptop1 # Build specific artifact +# Check all configurations +nix flake check + +# Format code +nix fmt **/*.nix + +# Build specific artifact +nix build .#installer-iso-nix-laptop1 + +# Update flake inputs +nix flake update ``` -**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.** +**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed workflow.** ## Troubleshooting -**Common issues:** +| Issue | Solution | +|-------|----------| +| Build errors | Run `nix flake check --show-trace` for details | +| Configuration validation | `nix flake check` checks all 50+ hosts | +| External modules fail | Verify Git URL accessibility and module structure | +| Remote build issues | Test SSH: `ssh engr-ugaif@nix-builder` | +| List all hosts | `nix eval .#nixosConfigurations --apply builtins.attrNames` | +| Disk space | `nix-collect-garbage -d && nix store optimise` | -- **Build errors:** Run `nix flake check --show-trace` for details -- **External modules not loading:** Check repository access and module structure (see templates) -- **Remote build failures:** Test SSH access: `ssh engr-ugaif@nix-builder` -- **Out of disk space:** Run `nix-collect-garbage -d && nix store optimise` +## Prerequisites + +Nix with flakes support: -**Useful commands:** ```bash -nix flake show # List all available outputs -nix flake metadata # Show flake info -nix eval .#nixosConfigurations --apply builtins.attrNames # List all hosts +# Recommended: Determinate Systems installer +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install + +# Or enable flakes in existing Nix installation +echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf ``` -**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.** +## More Information -## Getting Help - -- Review documentation in `docs/` directory -- Check templates: `templates/user/` and `templates/system/` -- Contact Innovation Factory IT team +- [docs/INVENTORY.md](docs/INVENTORY.md) - Host configuration +- [docs/NAMESPACE.md](docs/NAMESPACE.md) - All option references +- [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) - User management +- [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) - External modules +- [docs/BUILDING.md](docs/BUILDING.md) - Building and deployment +- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development guide diff --git a/docs/BUILDING.md b/docs/BUILDING.md index aa279e7..46d09ff 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -1,11 +1,13 @@ -# Building Installation Media +# Building Installation Media and Artifacts -This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake. +Guide to building installer ISOs, live images, and container artifacts. ## Table of Contents - [Quick Start](#quick-start) - [Available Artifacts](#available-artifacts) +- [Building Locally](#building-locally) +- [Building from Remote](#building-from-remote) - [Installer ISOs](#installer-isos) - [Live ISOs](#live-isos) - [Container Images](#container-images) @@ -15,116 +17,194 @@ This guide covers building installer ISOs, live images, and container artifacts ## Quick Start ```bash -# Build an installer ISO for a specific host -nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1 +# List all available artifacts +nix flake show -# Result will be in result/iso/ +# Build installer ISO for a specific host +nix build .#installer-iso-nix-laptop1 + +# Result is in result/iso/ ls -lh result/iso/ ``` ## Available Artifacts -List all available build outputs: +Athenix can build multiple artifact types for deployment: -```bash -nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git +| Type | Description | Location | Use Case | +|------|-------------|----------|----------| +| `installer-iso-*` | Auto-install ISO | `result/iso/` | Install NixOS to disk | +| `iso-*` | Live ISO | `result/iso/` | Boot without installing | +| `ipxe-*` | PXE netboot | `result/` | Diskless netboot systems | +| `lxc-*` | LXC container | `result/tarball/` | LXC/Proxmox containers | +| `proxmox-*` | Proxmox VMA | `result/` | Proxmox VM templates | + +Set artifact types per-host via `athenix.host.buildMethods` in `inventory.nix`: + +```nix +nix-laptop = { + devices = 5; + overrides.athenix.host.buildMethods = [ "installer-iso" ]; +}; + +nix-lxc = { + devices.builder = { + athenix.host.buildMethods = [ "lxc" "proxmox" ]; + }; +}; ``` -Common artifact types: +## Building Locally -| Artifact Type | Description | Example | -|--------------|-------------|---------| -| `installer-iso-*` | Auto-install ISO that installs configuration to disk | `installer-iso-nix-laptop1` | -| `iso-*` | Live ISO (bootable without installation) | `iso-nix-ephemeral1` | -| `ipxe-*` | iPXE netboot artifacts (kernel, initrd, script) | `ipxe-nix-ephemeral1` | -| `lxc-*` | LXC container tarball | `lxc-nix-builder` | -| `proxmox-*` | Proxmox VMA archive | `proxmox-nix-builder` | - -## Installer ISOs - -Installer ISOs automatically install the NixOS configuration to disk on first boot. - -### Building Locally +Build artifacts on your local machine: ```bash -# Build installer for a specific host +# Build installer ISO nix build .#installer-iso-nix-laptop1 -# Result location -ls -lh result/iso/nixos-*.iso - -# Copy to USB drive (replace /dev/sdX with your USB device) -sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress -``` - -### Building from Gitea - -```bash -nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1 -``` - -### Using the Installer - -1. Boot from the ISO -2. The system will automatically partition the disk and install NixOS -3. After installation completes, remove the USB drive and reboot -4. Log in with the configured user credentials - -**Note:** The installer will **erase all data** on the target disk specified in `athenix.host.filesystem.device`. - -## Live ISOs - -Live ISOs boot into a temporary system without installing to disk. Useful for: -- Testing configurations -- Recovery operations -- Ephemeral/stateless systems - -### Building Live ISOs - -```bash # Build live ISO nix build .#iso-nix-ephemeral1 -# Result location -ls -lh result/iso/nixos-*.iso +# Build LXC container +nix build .#lxc-nix-builder + +# Build all available outputs +nix build .# ``` -### Stateless Kiosk Systems +**Result locations:** +- ISOs: `result/iso/nixos-*.iso` +- LXC: `result/tarball/nixos-*.tar.xz` +- Proxmox: `result/` +- iPXE: `result/` (kernel, initrd, script) -For PXE netboot kiosks, use the `ipxe-*` artifacts: +### Build Specific Host ```bash -# Build iPXE artifacts -nix build .#ipxe-nix-ephemeral1 +# Get list of all hosts +nix eval .#nixosConfigurations --apply builtins.attrNames -# Result contains: -# - bzImage (kernel) -# - initrd (initial ramdisk) -# - netboot.ipxe (iPXE script) -ls -lh result/ +# Build specific host +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel +``` + +## Building from Remote + +Build from the Gitea repository without cloning: + +```bash +# Build installer ISO +nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1 + +# Build LXC container +nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#lxc-nix-builder + +# Use specific branch or revision +nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git?ref=develop#installer-iso-nix-laptop1 +``` + +## Installer ISOs + +Installer ISOs automatically partition and install NixOS on first boot. + +### Building + +```bash +nix build .#installer-iso-nix-laptop1 +ls -lh result/iso/ +``` + +### Burning to USB + +```bash +# Find USB device (be careful!) +lsblk + +# Burn ISO to USB (replace sdX with your device) +sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress + +# Sync and eject +sudo sync && sudo eject /dev/sdX +``` + +### Installation Process + +1. Boot from the USB drive +2. System automatically boots into installer +3. Installer partitions disk according to `athenix.host.filesystem` +4. NixOS is installed and configured +5. System reboots automatically +6. Log in with configured user + +**Note:** Installer will erase all data on the target disk specified in `athenix.host.filesystem.device`. + +### Installer Configuration + +Customize installer via host configuration: + +```nix +nix-laptop = { + devices = 5; + overrides = { + athenix.host.filesystem.device = "/dev/nvme0n1"; + athenix.host.filesystem.swapSize = "32G"; + athenix.host.buildMethods = [ "installer-iso" ]; + }; +}; +``` + +## Live ISOs + +Live ISOs boot into a temporary system without installing to disk. + +### Building + +```bash +nix build .#iso-nix-ephemeral1 +``` + +### Usage + +Live ISOs are useful for: +- Testing configurations before installation +- Recovery operations +- Ephemeral/stateless systems +- Booting in kiosk mode + +### Customizing Live ISO + +```nix +nix-ephemeral = { + devices.live = { + athenix.sw.type = "stateless-kiosk"; + athenix.sw.kioskUrl = "https://dashboard.example.com"; + athenix.host.buildMethods = [ "iso" ]; + }; +}; ``` ## Container Images ### LXC Containers -Build LXC container tarballs for Proxmox or other LXC hosts: +Build LXC container tarballs for Proxmox or standalone LXC: ```bash -# Build LXC tarball nix build .#lxc-nix-builder - -# Result location -ls -lh result/tarball/nixos-*.tar.xz +ls -lh result/tarball/ ``` -**Importing to Proxmox:** +#### Importing to Proxmox + +1. Copy tarball to Proxmox host: ```bash -# Copy tarball to Proxmox host scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/ +``` -# Create container from Proxmox CLI +2. Create container: + +```bash pct create 100 local:vztmpl/nixos-*.tar.xz \ --hostname nix-builder \ --memory 4096 \ @@ -132,25 +212,59 @@ pct create 100 local:vztmpl/nixos-*.tar.xz \ --net0 name=eth0,bridge=vmbr0,ip=dhcp ``` -See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions. +3. Start and log in: + +```bash +pct start 100 +pct shell 100 +``` + +#### Proxmox Integration + +For detailed Proxmox deployment instructions, see [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md). ### Proxmox VMA Build Proxmox-specific VMA archives: ```bash -# Build Proxmox VMA nix build .#proxmox-nix-builder - -# Result location ls -lh result/ ``` +VMA files can be imported directly into Proxmox for rapid VM creation. + +## iPXE / Network Boot + +Build iPXE artifacts for diskless PXE boot systems: + +```bash +nix build .#ipxe-nix-ephemeral1 +ls -lh result/ +``` + +Artifacts include: +- `bzImage` - Linux kernel +- `initrd` - Initial ramdisk +- `netboot.ipxe` - iPXE boot script + +### iPXE Setup + +Configure your PXE server to boot from these artifacts: + +```ipxe +kernel tftp://server/bzImage +initrd tftp://server/initrd +boot +``` + +See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed network boot setup. + ## Remote Builders Speed up builds by offloading to build servers. -### One-Time Remote Build +### One-Time Build ```bash nix build .#installer-iso-nix-laptop1 \ @@ -159,7 +273,7 @@ nix build .#installer-iso-nix-laptop1 \ ### Persistent Configuration -Add to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`: +Add to `~/.config/nix/nix.conf`: ```conf builders = ssh://engr-ugaif@nix-builder x86_64-linux @@ -171,12 +285,12 @@ Then build normally: nix build .#installer-iso-nix-laptop1 ``` -### SSH Key Setup +### SSH Setup -For remote builders, ensure SSH keys are configured: +Ensure SSH is configured for the builder: ```bash -# Generate SSH key if needed +# Generate key if needed ssh-keygen -t ed25519 # Copy to builder @@ -188,77 +302,86 @@ ssh engr-ugaif@nix-builder ### Multiple Builders -Configure multiple build servers: - ```conf -builders = ssh://engr-ugaif@nix-builder x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux +builders = ssh://engr-ugaif@nix-builder1 x86_64-linux ; ssh://engr-ugaif@nix-builder2 x86_64-linux ``` +### Automatic Remote Build (Tablets) + +Surface tablets are configured to automatically use remote builders: + +```nix +athenix.sw.remoteBuild = { + enable = true; + hosts = [ "nix-builder" ]; +}; +``` + +This speeds up builds on resource-constrained devices. + ## Troubleshooting ### Build Errors -**Check configuration validity:** +Get detailed error information: + ```bash +# Verbose error traces +nix build .#installer-iso-nix-laptop1 --show-trace + +# Check all configurations first nix flake check --show-trace ``` -**Test specific host build:** -```bash -nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -``` - -### Remote Builder Issues - -**Test SSH access:** -```bash -ssh engr-ugaif@nix-builder -``` - -**Check builder disk space:** -```bash -ssh engr-ugaif@nix-builder df -h -``` - -**Temporarily disable remote builds:** - -In `inventory.nix`: -```nix -athenix.sw.remoteBuild.enable = false; -``` - ### Out of Disk Space -**Clean up Nix store:** ```bash +# Clean up Nix store nix-collect-garbage -d + +# Optimize store nix store optimise ``` -**Check space:** +### Build Hangs + ```bash -df -h /nix +# List processes +ps aux | grep nix + +# Cancel build +Ctrl+C ``` -### ISO Won't Boot +### Finding Artifact Outputs -**Verify ISO integrity:** ```bash -sha256sum result/iso/nixos-*.iso +# List all buildable outputs +nix flake show + +# Check specific output exists +nix flake show | grep installer-iso-nix-laptop1 + +# Get path to output +nix build .#installer-iso-nix-laptop1 --no-link ``` -**Check USB write:** -```bash -# Use correct block size and sync -sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress && sync -``` +### Build Not Creating Expected File -**Try alternative boot mode:** -- UEFI systems: Try legacy BIOS mode -- Legacy BIOS: Try UEFI mode +```bash +# Check build log +nix build .#installer-iso-nix-laptop1 -L + +# Check what's in result +ls -la result/ + +# Inspect NixOS build structure +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L +``` ## See Also +- [DEVELOPMENT.md](DEVELOPMENT.md) - Development workflow +- [INVENTORY.md](INVENTORY.md) - Host configuration +- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment - [README.md](../README.md) - Main documentation -- [INVENTORY.md](INVENTORY.md) - Host configuration guide -- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment guide diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 9b114ef..4ad8558 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,464 +1,456 @@ # Development Guide -This guide covers development workflows for maintaining and extending the nixos-systems repository. +Comprehensive guide for maintaining and extending Athenix. ## Table of Contents - [Prerequisites](#prerequisites) +- [Development Workflow](#development-workflow) - [Testing Changes](#testing-changes) - [Continuous Integration](#continuous-integration) -- [System Rebuilds](#system-rebuilds) -- [Updating Dependencies](#updating-dependencies) -- [Adding Packages](#adding-packages) -- [Python Development](#python-development) -- [Contributing](#contributing) +- [Common Tasks](#common-tasks) +- [Debugging](#debugging) +- [Troubleshooting](#troubleshooting) ## Prerequisites -Install Nix with flakes support: +### Install Nix with Flakes ```bash -# Recommended: Determinate Systems installer (includes flakes) +# Recommended: Determinate Systems installer curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install -# Alternative: Official installer (requires enabling flakes manually) +# Or official installer sh <(curl -L https://nixos.org/nix/install) --daemon + +# Enable flakes in existing installation +mkdir -p ~/.config/nix +echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf +``` + +### Clone Repository + +```bash +git clone https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git +cd athenix + +# Optional: enable direnv for automatic Nix environment +direnv allow +``` + +## Development Workflow + +### Making Changes + +1. **Edit configuration files** - Modify `inventory.nix`, `users.nix`, or host/software config + +2. **Validate** - Check syntax and configuration + +```bash +nix flake check +``` + +3. **Format code** - Apply consistent formatting + +```bash +nix fmt +``` + +4. **Test** - Build specific artifacts or configurations + +```bash +# Test specific host +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel + +# Or build an artifact +nix build .#installer-iso-nix-laptop1 +``` + +5. **Commit and push** + +```bash +git add . +git commit -m "Brief description of changes" +git push +``` + +### Example: Adding a New User + +1. Define user in `users.nix`: + +```nix +athenix.users.newuser = { + description = "New User"; + extraGroups = [ "wheel" "networkmanager" ]; + shell = pkgs.zsh; + hashedPassword = "..."; # mkpasswd -m sha-512 +}; +``` + +2. Enable on hosts in `inventory.nix`: + +```nix +nix-laptop = { + devices = 5; + overrides.athenix.users.newuser.enable = true; +}; +``` + +3. Validate and commit: + +```bash +nix flake check +nix fmt +git add . && git commit -m "Add newuser account" +git push ``` ## Testing Changes -Always test configuration changes before committing. +### Validate Configuration Syntax -### Validate All Configurations +Always run before committing: ```bash -# Check all configurations build correctly nix flake check +``` -# Check with verbose error traces -nix flake check --show-trace +Shows any configuration errors across all ~50+ hosts. Output: + +``` +checking 50 configurations... +✓ All checks passed ``` ### Test Specific Host Build ```bash -# Build a specific host's configuration +# Build specific host (shows if config actually compiles) nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -# Build installer for specific host -nix build .#installer-iso-nix-laptop1 +# Shorter form +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L ``` -### Test Local Changes - -If you're on a NixOS system managed by this flake: +### Test Installer Build ```bash -# Test changes without committing (temporary, doesn't survive reboot) +# Test that installer ISO builds +nix build .#installer-iso-nix-laptop1 -L +``` + +### Test on Running NixOS System + +If you're on a NixOS system managed by Athenix: + +```bash +# Test changes temporarily (won't survive reboot) sudo nixos-rebuild test --flake . -# Apply and switch to new configuration +# Apply and switch (persistent) sudo nixos-rebuild switch --flake . # Build without switching sudo nixos-rebuild build --flake . + +# Show what will change +sudo nixos-rebuild dry-activate --flake . +``` + +### Rollback + +If a build breaks your system: + +```bash +# List recent generations +nix-env --list-generations + +# Rollback to previous generation +nix-env --rollback + +# Or switch to specific generation +nix-env --switch-generation 42 ``` ## Continuous Integration -The repository uses Gitea Actions for automated testing and validation. CI jobs run on the self-hosted `nix-builder` machine. +### CI Pipeline -### CI Workflow +All pushes and pull requests trigger automated tests on the self-hosted `nix-builder`: -All pull requests and pushes to main trigger the CI pipeline, which includes: - -1. **Flake Check** - Validates all NixOS configurations - - Runs `nix flake check` to ensure all systems build correctly - - Catches configuration errors early - -2. **Format Check** - Ensures code formatting consistency - - Verifies code is formatted with `nix fmt` - - Automatically fails if formatting is incorrect - -3. **Build Key Configurations** - Tests critical system builds - - Builds: `nix-builder`, `nix-laptop1`, `nix-desktop1` - - Ensures core configurations compile successfully - -4. **Build Artifacts** - Validates installer and container builds - - Builds: `lxc-nix-builder`, `installer-iso-nix-laptop1` - - Verifies deployment artifacts are buildable +1. **Flake Check** - `nix flake check` validates all 50+ configurations +2. **Format Check** - Verifies code formatted with `nix fmt` +3. **Build Key Hosts** - Builds `nix-builder`, `nix-laptop1`, `nix-desktop1` +4. **Build Artifacts** - Tests `lxc-nix-builder` and `installer-iso-nix-laptop1` ### Viewing CI Status -Check the CI status badge at the top of the README or view detailed logs: - ```bash -# View workflow status +# Web interface https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions + +# Or check locally +git log --oneline -n 5 +# Look for ✓ or ✗ next to commits ``` ### Running CI Checks Locally -Before pushing changes, run the same checks that CI performs: +Test before pushing: ```bash -# Run all checks +# Flake check nix flake check --show-trace -# Check formatting -nix fmt -git diff --exit-code # Should return no changes +# Format check +nix fmt --check -# Build specific configuration -nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel +# Format code +nix fmt **/*.nix -# Build artifacts -nix build .#lxc-nix-builder +# Build key configurations +nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel -L +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L ``` -### Self-Hosted Runner +## Common Tasks -CI jobs run on the `nix-builder` host as a self-hosted Gitea Actions runner. This provides: +### Adding a New Host -- Native Nix environment without installation overhead -- Access to local Nix store for faster builds -- Consistent build environment matching deployment targets -- Direct access to build caching infrastructure - -#### Setting Up the Gitea Actions Runner - -The nix-builder host is configured with a Gitea Actions self-hosted runner in `inventory.nix`. To complete the setup: - -1. **Generate a Gitea Runner Token**: - - Go to https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners - - Click "Create new Runner" - - Copy the registration token - -2. **Create the token file on nix-builder**: - ```bash - ssh engr-ugaif@nix-builder - echo "YOUR_TOKEN_HERE" | sudo tee /var/lib/gitea-runner-token > /dev/null - sudo chmod 600 /var/lib/gitea-runner-token - ``` - -3. **Rebuild the system** to start the runner: - ```bash - sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-builder - ``` - -4. **Verify the runner is registered**: - - Check https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners - - The runner should appear with the `nix-builder` label - -The runner service is configured in the nix-builder device configuration and will automatically: -- Register with the repository on first start -- Use the `nix-builder` label for workflow targeting -- Run as the `engr-ugaif` user -- Store work in `/var/lib/gitea-runner` - -### Troubleshooting CI Failures - -If CI fails: - -1. **Check the error logs** in the Gitea Actions tab -2. **Run the same command locally** to reproduce the issue -3. **Use `--show-trace`** for detailed error information -4. **Verify formatting** with `nix fmt` if format check fails -5. **Check for external dependencies** that might be unavailable - -Common CI issues: - -- **Flake check fails**: Configuration error in a host definition -- **Format check fails**: Run `nix fmt` locally and commit changes -- **Build fails**: Missing dependency or syntax error in Nix expressions -- **Cache issues**: Usually self-resolving; can retry the workflow - -## System Rebuilds - -### From Local Directory - -```bash -# Rebuild current host from local directory -sudo nixos-rebuild switch --flake . - -# Rebuild specific host -sudo nixos-rebuild switch --flake .#nix-laptop1 - -# Test without switching (temporary, doesn't persist reboot) -sudo nixos-rebuild test --flake .#nix-laptop1 - -# Build a new generation without activating it -sudo nixos-rebuild build --flake . -``` - -### From GitHub - -```bash -# Rebuild from GitHub main branch -sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git - -# Use --impure for external user configurations with fetchGit -sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure - -# Rebuild specific host from GitHub -sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-laptop1 -``` - -### Boot into Previous Generation - -If something breaks: - -```bash -# List generations -sudo nixos-rebuild list-generations - -# Rollback to previous generation -sudo nixos-rebuild switch --rollback - -# Or select specific generation at boot (GRUB menu) -# Reboot and select "NixOS - Configuration X" from boot menu -``` - -## Updating Dependencies - -### Update All Inputs - -```bash -# Update all flake inputs (nixpkgs, home-manager, etc.) -nix flake update - -# Review changes -git diff flake.lock - -# Test the updates -nix flake check - -# Commit if successful -git add flake.lock -git commit -m "Update flake inputs" -git push -``` - -### Update Specific Input - -```bash -# Update only nixpkgs -nix flake lock --update-input nixpkgs - -# Update home-manager -nix flake lock --update-input home-manager - -# Update multiple specific inputs -nix flake lock --update-input nixpkgs --update-input home-manager -``` - -### Check for Security Updates - -```bash -# After updating, check for known vulnerabilities -nix flake check - -# Review nixpkgs changelog -git log HEAD..nixpkgs/nixos-25.11 --oneline | head -20 -``` - -## Adding Packages - -### System-Wide Packages by Type - -Add packages based on system type: - -**Desktop systems:** -```bash -# Edit sw/desktop/programs.nix -vim sw/desktop/programs.nix -``` - -**Tablet kiosks:** -```bash -# Edit sw/tablet-kiosk/programs.nix -vim sw/tablet-kiosk/programs.nix -``` - -**Headless systems:** -```bash -# Edit sw/headless/programs.nix -vim sw/headless/programs.nix -``` - -### Packages for Specific Hosts - -Add to `athenix.sw.extraPackages` in `inventory.nix`: +Edit `inventory.nix`: ```nix -nix-laptop = { - devices = 2; +nix-surface = { + devices = 3; # Creates nix-surface1, nix-surface2, nix-surface3 overrides = { - athenix.sw.extraPackages = with pkgs; [ - vim - docker - kubernetes-helm - ]; + athenix.sw.type = "tablet-kiosk"; + athenix.sw.kioskUrl = "https://dashboard.example.com"; }; }; ``` -### User-Specific Packages - -Add to user's home-manager configuration in their external `user.nix`: - -```nix -# In external user.nix -home.packages = with pkgs; [ - ripgrep - fd - bat -]; -``` - -### Search for Packages +Test: ```bash -# Search nixpkgs -nix search nixpkgs firefox -nix search nixpkgs python3 - -# Show package details -nix eval nixpkgs#firefox.meta.description -``` - -## Python Development - -All systems include modern Python tools: `pixi` and `uv`. - -### Pixi (Recommended for Projects) - -```bash -# Initialize new project -pixi init my-project -cd my-project - -# Add dependencies -pixi add pandas numpy matplotlib jupyter - -# Run Python -pixi run python - -# Run Jupyter -pixi run jupyter notebook - -# Run scripts -pixi run python script.py - -# Shell with dependencies -pixi shell -``` - -### uv (Quick Virtual Environments) - -```bash -# Create virtual environment -uv venv - -# Activate -source .venv/bin/activate - -# Install packages -uv pip install requests pandas - -# Freeze requirements -uv pip freeze > requirements.txt - -# Install from requirements -uv pip install -r requirements.txt -``` - -### System Python - -Python development tools are configured in `sw/python.nix` and can be controlled via: - -```nix -athenix.sw.python.enable = true; # Default: enabled -``` - -## Contributing - -### Code Style - -- Run formatter before committing: `nix fmt` -- Follow existing code structure and conventions -- Add comments for complex logic -- Use the `athenix.*` namespace for all custom options - -### Testing Workflow - -1. Make changes -2. Run formatter: `nix fmt` -3. Test locally: `nix flake check` -4. Test specific builds if needed -5. Commit changes -6. Push to GitHub - -```bash -# Full workflow -nix fmt nix flake check -git add . -git commit -m "Description of changes" -git push +nix build .#installer-iso-nix-surface1 -L ``` -### Documentation +### Modifying Software Configuration -Update relevant documentation when making changes: - -- `README.md` - Overview and quick start -- `docs/INVENTORY.md` - Inventory configuration -- `docs/NAMESPACE.md` - Configuration options -- `USER_CONFIGURATION.md` - User management -- `EXTERNAL_MODULES.md` - External modules - -### Creating Issues - -When reporting bugs or requesting features: - -1. Check existing issues first -2. Provide clear description -3. Include error messages and traces -4. Specify which hosts are affected -5. Include `flake.lock` info if relevant - -## Useful Commands +Edit appropriate file in `sw/`: ```bash -# Show all available outputs -nix flake show +# Desktop software +vim sw/desktop/programs.nix -# Evaluate specific option -nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName +# Or for all systems +vim sw/default.nix +``` +Use `athenix.sw.extraPackages` for host-specific additions: + +```nix +nix-laptop = { + devices = 5; + overrides.athenix.sw.extraPackages = with pkgs; [ special-tool ]; +}; +``` + +### Adding a System Type + +Create new type in `sw/`: + +```bash +mkdir -p sw/my-type +touch sw/my-type/{default.nix,programs.nix,services.nix} +``` + +Then reference in `sw/default.nix`: + +```nix +{ + imports = [ + ./my-type/default.nix + # ... other types + ]; +} +``` + +### Using External Configurations + +For user dotfiles: + +```nix +# users.nix +athenix.users.myuser.external = builtins.fetchGit { + url = "https://git.factory.uga.edu/username/dotfiles"; + rev = "abc123..."; # Pin to commit +}; +``` + +For system config: + +```nix +# inventory.nix +nix-lxc = { + devices."server" = builtins.fetchGit { + url = "https://git.factory.uga.edu/org/server-config"; + rev = "abc123..."; + }; +}; +``` + +### Updating Dependencies + +```bash +# Update all flake inputs +nix flake update + +# Update specific input +nix flake update nixpkgs + +# Show what changed +git diff flake.lock + +# Test after update +nix flake check --show-trace + +# If tests pass, commit +git add flake.lock && git commit -m "Update dependencies" +``` + +## Debugging + +### Verbose Output + +Get detailed error messages: + +```bash +# Show full error traces +nix flake check --show-trace + +# With maximum verbosity +nix build .#installer-iso-nix-laptop1 -vvv + +# Show build log +nix build .#installer-iso-nix-laptop1 -L +``` + +### Inspect Configuration + +```bash +# Evaluate configuration for specific host +nix eval .#nixosConfigurations.nix-laptop1.config.athenix.sw --json + +# Get all host names +nix eval .#nixosConfigurations --apply builtins.attrNames + +# Check specific option +nix eval .#nixosConfigurations.nix-laptop1.config.users.users +``` + +### Test Module Loading + +```bash +# Evaluate specific module +nix-build -A nixosConfigurations.nix-laptop1.config.system.build.toplevel + +# Or with flakes +nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel --verbose +``` + +### Check Derivation Dependencies + +```bash +# Show what dependencies a build needs +nix show-derivation .#installer-iso-nix-laptop1 + +# Or human-readable +nix build .#installer-iso-nix-laptop1 --dry-run +``` + +## Troubleshooting + +### Common Errors + +#### "Evaluation error" + +``` +error: evaluation aborted with the following error message: '...' +``` + +**Solution:** Check syntax in modified files. Use `nix fmt` and `nix flake check --show-trace`. + +#### "Unknown variable" or "Option does not exist" + +``` +error: The option `athenix.xyz' does not exist. +``` + +**Solution:** Check NAMESPACE.md for available options. Options must be in `athenix.*` namespace. + +#### "Hash mismatch" (for external modules) + +``` +error: Hash mismatch in fetched input +``` + +**Solution:** Update the pin. For `builtins.fetchGit`, use actual commit hash. Or: + +```bash +nix flake update +``` + +#### Build runs out of memory + +```bash +# Reduce parallel jobs +nix build . --max-jobs 1 +``` + +#### "No such file or directory" in build + +```bash +# Check path exists +ls -la /path/to/file + +# Or check relative to repo +ls -la sw/my-file.nix +``` + +### Helpful Diagnostics + +```bash # List all hosts nix eval .#nixosConfigurations --apply builtins.attrNames -# Check flake metadata -nix flake metadata +# Show flake structure +nix flake show | head -50 -# Show evaluation trace -nix eval --show-trace .#nixosConfigurations.nix-laptop1 +# Check Nix store size +du -sh /nix/store -# Build and enter debug shell -nix develop +# List top space users in store +nix store du --human-readable | head -20 -# Clean up old generations -nix-collect-garbage -d - -# Optimize Nix store -nix store optimise +# Find store paths for a package +nix store path-info -rS $(which some-package) ``` +### Getting Help + +1. **Check documentation** - Review relevant doc file +2. **Look at existing examples** - Check `inventory.nix` or `users.nix` +3. **Search for similar patterns** - `grep -r "athenix.option" .` +4. **Run tests locally** - `nix flake check --show-trace` with full output +5. **Review git history** - `git log --patch -- filename.nix` + ## See Also -- [README.md](../README.md) - Main documentation -- [INVENTORY.md](INVENTORY.md) - Host inventory configuration -- [BUILDING.md](BUILDING.md) - Building installation media +- [BUILDING.md](BUILDING.md) - Building artifacts +- [INVENTORY.md](INVENTORY.md) - Host configuration +- [NAMESPACE.md](NAMESPACE.md) - Configuration options - [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management +- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules +- [README.md](../README.md) - Main documentation diff --git a/docs/EXTERNAL_MODULES.md b/docs/EXTERNAL_MODULES.md index 65552d3..48203e1 100644 --- a/docs/EXTERNAL_MODULES.md +++ b/docs/EXTERNAL_MODULES.md @@ -1,6 +1,6 @@ # External Configuration Modules -This guide explains how to use external modules for system and user configurations in nixos-systems. +Guide to using external modules for system and user configurations. ## Table of Contents @@ -8,116 +8,125 @@ This guide explains how to use external modules for system and user configuratio - [System Modules](#system-modules) - [User Modules](#user-modules) - [Fetch Methods](#fetch-methods) -- [Templates](#templates) -- [Integration Details](#integration-details) +- [Creating External Modules](#creating-external-modules) +- [Best Practices](#best-practices) ## Overview -External modules allow you to maintain configurations in separate Git repositories and reference them from `inventory.nix` (for systems) or `users.nix` (for users). +External modules allow you to maintain configurations in separate Git repositories and reference them from Athenix. **Benefits:** -- **Separation:** Keep configs in separate repositories -- **Versioning:** Pin to specific commits for reproducibility -- **Reusability:** Share configurations across deployments -- **Flexibility:** Mix external modules with local overrides +- **Separation** - Keep complex configs in separate repositories +- **Reproducibility** - Pin specific commits for deterministic builds +- **Reusability** - Share configurations across multiple deployments +- **Flexibility** - Mix external modules with local configuration +- **Ownership** - Users maintain their own dotfiles ## System Modules -External system modules provide complete NixOS configurations for hosts. +External system modules provide host-specific NixOS configurations. -### Usage in inventory.nix +### Usage + +In `inventory.nix`, reference an external module as a device: ```nix nix-lxc = { devices = { - # Traditional inline configuration + # Inline configuration "local-server" = { - athenix.users.admin.enable = true; + athenix.sw.type = "headless"; services.nginx.enable = true; }; - # External module from Git + # External module "remote-server" = builtins.fetchGit { url = "https://git.factory.uga.edu/org/server-config"; - rev = "abc123..."; # Pin to specific commit + rev = "abc123def456..."; # Must pin to specific commit }; }; }; ``` -### External Repository Structure +### Repository Structure ``` server-config/ -├── default.nix # Required: NixOS module -└── README.md # Optional: Documentation +├── default.nix # Required: NixOS module +├── README.md # Recommended: Documentation +└── optional/ + ├── config/ # Optional: Configuration files + └── scripts/ # Optional: Helper scripts ``` -**default.nix:** +### Module Content (default.nix) + ```nix +# The module receives inputs and standard NixOS module parameters { inputs, ... }: { config, lib, pkgs, ... }: { # Your NixOS configuration + # Use any standard NixOS option or athenix.* options + services.nginx = { enable = true; virtualHosts."example.com" = { root = "/var/www"; + forceSSL = true; + enableACME = true; }; }; - # Use athenix namespace options - athenix.users.admin.enable = true; + # Use athenix options athenix.sw.type = "headless"; + athenix.sw.extraPackages = with pkgs; [ git htop ]; + + # Standard NixOS configuration + networking.firewall.allowedTCPPorts = [ 80 443 ]; + services.openssh.enable = true; } ``` -### What External Modules Receive +### What System Modules Receive -- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.) -- **`config`** - Full NixOS configuration +- **`inputs`** - All flake inputs (nixpkgs, home-manager, disko, etc.) +- **`config`** - Current NixOS configuration (read/write) - **`lib`** - Nixpkgs library functions - **`pkgs`** - Package set -### Module Integration Order +### Configuration Order -When a host is built, modules are loaded in this order: +When a host is built, modules load in this order: -1. User NixOS modules (from `users.nix` - `nixos.nix` files) -2. Host type module (from `hosts/types/`) -3. Configuration overrides (from `inventory.nix`) -4. Hostname assignment -5. External system module (if using `builtins.fetchGit`) +1. Hardware type module (from `hosts/types/nix-*.nix`) +2. Host common configuration (from `hosts/common.nix`) +3. Software type module (from `sw/{type}/`) +4. User NixOS modules (from `users.nix` - `nixos.nix` files) +5. Device-specific overrides (from `inventory.nix`) +6. External system module (if present) -Later modules can override earlier ones using standard NixOS module precedence. - -### Template - -Create a new system module: - -```bash -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system -``` - -See [templates/system/](../templates/system/) for the complete template. +Each later module can override earlier ones using standard NixOS precedence rules. ## User Modules -External user modules provide home-manager configurations (dotfiles, packages, programs). +External user modules provide home-manager configurations (dotfiles, environment setup). -### Usage in users.nix +### Usage + +In `users.nix`, reference an external user module: ```nix athenix.users = { - # External user module (dotfiles, home-manager, and user options) - myuser = builtins.fetchGit { + # External user module + myuser.external = builtins.fetchGit { url = "https://git.factory.uga.edu/username/dotfiles"; - rev = "abc123..."; + rev = "abc123def456..."; # Pin to specific commit }; # Inline user definition - inlineuser = { - description = "Inline User"; + otheruser = { + description = "Other User"; extraGroups = [ "wheel" ]; shell = pkgs.zsh; hashedPassword = "$6$..."; @@ -125,148 +134,179 @@ athenix.users = { }; ``` -### External Repository Structure +Then enable on hosts in `inventory.nix`: -``` -dotfiles/ -├── user.nix # Required: User options AND home-manager config -├── nixos.nix # Optional: System-level config -└── config/ # Optional: Actual dotfiles - ├── bashrc - └── vimrc -``` - -**user.nix (required):** ```nix +nix-laptop = { + devices = 5; + overrides.athenix.users.myuser.enable = true; +}; +``` + +### Repository Structure + +``` +my-dotfiles/ +├── user.nix # Required: User options + home-manager config +├── nixos.nix # Optional: System-level configuration +├── README.md # Recommended: Documentation +└── config/ # Optional: Your actual dotfiles + ├── zshrc + ├── vimrc + ├── nvim/ + └── ... +``` + +### user.nix (Required) + +Provides both user account settings AND home-manager configuration: + +```nix +# Receives { inputs } and standard home-manager module parameters { inputs, ... }: { config, lib, pkgs, osConfig ? null, ... }: { # ========== User Account Configuration ========== + # These options define the user account itself + athenix.users.myusername = { - description = "Your Full Name"; + description = "My Full Name"; + extraGroups = [ "wheel" "docker" ]; shell = pkgs.zsh; - hashedPassword = "!"; - opensshKeys = [ "ssh-ed25519 AAAA..." ]; + hashedPassword = "!"; # SSH keys only + opensshKeys = [ + "ssh-ed25519 AAAA... user@laptop" + ]; useZshTheme = true; useNvimPlugins = true; }; # ========== Home Manager Configuration ========== + # User environment, packages, and dotfiles + # Packages home.packages = with pkgs; [ vim git - htop + ripgrep + fzf ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox; - + + # Programs 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 + export EDITOR=vim + ''; + }; + # Manage dotfiles - home.file.".bashrc".source = ./dotfiles/bashrc; + home.file.".zshrc".source = ./config/zshrc; + home.file.".vimrc".source = ./config/vimrc; + home.file.".config/nvim".source = ./config/nvim; + + # Services + services.gpg-agent.enable = true; } ``` -**nixos.nix (optional):** +### nixos.nix (Optional) + +System-level configuration for this user (rarely needed): + ```nix { inputs, ... }: { config, lib, pkgs, ... }: { - # System-level configuration for this user - users.users.myuser.extraGroups = [ "docker" ]; + # System-level configuration + # Only needed if the user requires specific system-wide settings + + users.users.myusername.extraGroups = [ "docker" ]; environment.systemPackages = [ pkgs.docker ]; + + # Security settings + security.sudo.extraRules = [{ + users = [ "myusername" ]; + commands = [{ + command = "/usr/bin/something"; + options = [ "NOPASSWD" ]; + }]; + }]; } ``` ### What User Modules Receive **In user.nix:** -- **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.) -- **`config`** - Home-manager configuration +- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.) +- **`config`** - Home-manager configuration (read/write) - **`lib`** - Nixpkgs library functions - **`pkgs`** - Package set -- **`osConfig`** - OS-level configuration (read-only) +- **`osConfig`** - OS configuration (read-only) - useful for conditional setup **In nixos.nix:** - **`inputs`** - Flake inputs -- **`config`** - NixOS configuration -- **`lib`** - Nixpkgs library functions +- **`config`** - NixOS configuration (read/write) +- **`lib`** - Nixpkgs library functions - **`pkgs`** - Package set -### User Options in users.nix +### Conditional Setup Example + +Use `osConfig` to conditionally set up dotfiles based on the system type: ```nix -username = { - # Identity - description = "Full Name"; - - # External configuration - external = builtins.fetchGit { ... }; - # System settings - extraGroups = [ "wheel" "networkmanager" ]; - hashedPassword = "$6$..."; - opensshKeys = [ "ssh-ed25519 ..." ]; - shell = pkgs.zsh; - - # Theme integration - useZshTheme = true; # Apply system zsh theme (default: true) - useNvimPlugins = true; # Apply system nvim config (default: true) - - # Enable on specific systems (see docs/INVENTORY.md) - enable = false; # Set in inventory.nix via athenix.users.username.enable -}; +# In user.nix +{ inputs, ... }: +{ config, lib, pkgs, osConfig ? null, ... }: +{ + athenix.users.myuser = { /* ... */ }; + + # Install Firefox only on desktop systems + home.packages = with pkgs; [ + ripgrep + ] ++ lib.optional (osConfig.athenix.sw.type or null == "desktop") firefox; + + # Different shell config per system + programs.zsh.initExtra = '' + ${lib.optionalString (osConfig.athenix.sw.type or null == "headless") " + # Headless-only settings + "} + ''; +} ``` -### Template - -Create a new user module: - -```bash -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user -``` - -See [templates/user/](../templates/user/) for the complete template. - ## Fetch Methods -### Recommended: fetchGit with Revision +### builtins.fetchGit (Recommended) -Pin to a specific commit for reproducibility: +Pin to a specific Git revision: ```nix builtins.fetchGit { - url = "https://github.com/user/repo"; - rev = "abc123def456..."; # Full commit hash (40 characters) - ref = "main"; # Optional: branch name + url = "https://git.factory.uga.edu/username/dotfiles"; + rev = "abc123def456..."; # Required: specific commit hash } ``` -**Finding the commit hash:** -```bash -# Latest commit on main branch -git ls-remote https://github.com/user/repo main +**Advantages:** +- Reproducible (pinned to exact commit) +- Works with any Git repository +- Supports SSH or HTTPS URLs -# Or from a local clone -git rev-parse HEAD -``` +**Important:** Always specify `rev` (commit hash) for reproducibility. Don't use branches which can change. -### fetchGit with Branch (Less Reproducible) - -Always fetches latest from branch: - -```nix -builtins.fetchGit { - url = "https://github.com/user/repo"; - ref = "develop"; -} -``` - -⚠️ **Warning:** Builds may not be reproducible as the branch HEAD can change. - -### fetchTarball (For Releases) +### builtins.fetchTarball Download specific release archives: @@ -287,174 +327,141 @@ nix-prefetch-url --unpack https://github.com/user/repo/archive/v1.0.0.tar.gz Use local directories during development: ```nix -/home/username/dev/my-config +# users.nix +athenix.users.myuser.external = /home/user/my-dotfiles; -# Or relative to repository -./my-local-config -``` - -⚠️ **Warning:** Only for testing. Use Git-based methods for production. - -## Templates - -### System Module Template - -```bash -# Initialize in new directory -mkdir my-server-config -cd my-server-config -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system -``` - -See [templates/system/README.md](../templates/system/README.md) for detailed usage. - -### User Module Template - -```bash -# Initialize in new directory -mkdir my-dotfiles -cd my-dotfiles -nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user -``` - -See [templates/user/README.md](../templates/user/README.md) for detailed usage. - -## Integration Details - -### Detection Logic - -The system automatically detects external modules when a device or user value is: -- A path (`builtins.isPath`) -- A string starting with `/` (absolute path) -- A derivation (`lib.isDerivation`) -- An attrset with `outPath` attribute (result of `fetchGit`/`fetchTarball`) - -### System Module Integration - -External system modules are imported and merged into the NixOS configuration: - -```nix -import externalModulePath { inherit inputs; } -``` - -They can use all standard NixOS options plus `athenix.*` namespace options. - -### User Module Integration - -External user modules are loaded in two contexts: - -**User options (NixOS module context):** -```nix -import (externalPath + "/user.nix") { inherit inputs; } -# Evaluated as NixOS module to extract athenix.users. options -``` - -**Home-manager configuration:** -```nix -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 - -You can mix external modules with local overrides: - -```nix -nix-lxc = { +# inventory.nix +nix-laptop = { devices = { - "server" = builtins.fetchGit { - url = "https://git.factory.uga.edu/org/base-config"; - rev = "abc123..."; - }; - }; - overrides = { - # Apply to all devices, including external ones - athenix.users.admin.enable = true; - networking.firewall.allowedTCPPorts = [ 80 443 ]; + "dev".athenix.users.myuser.enable = true; }; }; ``` -### Minimal User Module +**Note:** Only works if the path exists on the machine running `nix flake check` or `nix build`. -**user.nix:** +## Creating External Modules + +### System Module Template + +Create a new system module repository from the template: + +```bash +nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system +``` + +This creates: + +``` +my-system-config/ +├── flake.nix # Optional: for testing standalone +├── default.nix # Your NixOS module +└── README.md # Documentation +``` + +### User Module Template + +Create a new user module repository: + +```bash +nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user +``` + +This creates: + +``` +my-dotfiles/ +├── flake.nix # Optional: for testing standalone +├── user.nix # User options + home-manager config +├── nixos.nix # Optional: system-level config +└── README.md # Documentation +``` + +### Testing External Modules + +Test your external module locally before pushing: + +```bash +# In your module repository +cd /path/to/my-module + +# Test the Nix syntax +nix flake check +``` + +## Best Practices + +### 1. Always Pin to Specific Commits + +❌ Wrong - using branch names: ```nix -{ inputs, ... }: -{ config, lib, pkgs, osConfig ? null, ... }: -{ - # User account options - athenix.users.myusername = { - description = "My Name"; - shell = pkgs.zsh; - hashedPassword = "!"; - }; - - # Home-manager config - home.packages = with pkgs; [ vim git ]; +builtins.fetchGit { + url = "https://git.factory.uga.edu/username/dotfiles"; + # No rev specified or using "main" } ``` -### Full User Module with Dotfiles - -``` -dotfiles/ -├── user.nix -├── nixos.nix -└── config/ - ├── bashrc - ├── vimrc - └── gitconfig -``` - -**user.nix:** +✅ Correct - using commit hash: ```nix -{ inputs, ... }: -{ config, lib, pkgs, osConfig ? null, ... }: -{ - # User account configuration - athenix.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.athenix.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; - ".vimrc".source = ./config/vimrc; - ".gitconfig".source = ./config/gitconfig; - }; +builtins.fetchGit { + url = "https://git.factory.uga.edu/username/dotfiles"; + rev = "abc123def456789..."; } ``` +### 2. Keep External Modules Focused + +Each external module should have a clear purpose: +- User dotfiles (one repo per user) +- System service configuration (one repo per service/cluster) +- Hardware-specific config (one repo per hardware setup) + +### 3. Document Your Modules + +Include a README with: +- What the module configures +- Required dependencies +- Usage examples +- Configuration options + +### 4. Use Semantic Versioning + +Tag releases in Git: + +```bash +git tag v1.0.0 +git push origin v1.0.0 +``` + +Reference specific versions: + +```nix +builtins.fetchGit { + url = "https://git.factory.uga.edu/org/server-config"; + rev = "v1.0.0"; # Can use tags too +} +``` + +### 5. Test Before Updating Pins + +When updating commit hashes: + +```bash +# Test new revision locally +nix flake update + +# Validate all configurations +nix flake check --show-trace + +# Only commit after validation +git add . && git commit -m "Update module versions" +``` + ## See Also -- [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 +- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management +- [INVENTORY.md](INVENTORY.md) - Host configuration +- [NAMESPACE.md](NAMESPACE.md) - Configuration options - [README.md](../README.md) - Main documentation +- [templates/user/](../templates/user/) - User module template +- [templates/system/](../templates/system/) - System module template diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md index a85623e..f83b5e8 100644 --- a/docs/INVENTORY.md +++ b/docs/INVENTORY.md @@ -1,101 +1,272 @@ # Host Inventory Configuration -This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices. +This document explains the `inventory.nix` file, which defines all hosts in your fleet. ## Table of Contents -- [Understanding Inventory Structure](#understanding-inventory-structure) -- [Hostname Generation Rules](#hostname-generation-rules) -- [Adding Hosts](#adding-hosts) -- [Device Configuration Options](#device-configuration-options) +- [Overview](#overview) +- [Structure](#structure) +- [Hostname Generation](#hostname-generation) +- [Configuration Methods](#configuration-methods) +- [Options](#options) - [Examples](#examples) -## Understanding Inventory Structure +## Overview -The `inventory.nix` file defines all hosts in the fleet using a flexible system. Top-level keys are always hostname **prefixes**, and actual hostnames are generated from device configurations. +`inventory.nix` defines your fleet of hosts. Top-level keys are hostname **prefixes**, and actual hostnames are generated from device specifications. This allows you to manage large fleets with minimal repetition. -## Hostname Generation Rules +**Key concepts:** +- Each top-level key generates one or more NixOS configurations +- Host type defaults to the prefix name (can be overridden) +- System architecture defaults to `x86_64-linux` +- Common configuration can be applied to all devices in a group via `overrides` -- **Numeric suffixes**: no dash (e.g., `nix-laptop1`, `nix-laptop2`) -- **Non-numeric suffixes**: with dash (e.g., `nix-laptop-alpha`, `nix-laptop-beta`) -- **Custom hostnames**: Set `athenix.host.useHostPrefix = false` to use suffix as full hostname - -## Adding Hosts - -### Method 1: Quick Count (Simplest) +## Structure ```nix -nix-laptop = { - devices = 5; # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5 -}; +{ + "prefix-name" = { + # Optional: Device count or explicit device map + devices = 5; # or { "1" = { ... }; "alpha" = { ... }; } + + # Optional: Hardware type (defaults to prefix name) + type = "nix-desktop"; + + # Optional: System architecture + system = "x86_64-linux"; + + # Optional: Configuration applied to ALL devices in this group + overrides = { + athenix.users.student.enable = true; + }; + + # Optional: Per-device configuration + "device-suffix" = { ... }; + }; +} ``` -### Method 2: Explicit Count with Overrides +## Hostname Generation + +Hostnames are generated automatically based on the device key: + +- **Numeric keys** (`"1"`, `"2"`, `"42"`) → no dash: `prefix1`, `prefix2`, `prefix42` +- **Non-numeric keys** (`"alpha"`, `"special"`) → with dash: `prefix-alpha`, `prefix-special` +- **Custom hostnames** → Set `athenix.host.useHostPrefix = false` to use the suffix as the full hostname (no prefix) + +**Examples:** ```nix nix-laptop = { - devices = 5; - overrides = { - # Applied to ALL nix-laptop hosts - athenix.users.student.enable = true; - athenix.sw.extraPackages = with pkgs; [ vim git ]; + devices = 3; # Generates: nix-laptop1, nix-laptop2, nix-laptop3 +}; + +nix-surface = { + devices = { + "1" = { }; # → nix-surface1 + "special" = { }; # → nix-surface-special + }; +}; + +custom-machine = { + devices."lab-machine" = { + athenix.host.useHostPrefix = false; # → lab-machine (not custom-machine-lab-machine) }; }; ``` -### Method 3: Individual Device Configuration +## Configuration Methods + +### Method 1: Simple Count + +Create N identical hosts: + +```nix +nix-laptop = { + devices = 5; +}; +# Generates: nix-laptop1, nix-laptop2, nix-laptop3, nix-laptop4, nix-laptop5 +``` + +### Method 2: Simple Count with Overrides + +Create N hosts with common configuration: + +```nix +nix-desktop = { + devices = 3; + overrides = { + athenix.users.student.enable = true; + athenix.sw.extraPackages = with pkgs; [ vim git ]; + services.openssh.enable = true; + }; +}; +# All three hosts get the overrides configuration +``` + +### Method 3: Explicit Device Map + +Configure each device individually: ```nix nix-surface = { devices = { "1".athenix.sw.kioskUrl = "https://dashboard1.example.com"; "2".athenix.sw.kioskUrl = "https://dashboard2.example.com"; - "3".athenix.sw.kioskUrl = "https://dashboard3.example.com"; + "3" = { + athenix.sw.kioskUrl = "https://dashboard3.example.com"; + services.openssh.enable = false; + }; }; }; ``` -### Method 4: Mixed (Default Count + Custom Devices) +### Method 4: External Module + +Reference a Git repository instead of inline configuration: ```nix -nix-surface = { - defaultCount = 2; # Creates nix-surface1, nix-surface2 +nix-lxc = { + devices."builder" = builtins.fetchGit { + url = "https://git.factory.uga.edu/org/builder-config"; + rev = "abc123..."; + }; +}; +``` + +### Method 5: Mixed Approach + +Combine default count, custom devices, and overrides: + +```nix +nix-lab = { + defaultCount = 5; # Creates nix-lab1 through nix-lab5 devices = { - "special" = { # Creates nix-surface-special - athenix.sw.kioskUrl = "https://special-dashboard.example.com"; + "special" = { + athenix.sw.extraPackages = with pkgs; [ special-software ]; }; }; overrides = { - # Applied to all devices (including "special") - athenix.sw.kioskUrl = "https://default-dashboard.example.com"; + # Applied to all devices (default count + custom) + athenix.users.lab-admin.enable = true; }; }; ``` -## Device Configuration Options +## Options -### Direct Configuration (Recommended) +### Top-Level Device Options -Use any NixOS or `athenix.*` option: +#### `devices` + +Specify hosts to create. Can be: +- **Number**: Create N hosts with keys `"1"`, `"2"`, ..., `"N"` +- **Attribute set**: Map of device names to configurations + +**Type**: `int | attrs` + +**Examples:** +```nix +devices = 5; # Creates 5 hosts + +devices = { + "1" = { }; + "alpha" = { }; +}; +``` + +#### `defaultCount` + +When using a device map, also create N numbered hosts. + +**Type**: `int` (optional) + +**Example:** +```nix +defaultCount = 3; # Creates "1", "2", "3" in addition to devices map +devices = { + "special" = { }; +}; +# Result: hosts "1", "2", "3", and "special" +``` + +#### `type` + +Hardware type module to use. Defaults to the prefix name (inferred from top-level key). + +**Type**: `string` (optional) + +**Options**: `nix-desktop`, `nix-laptop`, `nix-surface`, `nix-lxc`, `nix-wsl`, `nix-ephemeral` + +**Example:** +```nix +lab-machines = { + type = "nix-desktop"; # Use desktop hardware configuration + devices = 5; +}; +``` + +#### `system` + +System architecture. Defaults to `x86_64-linux`. + +**Type**: `string` (optional) + +**Example:** +```nix +arm-devices = { + system = "aarch64-linux"; + devices = 2; +}; +``` + +#### `overrides` + +Configuration applied to all devices in this group. Useful for fleet-wide settings. + +**Type**: `attrs` (optional) + +**Example:** +```nix +nix-laptop = { + devices = 10; + overrides = { + # Applied to all 10 laptops + athenix.users.staff.enable = true; + services.openssh.enable = true; + boot.loader.timeout = 10; + }; +}; +``` + +### Per-Device Options + +Any NixOS or `athenix.*` option can be set per-device: ```nix -"1" = { - # Athenix options - athenix.users.myuser.enable = true; - athenix.host.filesystem.swapSize = "64G"; - athenix.sw.extraPackages = with pkgs; [ docker ]; - athenix.sw.kioskUrl = "https://example.com"; - - # Standard NixOS options - networking.firewall.enable = false; - services.openssh.enable = true; - time.timeZone = "America/New_York"; +nix-surface = { + devices = { + "1" = { + # athenix.* namespace options + athenix.users.student.enable = true; + athenix.host.filesystem.device = "/dev/sda"; + athenix.host.filesystem.swapSize = "16G"; + athenix.sw.kioskUrl = "https://dashboard1.example.com"; + athenix.sw.extraPackages = with pkgs; [ firefox ]; + + # Standard NixOS options + networking.firewall.enable = false; + services.openssh.enable = true; + time.timeZone = "America/New_York"; + boot.kernelPackages = pkgs.linuxPackages_latest; + }; + }; }; ``` ### Convenience: `athenix.forUser` -Quick setup for single-user systems (especially WSL): +Quick setup for single-user systems (especially WSL). This automatically enables a user and sets the WSL default user: ```nix nix-wsl = { diff --git a/docs/NAMESPACE.md b/docs/NAMESPACE.md index 14f2986..118688b 100644 --- a/docs/NAMESPACE.md +++ b/docs/NAMESPACE.md @@ -1,53 +1,69 @@ # Configuration Namespace Reference -All UGA Innovation Factory-specific options are under the `athenix` namespace to avoid conflicts with standard NixOS options. +All UGA Innovation Factory-specific options are in the `athenix` namespace to avoid conflicts with standard NixOS options. ## Table of Contents - [Host Configuration (`athenix.host`)](#host-configuration-athenixhost) - [Software Configuration (`athenix.sw`)](#software-configuration-athenixsw) - [User Management (`athenix.users`)](#user-management-athenixusers) -- [System Configuration (`athenix.system`)](#system-configuration-athenixsystem) - [Convenience Options](#convenience-options) ## Host Configuration (`athenix.host`) -Hardware and host-specific settings. +Hardware and boot-related settings. -### `athenix.host.filesystem` +### `athenix.host.filesystem.device` -Disk and storage configuration. +Boot disk device path. -**Options:** -- `athenix.host.filesystem.device` - Boot disk device (default: `/dev/sda`) -- `athenix.host.filesystem.swapSize` - Swap file size (default: `"32G"`) +**Type:** String + +**Default:** `"/dev/sda"` **Example:** ```nix -athenix.host.filesystem = { - device = "/dev/nvme0n1"; - swapSize = "64G"; -}; +athenix.host.filesystem.device = "/dev/nvme0n1"; +``` + +### `athenix.host.filesystem.swapSize` + +Swap partition size. + +**Type:** String (size with unit, e.g., `"32G"`, `"2G"`) + +**Default:** `"32G"` + +**Example:** +```nix +athenix.host.filesystem.swapSize = "64G"; ``` ### `athenix.host.buildMethods` -List of supported build artifact types for this host. +Artifact types to build for this host. **Type:** List of strings **Options:** `"installer-iso"`, `"iso"`, `"ipxe"`, `"lxc"`, `"proxmox"` -**Default:** `["installer-iso"]` +**Default:** `[ "installer-iso" ]` + +**Description:** +- `"installer-iso"` - Installer ISO with auto-install +- `"iso"` - Live ISO (boot without installation) +- `"ipxe"` - iPXE netboot artifacts +- `"lxc"` - LXC container tarball +- `"proxmox"` - Proxmox VMA template **Example:** ```nix -athenix.host.buildMethods = [ "lxc" "proxmox" ]; +athenix.host.buildMethods = [ "installer-iso" "lxc" ]; ``` ### `athenix.host.useHostPrefix` -Whether to prepend the host type prefix to the hostname (used in inventory generation). +Whether to prepend the host type prefix to the generated hostname. **Type:** Boolean @@ -55,15 +71,19 @@ Whether to prepend the host type prefix to the hostname (used in inventory gener **Example:** ```nix -athenix.host.useHostPrefix = false; # "builder" instead of "nix-lxc-builder" +# With useHostPrefix = true (default) +# Device "1" under "nix-laptop" → "nix-laptop1" + +# With useHostPrefix = false +# Device "builder" under "nix-lxc" → "builder" (not "nix-lxc-builder") +athenix.host.useHostPrefix = false; ``` -### `athenix.host.wsl` +### `athenix.host.wsl.user` -WSL-specific configuration options. +Default WSL user account (only for `nix-wsl` type). -**Options:** -- `athenix.host.wsl.user` - Default WSL user for this instance +**Type:** String (username) **Example:** ```nix @@ -72,11 +92,11 @@ athenix.host.wsl.user = "myusername"; ## Software Configuration (`athenix.sw`) -System software and application configuration. +System type, packages, and application configuration. ### `athenix.sw.enable` -Enable the software configuration module. +Enable software configuration. **Type:** Boolean @@ -84,28 +104,32 @@ Enable the software configuration module. ### `athenix.sw.type` -System type that determines the software profile. +System profile/type. Determines which software packages and services are installed. -**Type:** Enum +**Type:** String or list of strings **Options:** -- `"desktop"` - Full desktop environment (GNOME) -- `"tablet-kiosk"` - Surface tablets with kiosk mode browser -- `"stateless-kiosk"` - Diskless PXE boot kiosks +- `"desktop"` - Full GNOME desktop environment with development tools +- `"tablet-kiosk"` - Surface tablets with Firefox kiosk browser +- `"stateless-kiosk"` - Diskless PXE-booted ephemeral systems - `"headless"` - Servers and containers without GUI +- `"builders"` - Build servers with build dependencies **Default:** `"desktop"` **Example:** ```nix -athenix.sw.type = "headless"; +athenix.sw.type = "desktop"; + +# Multiple types supported +athenix.sw.type = [ "desktop" "headless" ]; ``` ### `athenix.sw.kioskUrl` -URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` types). +URL to display in kiosk browser (for `tablet-kiosk` and `stateless-kiosk` types). -**Type:** String +**Type:** String (URL) **Default:** `"https://ha.factory.uga.edu"` @@ -114,12 +138,13 @@ URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` athenix.sw.kioskUrl = "https://dashboard.example.com"; ``` -### `athenix.sw.python` +### `athenix.sw.python.enable` -Python development tools configuration. +Enable Python development tools (pixi, uv, etc.). -**Options:** -- `athenix.sw.python.enable` - Enable Python tools (pixi, uv) (default: `true`) +**Type:** Boolean + +**Default:** `true` **Example:** ```nix @@ -128,11 +153,13 @@ athenix.sw.python.enable = true; ### `athenix.sw.remoteBuild` -Remote build server configuration for offloading builds. +Configure remote build servers for offloading builds. + +**Type:** Attribute set **Options:** -- `athenix.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets) -- `athenix.sw.remoteBuild.hosts` - List of build server hostnames +- `enable` - Enable remote builders (Boolean, default: `true` for tablets) +- `hosts` - List of remote builder hostnames (List of strings) **Example:** ```nix @@ -144,104 +171,187 @@ athenix.sw.remoteBuild = { ### `athenix.sw.extraPackages` -Additional system packages to install beyond the type defaults. +Additional system packages beyond the type defaults. **Type:** List of packages -**Default:** `[]` +**Default:** `[ ]` **Example:** ```nix athenix.sw.extraPackages = with pkgs; [ vim - htop docker + htop + ripgrep ]; ``` ### `athenix.sw.excludePackages` -Packages to exclude from the default list for this system type. +Packages to remove from the default list for this system type. **Type:** List of packages -**Default:** `[]` +**Default:** `[ ]` **Example:** ```nix athenix.sw.excludePackages = with pkgs; [ - firefox # Remove Firefox from default desktop packages + firefox # Don't install Firefox on this system ]; ``` ## User Management (`athenix.users`) -User account configuration and management. +User account configuration and access control. ### `athenix.users..enable` -Enable a specific user account on this system. +Enable a user account on this system. **Type:** Boolean -**Default:** `false` (except `root` and `engr-ugaif` which default to `true`) +**Default:** `false` (except `root` and `engr-ugaif` which are `true`) **Example:** ```nix -athenix.users = { - myuser.enable = true; - student.enable = true; +# In inventory.nix +nix-laptop = { + devices = 5; + overrides.athenix.users.myuser.enable = true; }; ``` -### User Account Options +### User Account Options (in `users.nix`) -Each user in `users.nix` can be configured with: +Define user accounts in `users.nix` with these options: + +#### `description` + +Full name or description of the user. + +**Type:** String ```nix -# Option 1: Define inline in users.nix -athenix.users.myuser = { - description = "Full Name"; - isNormalUser = true; # Default: true - extraGroups = [ "wheel" "docker" ]; # Additional groups - shell = pkgs.zsh; # Login shell - hashedPassword = "$6$..."; # Hashed password - opensshKeys = [ "ssh-ed25519 ..." ]; # SSH public keys - useZshTheme = true; # Use system Zsh theme - useNvimPlugins = true; # Use system Neovim config - - enable = false; # Enable per-system in inventory.nix -}; +athenix.users.myuser.description = "John Doe"; +``` -# Option 2: Use external configuration (recommended) -# The external user.nix can set athenix.users.myuser options directly -athenix.users.anotheruser.external = builtins.fetchGit { +#### `extraGroups` + +Additional Unix groups for the user. + +**Type:** List of strings + +**Common groups:** +- `"wheel"` - Sudo access +- `"networkmanager"` - Network configuration +- `"docker"` - Docker access +- `"video"` - Video device access +- `"audio"` - Audio device access +- `"input"` - Input device access (keyboards, mice) + +```nix +athenix.users.myuser.extraGroups = [ "wheel" "docker" "networkmanager" ]; +``` + +#### `shell` + +Login shell for the user. + +**Type:** Package + +**Default:** `pkgs.bash` + +```nix +athenix.users.myuser.shell = pkgs.zsh; +``` + +#### `hashedPassword` + +Password hash for the user. + +**Type:** String (SHA-512 hash) + +**Generation:** +```bash +mkpasswd -m sha-512 +``` + +```nix +athenix.users.myuser.hashedPassword = "$6$..."; +``` + +#### `opensshKeys` + +SSH public keys for this user. + +**Type:** List of strings + +```nix +athenix.users.myuser.opensshKeys = [ + "ssh-ed25519 AAAA... user@host" + "ssh-rsa AAAA... user@other" +]; +``` + +#### `useZshTheme` + +Apply system Zsh theme configuration to this user. + +**Type:** Boolean + +**Default:** `true` + +```nix +athenix.users.myuser.useZshTheme = true; +``` + +#### `useNvimPlugins` + +Apply system Neovim configuration to this user. + +**Type:** Boolean + +**Default:** `true` + +```nix +athenix.users.myuser.useNvimPlugins = true; +``` + +#### `external` + +Reference external user configuration (dotfiles, home-manager). + +**Type:** Path or Git reference + +**Example:** +```nix +athenix.users.myuser.external = builtins.fetchGit { url = "https://git.factory.uga.edu/username/dotfiles"; rev = "abc123..."; }; ``` -## System Configuration (`athenix.system`) +See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) for detailed external module usage. -System-wide settings and services. +### Enabling Users on Systems -### `athenix.system.gc` +Users defined in `users.nix` are **not enabled by default**. Enable them in `inventory.nix`: -Automatic garbage collection configuration. - -**Options:** -- `athenix.system.gc.enable` - Enable automatic garbage collection (default: `true`) -- `athenix.system.gc.frequency` - How often to run (default: `"weekly"`) -- `athenix.system.gc.retentionDays` - Days to keep old generations (default: `30`) -- `athenix.system.gc.optimise` - Optimize Nix store automatically (default: `true`) - -**Example:** ```nix -athenix.system.gc = { - enable = true; - frequency = "daily"; - retentionDays = 14; - optimise = true; +# Option 1: Enable on all devices in a group +nix-laptop = { + devices = 5; + overrides.athenix.users.student.enable = true; +}; + +# Option 2: Enable on specific devices +nix-surface = { + devices = { + "1".athenix.users.admin.enable = true; + "2".athenix.users.admin.enable = true; + }; }; ``` @@ -249,7 +359,7 @@ athenix.system.gc = { ### `athenix.forUser` -Quick setup option that enables a user account in one line. +Quick setup for single-user systems. Automatically enables a user and sets it as the default. **Type:** String (username) or null @@ -257,11 +367,7 @@ Quick setup option that enables a user account in one line. **Example:** ```nix -athenix.forUser = "myusername"; # Equivalent to athenix.users.myusername.enable = true -``` - -**Usage in inventory.nix:** -```nix +# In inventory.nix - enables the user automatically nix-wsl = { devices = { "alice".athenix.forUser = "alice-uga"; @@ -269,9 +375,17 @@ nix-wsl = { }; ``` +Equivalent to: +```nix +"alice" = { + athenix.users.alice-uga.enable = true; + athenix.host.wsl.user = "alice-uga"; +}; +``` + ## See Also -- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide -- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management guide -- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules +- [INVENTORY.md](INVENTORY.md) - Host configuration examples +- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management guide +- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module integration - [README.md](../README.md) - Main documentation diff --git a/docs/USER_CONFIGURATION.md b/docs/USER_CONFIGURATION.md index 29abd3a..362ded1 100644 --- 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 === diff --git a/inventory.nix b/inventory.nix index ade13ea..0d1ab70 100644 --- a/inventory.nix +++ b/inventory.nix @@ -121,7 +121,7 @@ }; }; "usda-dash" = builtins.fetchGit { - url = "git@factory.uga.edu:MODEL/usda-dash-config.git"; + url = "https://git.factory.uga.edu/MODEL/usda-dash-config.git"; rev = "dab32f5884895cead0fae28cb7d88d17951d0c12"; submodules = true; };