docs: Documentation overhaul
This commit is contained in:
Hunter Halloran
264
docs/BUILDING.md
Normal file
264
docs/BUILDING.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# Building Installation Media
|
||||
|
||||
This guide covers building installer ISOs, live images, and container artifacts from the nixos-systems flake.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
- [Available Artifacts](#available-artifacts)
|
||||
- [Installer ISOs](#installer-isos)
|
||||
- [Live ISOs](#live-isos)
|
||||
- [Container Images](#container-images)
|
||||
- [Remote Builders](#remote-builders)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build an installer ISO for a specific host
|
||||
nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1
|
||||
|
||||
# Result will be in result/iso/
|
||||
ls -lh result/iso/
|
||||
```
|
||||
|
||||
## Available Artifacts
|
||||
|
||||
List all available build outputs:
|
||||
|
||||
```bash
|
||||
nix flake show github:UGA-Innovation-Factory/nixos-systems
|
||||
```
|
||||
|
||||
Common artifact types:
|
||||
|
||||
| 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
|
||||
|
||||
```bash
|
||||
# Build installer for a specific host
|
||||
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 GitHub
|
||||
|
||||
```bash
|
||||
nix build github:UGA-Innovation-Factory/nixos-systems#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 `ugaif.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
|
||||
```
|
||||
|
||||
### Stateless Kiosk Systems
|
||||
|
||||
For PXE netboot kiosks, use the `ipxe-*` artifacts:
|
||||
|
||||
```bash
|
||||
# Build iPXE artifacts
|
||||
nix build .#ipxe-nix-ephemeral1
|
||||
|
||||
# Result contains:
|
||||
# - bzImage (kernel)
|
||||
# - initrd (initial ramdisk)
|
||||
# - netboot.ipxe (iPXE script)
|
||||
ls -lh result/
|
||||
```
|
||||
|
||||
## Container Images
|
||||
|
||||
### LXC Containers
|
||||
|
||||
Build LXC container tarballs for Proxmox or other LXC hosts:
|
||||
|
||||
```bash
|
||||
# Build LXC tarball
|
||||
nix build .#lxc-nix-builder
|
||||
|
||||
# Result location
|
||||
ls -lh result/tarball/nixos-*.tar.xz
|
||||
```
|
||||
|
||||
**Importing to Proxmox:**
|
||||
|
||||
```bash
|
||||
# Copy tarball to Proxmox host
|
||||
scp result/tarball/nixos-*.tar.xz root@proxmox:/var/lib/vz/template/cache/
|
||||
|
||||
# Create container from Proxmox CLI
|
||||
pct create 100 local:vztmpl/nixos-*.tar.xz \
|
||||
--hostname nix-builder \
|
||||
--memory 4096 \
|
||||
--cores 4 \
|
||||
--net0 name=eth0,bridge=vmbr0,ip=dhcp
|
||||
```
|
||||
|
||||
See [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) for detailed Proxmox deployment instructions.
|
||||
|
||||
### Proxmox VMA
|
||||
|
||||
Build Proxmox-specific VMA archives:
|
||||
|
||||
```bash
|
||||
# Build Proxmox VMA
|
||||
nix build .#proxmox-nix-builder
|
||||
|
||||
# Result location
|
||||
ls -lh result/
|
||||
```
|
||||
|
||||
## Remote Builders
|
||||
|
||||
Speed up builds by offloading to build servers.
|
||||
|
||||
### One-Time Remote Build
|
||||
|
||||
```bash
|
||||
nix build .#installer-iso-nix-laptop1 \
|
||||
--builders "ssh://engr-ugaif@nix-builder x86_64-linux"
|
||||
```
|
||||
|
||||
### Persistent Configuration
|
||||
|
||||
Add to `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`:
|
||||
|
||||
```conf
|
||||
builders = ssh://engr-ugaif@nix-builder x86_64-linux
|
||||
```
|
||||
|
||||
Then build normally:
|
||||
|
||||
```bash
|
||||
nix build .#installer-iso-nix-laptop1
|
||||
```
|
||||
|
||||
### SSH Key Setup
|
||||
|
||||
For remote builders, ensure SSH keys are configured:
|
||||
|
||||
```bash
|
||||
# Generate SSH key if needed
|
||||
ssh-keygen -t ed25519
|
||||
|
||||
# Copy to builder
|
||||
ssh-copy-id engr-ugaif@nix-builder
|
||||
|
||||
# Test connection
|
||||
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
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Errors
|
||||
|
||||
**Check configuration validity:**
|
||||
```bash
|
||||
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
|
||||
ugaif.sw.remoteBuild.enable = false;
|
||||
```
|
||||
|
||||
### Out of Disk Space
|
||||
|
||||
**Clean up Nix store:**
|
||||
```bash
|
||||
nix-collect-garbage -d
|
||||
nix store optimise
|
||||
```
|
||||
|
||||
**Check space:**
|
||||
```bash
|
||||
df -h /nix
|
||||
```
|
||||
|
||||
### ISO Won't Boot
|
||||
|
||||
**Verify ISO integrity:**
|
||||
```bash
|
||||
sha256sum result/iso/nixos-*.iso
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
**Try alternative boot mode:**
|
||||
- UEFI systems: Try legacy BIOS mode
|
||||
- Legacy BIOS: Try UEFI mode
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Main documentation
|
||||
- [INVENTORY.md](INVENTORY.md) - Host configuration guide
|
||||
- [installer/PROXMOX_LXC.md](../installer/PROXMOX_LXC.md) - Proxmox deployment guide
|
||||
355
docs/DEVELOPMENT.md
Normal file
355
docs/DEVELOPMENT.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# Development Guide
|
||||
|
||||
This guide covers development workflows for maintaining and extending the nixos-systems repository.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Testing Changes](#testing-changes)
|
||||
- [System Rebuilds](#system-rebuilds)
|
||||
- [Updating Dependencies](#updating-dependencies)
|
||||
- [Adding Packages](#adding-packages)
|
||||
- [Python Development](#python-development)
|
||||
- [Contributing](#contributing)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Testing Changes
|
||||
|
||||
Always test configuration changes before committing.
|
||||
|
||||
### Validate All Configurations
|
||||
|
||||
```bash
|
||||
# Check all configurations build correctly
|
||||
nix flake check
|
||||
|
||||
# Check with verbose error traces
|
||||
nix flake check --show-trace
|
||||
```
|
||||
|
||||
### Test Specific Host Build
|
||||
|
||||
```bash
|
||||
# Build a specific host's configuration
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
||||
|
||||
# Build installer for specific host
|
||||
nix build .#installer-iso-nix-laptop1
|
||||
```
|
||||
|
||||
### Test Local Changes
|
||||
|
||||
If you're on a NixOS system managed by this flake:
|
||||
|
||||
```bash
|
||||
# Test changes without committing (temporary, doesn't survive reboot)
|
||||
sudo nixos-rebuild test --flake .
|
||||
|
||||
# Apply and switch to new configuration
|
||||
sudo nixos-rebuild switch --flake .
|
||||
|
||||
# Build without switching
|
||||
sudo nixos-rebuild build --flake .
|
||||
```
|
||||
|
||||
## 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 github:UGA-Innovation-Factory/nixos-systems
|
||||
|
||||
# Use --impure for external user configurations with fetchGit
|
||||
sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems --impure
|
||||
|
||||
# Rebuild specific host from GitHub
|
||||
sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems#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 `ugaif.sw.extraPackages` in `inventory.nix`:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 2;
|
||||
overrides = {
|
||||
ugaif.sw.extraPackages = with pkgs; [
|
||||
vim
|
||||
docker
|
||||
kubernetes-helm
|
||||
];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### User-Specific Packages
|
||||
|
||||
Add to user's home-manager configuration in `users.nix` or external dotfiles:
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
homePackages = with pkgs; [
|
||||
ripgrep
|
||||
fd
|
||||
bat
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
### Search for Packages
|
||||
|
||||
```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
|
||||
ugaif.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 `ugaif.*` 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
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
# Show all available outputs
|
||||
nix flake show
|
||||
|
||||
# Evaluate specific option
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName
|
||||
|
||||
# List all hosts
|
||||
nix eval .#nixosConfigurations --apply builtins.attrNames
|
||||
|
||||
# Check flake metadata
|
||||
nix flake metadata
|
||||
|
||||
# Show evaluation trace
|
||||
nix eval --show-trace .#nixosConfigurations.nix-laptop1
|
||||
|
||||
# Build and enter debug shell
|
||||
nix develop
|
||||
|
||||
# Clean up old generations
|
||||
nix-collect-garbage -d
|
||||
|
||||
# Optimize Nix store
|
||||
nix store optimise
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Main documentation
|
||||
- [INVENTORY.md](INVENTORY.md) - Host inventory configuration
|
||||
- [BUILDING.md](BUILDING.md) - Building installation media
|
||||
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
|
||||
418
docs/EXTERNAL_MODULES.md
Normal file
418
docs/EXTERNAL_MODULES.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# External Configuration Modules
|
||||
|
||||
This guide explains how to use external modules for system and user configurations in nixos-systems.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [System Modules](#system-modules)
|
||||
- [User Modules](#user-modules)
|
||||
- [Fetch Methods](#fetch-methods)
|
||||
- [Templates](#templates)
|
||||
- [Integration Details](#integration-details)
|
||||
|
||||
## 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).
|
||||
|
||||
**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
|
||||
|
||||
## System Modules
|
||||
|
||||
External system modules provide complete NixOS configurations for hosts.
|
||||
|
||||
### Usage in inventory.nix
|
||||
|
||||
```nix
|
||||
nix-lxc = {
|
||||
devices = {
|
||||
# Traditional inline configuration
|
||||
"local-server" = {
|
||||
ugaif.users.admin.enable = true;
|
||||
services.nginx.enable = true;
|
||||
};
|
||||
|
||||
# External module from Git
|
||||
"remote-server" = builtins.fetchGit {
|
||||
url = "https://github.com/org/server-config";
|
||||
rev = "abc123..."; # Pin to specific commit
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### External Repository Structure
|
||||
|
||||
```
|
||||
server-config/
|
||||
├── default.nix # Required: NixOS module
|
||||
└── README.md # Optional: Documentation
|
||||
```
|
||||
|
||||
**default.nix:**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
# Your NixOS configuration
|
||||
services.nginx = {
|
||||
enable = true;
|
||||
virtualHosts."example.com" = {
|
||||
root = "/var/www";
|
||||
};
|
||||
};
|
||||
|
||||
# Use ugaif namespace options
|
||||
ugaif.users.admin.enable = true;
|
||||
ugaif.sw.type = "headless";
|
||||
}
|
||||
```
|
||||
|
||||
### What External Modules Receive
|
||||
|
||||
- **`inputs`** - All flake inputs (nixpkgs, home-manager, etc.)
|
||||
- **`config`** - Full NixOS configuration
|
||||
- **`lib`** - Nixpkgs library functions
|
||||
- **`pkgs`** - Package set
|
||||
|
||||
### Module Integration Order
|
||||
|
||||
When a host is built, modules are loaded 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`)
|
||||
|
||||
Later modules can override earlier ones using standard NixOS module precedence.
|
||||
|
||||
### Template
|
||||
|
||||
Create a new system module:
|
||||
|
||||
```bash
|
||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#system
|
||||
```
|
||||
|
||||
See [templates/system/](../templates/system/) for the complete template.
|
||||
|
||||
## User Modules
|
||||
|
||||
External user modules provide home-manager configurations (dotfiles, packages, programs).
|
||||
|
||||
### Usage in users.nix
|
||||
|
||||
```nix
|
||||
ugaif.users = {
|
||||
myuser = {
|
||||
description = "My Name";
|
||||
extraGroups = [ "wheel" "networkmanager" ];
|
||||
hashedPassword = "$6$...";
|
||||
|
||||
# External home-manager configuration
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/dotfiles";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### External Repository Structure
|
||||
|
||||
```
|
||||
dotfiles/
|
||||
├── home.nix # Required: Home-manager config
|
||||
├── nixos.nix # Optional: System-level config
|
||||
└── dotfiles/ # Optional: Actual dotfiles
|
||||
├── bashrc
|
||||
└── vimrc
|
||||
```
|
||||
|
||||
**home.nix (required):**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, osConfig, ... }:
|
||||
{
|
||||
# Home-manager configuration
|
||||
home.packages = with pkgs; [ vim git htop ];
|
||||
|
||||
programs.git = {
|
||||
enable = true;
|
||||
userName = "My Name";
|
||||
userEmail = "me@example.com";
|
||||
};
|
||||
|
||||
# Manage dotfiles
|
||||
home.file.".bashrc".source = ./dotfiles/bashrc;
|
||||
}
|
||||
```
|
||||
|
||||
**nixos.nix (optional):**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
# System-level configuration for this user
|
||||
users.users.myuser.extraGroups = [ "docker" ];
|
||||
environment.systemPackages = [ pkgs.docker ];
|
||||
}
|
||||
```
|
||||
|
||||
### What User Modules Receive
|
||||
|
||||
**In home.nix:**
|
||||
- **`inputs`** - Flake inputs (nixpkgs, home-manager, etc.)
|
||||
- **`config`** - Home-manager configuration
|
||||
- **`lib`** - Nixpkgs library functions
|
||||
- **`pkgs`** - Package set
|
||||
- **`osConfig`** - OS-level configuration (read-only)
|
||||
|
||||
**In nixos.nix:**
|
||||
- **`inputs`** - Flake inputs
|
||||
- **`config`** - NixOS configuration
|
||||
- **`lib`** - Nixpkgs library functions
|
||||
- **`pkgs`** - Package set
|
||||
|
||||
### User Options in users.nix
|
||||
|
||||
```nix
|
||||
username = {
|
||||
# Identity
|
||||
description = "Full Name";
|
||||
|
||||
# External configuration
|
||||
home = 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 ugaif.users.username.enable
|
||||
};
|
||||
```
|
||||
|
||||
### Template
|
||||
|
||||
Create a new user module:
|
||||
|
||||
```bash
|
||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#user
|
||||
```
|
||||
|
||||
See [templates/user/](../templates/user/) for the complete template.
|
||||
|
||||
## Fetch Methods
|
||||
|
||||
### Recommended: fetchGit with Revision
|
||||
|
||||
Pin to a specific commit for reproducibility:
|
||||
|
||||
```nix
|
||||
builtins.fetchGit {
|
||||
url = "https://github.com/user/repo";
|
||||
rev = "abc123def456..."; # Full commit hash (40 characters)
|
||||
ref = "main"; # Optional: branch name
|
||||
}
|
||||
```
|
||||
|
||||
**Finding the commit hash:**
|
||||
```bash
|
||||
# Latest commit on main branch
|
||||
git ls-remote https://github.com/user/repo main
|
||||
|
||||
# Or from a local clone
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
### 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)
|
||||
|
||||
Download specific release archives:
|
||||
|
||||
```nix
|
||||
builtins.fetchTarball {
|
||||
url = "https://github.com/user/repo/archive/v1.0.0.tar.gz";
|
||||
sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
|
||||
}
|
||||
```
|
||||
|
||||
**Get the hash:**
|
||||
```bash
|
||||
nix-prefetch-url --unpack https://github.com/user/repo/archive/v1.0.0.tar.gz
|
||||
```
|
||||
|
||||
### Local Path (For Testing)
|
||||
|
||||
Use local directories during development:
|
||||
|
||||
```nix
|
||||
/home/username/dev/my-config
|
||||
|
||||
# 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 github:UGA-Innovation-Factory/nixos-systems#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 github:UGA-Innovation-Factory/nixos-systems#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 `ugaif.*` namespace options.
|
||||
|
||||
### User Module Integration
|
||||
|
||||
External user modules are loaded separately for home-manager (`home.nix`) and NixOS (`nixos.nix` if it exists):
|
||||
|
||||
**Home-manager:**
|
||||
```nix
|
||||
import (externalHomePath + "/home.nix") { inherit inputs; }
|
||||
```
|
||||
|
||||
**NixOS (optional):**
|
||||
```nix
|
||||
import (externalHomePath + "/nixos.nix") { inherit inputs; }
|
||||
```
|
||||
|
||||
### Combining External and Local Config
|
||||
|
||||
You can mix external modules with local overrides:
|
||||
|
||||
```nix
|
||||
nix-lxc = {
|
||||
devices = {
|
||||
"server" = builtins.fetchGit {
|
||||
url = "https://github.com/org/base-config";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
overrides = {
|
||||
# Apply to all devices, including external ones
|
||||
ugaif.users.admin.enable = true;
|
||||
networking.firewall.allowedTCPPorts = [ 80 443 ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Minimal System Module
|
||||
|
||||
**default.nix:**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
ugaif.sw.type = "headless";
|
||||
services.nginx.enable = true;
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal User Module
|
||||
|
||||
**home.nix:**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
home.packages = with pkgs; [ vim git ];
|
||||
}
|
||||
```
|
||||
|
||||
### Full User Module with Dotfiles
|
||||
|
||||
```
|
||||
dotfiles/
|
||||
├── home.nix
|
||||
├── nixos.nix
|
||||
└── config/
|
||||
├── bashrc
|
||||
├── vimrc
|
||||
└── gitconfig
|
||||
```
|
||||
|
||||
**home.nix:**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
home.packages = with pkgs; [ ripgrep fd bat ];
|
||||
|
||||
home.file = {
|
||||
".bashrc".source = ./config/bashrc;
|
||||
".vimrc".source = ./config/vimrc;
|
||||
".gitconfig".source = ./config/gitconfig;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration guide
|
||||
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options reference
|
||||
- [templates/system/](../templates/system/) - System module template
|
||||
- [templates/user/](../templates/user/) - User module template
|
||||
- [README.md](../README.md) - Main documentation
|
||||
190
docs/INVENTORY.md
Normal file
190
docs/INVENTORY.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# Host Inventory Configuration
|
||||
|
||||
This guide explains how to configure hosts in `inventory.nix` to define your fleet of devices.
|
||||
|
||||
## 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)
|
||||
- [Examples](#examples)
|
||||
|
||||
## Understanding Inventory Structure
|
||||
|
||||
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.
|
||||
|
||||
## Hostname Generation Rules
|
||||
|
||||
- **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 `ugaif.host.useHostPrefix = false` to use suffix as full hostname
|
||||
|
||||
## Adding Hosts
|
||||
|
||||
### Method 1: Quick Count (Simplest)
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 5; # Creates: nix-laptop1, nix-laptop2, ..., nix-laptop5
|
||||
};
|
||||
```
|
||||
|
||||
### Method 2: Explicit Count with Overrides
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 5;
|
||||
overrides = {
|
||||
# Applied to ALL nix-laptop hosts
|
||||
ugaif.users.student.enable = true;
|
||||
ugaif.sw.extraPackages = with pkgs; [ vim git ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Method 3: Individual Device Configuration
|
||||
|
||||
```nix
|
||||
nix-surface = {
|
||||
devices = {
|
||||
"1".ugaif.sw.kioskUrl = "https://dashboard1.example.com";
|
||||
"2".ugaif.sw.kioskUrl = "https://dashboard2.example.com";
|
||||
"3".ugaif.sw.kioskUrl = "https://dashboard3.example.com";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Method 4: Mixed (Default Count + Custom Devices)
|
||||
|
||||
```nix
|
||||
nix-surface = {
|
||||
defaultCount = 2; # Creates nix-surface1, nix-surface2
|
||||
devices = {
|
||||
"special" = { # Creates nix-surface-special
|
||||
ugaif.sw.kioskUrl = "https://special-dashboard.example.com";
|
||||
};
|
||||
};
|
||||
overrides = {
|
||||
# Applied to all devices (including "special")
|
||||
ugaif.sw.kioskUrl = "https://default-dashboard.example.com";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Device Configuration Options
|
||||
|
||||
### Direct Configuration (Recommended)
|
||||
|
||||
Use any NixOS or `ugaif.*` option:
|
||||
|
||||
```nix
|
||||
"1" = {
|
||||
# UGAIF options
|
||||
ugaif.users.myuser.enable = true;
|
||||
ugaif.host.filesystem.swapSize = "64G";
|
||||
ugaif.sw.extraPackages = with pkgs; [ docker ];
|
||||
ugaif.sw.kioskUrl = "https://example.com";
|
||||
|
||||
# Standard NixOS options
|
||||
networking.firewall.enable = false;
|
||||
services.openssh.enable = true;
|
||||
time.timeZone = "America/New_York";
|
||||
};
|
||||
```
|
||||
|
||||
### Convenience: `ugaif.forUser`
|
||||
|
||||
Quick setup for single-user systems (especially WSL):
|
||||
|
||||
```nix
|
||||
nix-wsl = {
|
||||
devices = {
|
||||
"alice".ugaif.forUser = "alice-username";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
This automatically enables the user account.
|
||||
|
||||
### External System Configuration
|
||||
|
||||
For complex configurations, use external modules (see [EXTERNAL_MODULES.md](../EXTERNAL_MODULES.md)):
|
||||
|
||||
```nix
|
||||
nix-lxc = {
|
||||
devices = {
|
||||
"special-server" = builtins.fetchGit {
|
||||
url = "https://github.com/org/server-config";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple Lab Computers
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 10; # Creates nix-laptop1 through nix-laptop10
|
||||
overrides = {
|
||||
ugaif.users.student.enable = true;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Mixed Surface Tablets
|
||||
|
||||
```nix
|
||||
nix-surface = {
|
||||
defaultCount = 5; # nix-surface1 through nix-surface5 (default config)
|
||||
devices = {
|
||||
"admin" = { # nix-surface-admin (special config)
|
||||
ugaif.sw.type = "desktop"; # Full desktop instead of kiosk
|
||||
ugaif.users.admin.enable = true;
|
||||
};
|
||||
};
|
||||
overrides = {
|
||||
ugaif.sw.type = "tablet-kiosk";
|
||||
ugaif.sw.kioskUrl = "https://dashboard.factory.uga.edu";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### LXC Containers
|
||||
|
||||
```nix
|
||||
nix-lxc = {
|
||||
devices = {
|
||||
"nix-builder" = {
|
||||
ugaif.sw.type = "headless";
|
||||
};
|
||||
"webserver" = {
|
||||
ugaif.sw.type = "headless";
|
||||
services.nginx.enable = true;
|
||||
};
|
||||
};
|
||||
overrides = {
|
||||
ugaif.host.useHostPrefix = false; # Use exact device key as hostname
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### WSL Instances
|
||||
|
||||
```nix
|
||||
nix-wsl = {
|
||||
devices = {
|
||||
"alice".ugaif.forUser = "alice-uga";
|
||||
"bob".ugaif.forUser = "bob-uga";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User account management
|
||||
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External configuration modules
|
||||
- [Configuration Namespace Reference](NAMESPACE.md) - All `ugaif.*` options
|
||||
275
docs/NAMESPACE.md
Normal file
275
docs/NAMESPACE.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# Configuration Namespace Reference
|
||||
|
||||
All UGA Innovation Factory-specific options are under the `ugaif` namespace to avoid conflicts with standard NixOS options.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Host Configuration (`ugaif.host`)](#host-configuration-ugaifhost)
|
||||
- [Software Configuration (`ugaif.sw`)](#software-configuration-ugaifsw)
|
||||
- [User Management (`ugaif.users`)](#user-management-ugaifusers)
|
||||
- [System Configuration (`ugaif.system`)](#system-configuration-ugaifsystem)
|
||||
- [Convenience Options](#convenience-options)
|
||||
|
||||
## Host Configuration (`ugaif.host`)
|
||||
|
||||
Hardware and host-specific settings.
|
||||
|
||||
### `ugaif.host.filesystem`
|
||||
|
||||
Disk and storage configuration.
|
||||
|
||||
**Options:**
|
||||
- `ugaif.host.filesystem.device` - Boot disk device (default: `/dev/sda`)
|
||||
- `ugaif.host.filesystem.swapSize` - Swap file size (default: `"32G"`)
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.host.filesystem = {
|
||||
device = "/dev/nvme0n1";
|
||||
swapSize = "64G";
|
||||
};
|
||||
```
|
||||
|
||||
### `ugaif.host.buildMethods`
|
||||
|
||||
List of supported build artifact types for this host.
|
||||
|
||||
**Type:** List of strings
|
||||
|
||||
**Options:** `"installer-iso"`, `"iso"`, `"ipxe"`, `"lxc"`, `"proxmox"`
|
||||
|
||||
**Default:** `["installer-iso"]`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.host.buildMethods = [ "lxc" "proxmox" ];
|
||||
```
|
||||
|
||||
### `ugaif.host.useHostPrefix`
|
||||
|
||||
Whether to prepend the host type prefix to the hostname (used in inventory generation).
|
||||
|
||||
**Type:** Boolean
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.host.useHostPrefix = false; # "builder" instead of "nix-lxc-builder"
|
||||
```
|
||||
|
||||
### `ugaif.host.wsl`
|
||||
|
||||
WSL-specific configuration options.
|
||||
|
||||
**Options:**
|
||||
- `ugaif.host.wsl.user` - Default WSL user for this instance
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.host.wsl.user = "myusername";
|
||||
```
|
||||
|
||||
## Software Configuration (`ugaif.sw`)
|
||||
|
||||
System software and application configuration.
|
||||
|
||||
### `ugaif.sw.enable`
|
||||
|
||||
Enable the software configuration module.
|
||||
|
||||
**Type:** Boolean
|
||||
|
||||
**Default:** `true`
|
||||
|
||||
### `ugaif.sw.type`
|
||||
|
||||
System type that determines the software profile.
|
||||
|
||||
**Type:** Enum
|
||||
|
||||
**Options:**
|
||||
- `"desktop"` - Full desktop environment (GNOME)
|
||||
- `"tablet-kiosk"` - Surface tablets with kiosk mode browser
|
||||
- `"stateless-kiosk"` - Diskless PXE boot kiosks
|
||||
- `"headless"` - Servers and containers without GUI
|
||||
|
||||
**Default:** `"desktop"`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.type = "headless";
|
||||
```
|
||||
|
||||
### `ugaif.sw.kioskUrl`
|
||||
|
||||
URL to display in kiosk mode browsers (for `tablet-kiosk` and `stateless-kiosk` types).
|
||||
|
||||
**Type:** String
|
||||
|
||||
**Default:** `"https://ha.factory.uga.edu"`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.kioskUrl = "https://dashboard.example.com";
|
||||
```
|
||||
|
||||
### `ugaif.sw.python`
|
||||
|
||||
Python development tools configuration.
|
||||
|
||||
**Options:**
|
||||
- `ugaif.sw.python.enable` - Enable Python tools (pixi, uv) (default: `true`)
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.python.enable = true;
|
||||
```
|
||||
|
||||
### `ugaif.sw.remoteBuild`
|
||||
|
||||
Remote build server configuration for offloading builds.
|
||||
|
||||
**Options:**
|
||||
- `ugaif.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets)
|
||||
- `ugaif.sw.remoteBuild.hosts` - List of build server hostnames
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.remoteBuild = {
|
||||
enable = true;
|
||||
hosts = [ "nix-builder" "nix-builder2" ];
|
||||
};
|
||||
```
|
||||
|
||||
### `ugaif.sw.extraPackages`
|
||||
|
||||
Additional system packages to install beyond the type defaults.
|
||||
|
||||
**Type:** List of packages
|
||||
|
||||
**Default:** `[]`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.extraPackages = with pkgs; [
|
||||
vim
|
||||
htop
|
||||
docker
|
||||
];
|
||||
```
|
||||
|
||||
### `ugaif.sw.excludePackages`
|
||||
|
||||
Packages to exclude from the default list for this system type.
|
||||
|
||||
**Type:** List of packages
|
||||
|
||||
**Default:** `[]`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.sw.excludePackages = with pkgs; [
|
||||
firefox # Remove Firefox from default desktop packages
|
||||
];
|
||||
```
|
||||
|
||||
## User Management (`ugaif.users`)
|
||||
|
||||
User account configuration and management.
|
||||
|
||||
### `ugaif.users.<username>.enable`
|
||||
|
||||
Enable a specific user account on this system.
|
||||
|
||||
**Type:** Boolean
|
||||
|
||||
**Default:** `false` (except `root` and `engr-ugaif` which default to `true`)
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.users = {
|
||||
myuser.enable = true;
|
||||
student.enable = true;
|
||||
};
|
||||
```
|
||||
|
||||
### User Account Options
|
||||
|
||||
Each user in `users.nix` can be configured with:
|
||||
|
||||
```nix
|
||||
ugaif.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
|
||||
homePackages = with pkgs; [ ... ]; # User packages
|
||||
useZshTheme = true; # Use system Zsh theme
|
||||
useNvimPlugins = true; # Use system Neovim config
|
||||
|
||||
# External home-manager configuration (optional)
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/dotfiles";
|
||||
rev = "abc123...";
|
||||
};
|
||||
|
||||
enable = false; # Enable per-system in inventory.nix
|
||||
};
|
||||
```
|
||||
|
||||
## System Configuration (`ugaif.system`)
|
||||
|
||||
System-wide settings and services.
|
||||
|
||||
### `ugaif.system.gc`
|
||||
|
||||
Automatic garbage collection configuration.
|
||||
|
||||
**Options:**
|
||||
- `ugaif.system.gc.enable` - Enable automatic garbage collection (default: `true`)
|
||||
- `ugaif.system.gc.frequency` - How often to run (default: `"weekly"`)
|
||||
- `ugaif.system.gc.retentionDays` - Days to keep old generations (default: `30`)
|
||||
- `ugaif.system.gc.optimise` - Optimize Nix store automatically (default: `true`)
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.system.gc = {
|
||||
enable = true;
|
||||
frequency = "daily";
|
||||
retentionDays = 14;
|
||||
optimise = true;
|
||||
};
|
||||
```
|
||||
|
||||
## Convenience Options
|
||||
|
||||
### `ugaif.forUser`
|
||||
|
||||
Quick setup option that enables a user account in one line.
|
||||
|
||||
**Type:** String (username) or null
|
||||
|
||||
**Default:** `null`
|
||||
|
||||
**Example:**
|
||||
```nix
|
||||
ugaif.forUser = "myusername"; # Equivalent to ugaif.users.myusername.enable = true
|
||||
```
|
||||
|
||||
**Usage in inventory.nix:**
|
||||
```nix
|
||||
nix-wsl = {
|
||||
devices = {
|
||||
"alice".ugaif.forUser = "alice-uga";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [INVENTORY.md](INVENTORY.md) - Host inventory configuration guide
|
||||
- [USER_CONFIGURATION.md](../USER_CONFIGURATION.md) - User management guide
|
||||
- [README.md](../README.md) - Main documentation
|
||||
486
docs/USER_CONFIGURATION.md
Normal file
486
docs/USER_CONFIGURATION.md
Normal file
@@ -0,0 +1,486 @@
|
||||
# User Configuration Guide
|
||||
|
||||
Complete guide to managing user accounts in nixos-systems.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Quick Start](#quick-start)
|
||||
- [User Account Options](#user-account-options)
|
||||
- [External User Configurations](#external-user-configurations)
|
||||
- [Enabling Users on Hosts](#enabling-users-on-hosts)
|
||||
- [Password Management](#password-management)
|
||||
- [SSH Keys](#ssh-keys)
|
||||
- [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`.
|
||||
|
||||
**Default enabled users:**
|
||||
- `root` - System administrator
|
||||
- `engr-ugaif` - Innovation Factory default account
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Define User in users.nix
|
||||
|
||||
```nix
|
||||
ugaif.users = {
|
||||
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"
|
||||
];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Enable User on Hosts
|
||||
|
||||
In `inventory.nix`:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 2;
|
||||
overrides.ugaif.users.myuser.enable = true; # Enables on all nix-laptop hosts
|
||||
};
|
||||
|
||||
# Or for specific devices
|
||||
nix-desktop = {
|
||||
devices = {
|
||||
"1".ugaif.users.myuser.enable = true;
|
||||
"2".ugaif.users.otheruser.enable = true;
|
||||
};
|
||||
};
|
||||
|
||||
# Or use convenience option
|
||||
nix-wsl = {
|
||||
devices."alice".ugaif.forUser = "alice-user"; # Automatically enables user
|
||||
};
|
||||
```
|
||||
|
||||
## User Account Options
|
||||
|
||||
Each user in `users.nix` can have the following options:
|
||||
|
||||
```nix
|
||||
username = {
|
||||
# === Identity ===
|
||||
description = "Full Name"; # User's full name
|
||||
|
||||
# === 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
|
||||
];
|
||||
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"
|
||||
];
|
||||
|
||||
# === Home Configuration ===
|
||||
home = builtins.fetchGit { ... }; # External home-manager config (see below)
|
||||
|
||||
# OR (if not using external config):
|
||||
homePackages = with pkgs; [ # User packages
|
||||
ripgrep
|
||||
fd
|
||||
bat
|
||||
];
|
||||
extraImports = [ ./my-module.nix ]; # Additional home-manager modules
|
||||
|
||||
# === Theme Integration ===
|
||||
useZshTheme = true; # Apply system Zsh theme (default: true)
|
||||
useNvimPlugins = true; # Apply system Neovim config (default: true)
|
||||
|
||||
# === System Enablement ===
|
||||
enable = false; # Enable on this system (set in inventory.nix)
|
||||
};
|
||||
```
|
||||
|
||||
## External User Configurations
|
||||
|
||||
Users can maintain their dotfiles and home-manager configuration in separate Git repositories.
|
||||
|
||||
### Basic External Configuration
|
||||
|
||||
In `users.nix`:
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
description = "My Name";
|
||||
extraGroups = [ "wheel" ];
|
||||
hashedPassword = "$6$...";
|
||||
|
||||
# Point to external dotfiles repository
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/dotfiles";
|
||||
rev = "abc123..."; # Pin to specific commit
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### External Repository Structure
|
||||
|
||||
```
|
||||
dotfiles/
|
||||
├── home.nix # Required: Home-manager configuration
|
||||
├── nixos.nix # Optional: System-level configuration
|
||||
└── config/ # Optional: Your dotfiles
|
||||
├── bashrc
|
||||
├── vimrc
|
||||
└── ...
|
||||
```
|
||||
|
||||
**home.nix (required):**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, osConfig, ... }:
|
||||
{
|
||||
home.packages = with pkgs; [ vim git htop ];
|
||||
|
||||
programs.git = {
|
||||
enable = true;
|
||||
userName = "My Name";
|
||||
userEmail = "me@example.com";
|
||||
};
|
||||
|
||||
home.file.".bashrc".source = ./config/bashrc;
|
||||
}
|
||||
```
|
||||
|
||||
**nixos.nix (optional):**
|
||||
```nix
|
||||
{ inputs, ... }:
|
||||
{ config, lib, pkgs, ... }:
|
||||
{
|
||||
# System-level configuration
|
||||
users.users.myusername.extraGroups = [ "docker" ];
|
||||
environment.systemPackages = [ pkgs.docker ];
|
||||
}
|
||||
```
|
||||
|
||||
### What External Modules Receive
|
||||
|
||||
**In home.nix:**
|
||||
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
|
||||
- `config` - Home-manager configuration
|
||||
- `lib` - Nixpkgs library functions
|
||||
- `pkgs` - Package set
|
||||
- `osConfig` - OS-level configuration (read-only)
|
||||
|
||||
**In nixos.nix:**
|
||||
- `inputs` - Flake inputs
|
||||
- `config` - NixOS configuration
|
||||
- `lib` - Nixpkgs library functions
|
||||
- `pkgs` - Package set
|
||||
|
||||
### Alternative Configuration Methods
|
||||
|
||||
**Local path (for testing):**
|
||||
```nix
|
||||
home = /home/username/dev/dotfiles;
|
||||
```
|
||||
|
||||
**Inline configuration:**
|
||||
```nix
|
||||
home = {
|
||||
home.packages = with pkgs; [ vim ];
|
||||
programs.git.enable = true;
|
||||
};
|
||||
```
|
||||
|
||||
**No external config (legacy):**
|
||||
```nix
|
||||
homePackages = with pkgs; [ vim git ];
|
||||
# home = null; # Default
|
||||
```
|
||||
|
||||
### Create User Template
|
||||
|
||||
```bash
|
||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#user
|
||||
```
|
||||
|
||||
See [templates/user/README.md](../templates/user/README.md) for complete template.
|
||||
|
||||
## Enabling Users on Hosts
|
||||
|
||||
Users must be explicitly enabled on each host in `inventory.nix`.
|
||||
|
||||
### Method 1: Enable in Overrides (All Devices)
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 5;
|
||||
overrides = {
|
||||
ugaif.users.student.enable = true; # All 5 laptops get this user
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Method 2: Enable per Device
|
||||
|
||||
```nix
|
||||
nix-desktop = {
|
||||
devices = {
|
||||
"1".ugaif.users.alice.enable = true;
|
||||
"2".ugaif.users.bob.enable = true;
|
||||
"3" = {
|
||||
ugaif.users.alice.enable = true;
|
||||
ugaif.users.bob.enable = true;
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Method 3: Convenience Option (ugaif.forUser)
|
||||
|
||||
Quick setup for single-user systems:
|
||||
|
||||
```nix
|
||||
nix-wsl = {
|
||||
devices = {
|
||||
"alice".ugaif.forUser = "alice-user"; # Automatically enables alice-user
|
||||
"bob".ugaif.forUser = "bob-user";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
This is equivalent to `ugaif.users.alice-user.enable = true`.
|
||||
|
||||
## Password Management
|
||||
|
||||
### Generate Hashed Password
|
||||
|
||||
```bash
|
||||
mkpasswd -m sha-512
|
||||
# Enter password when prompted
|
||||
# Copy the output hash
|
||||
```
|
||||
|
||||
### In users.nix
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
hashedPassword = "$6$rounds=656000$..."; # Paste hash here
|
||||
};
|
||||
```
|
||||
|
||||
### Disable Password Login
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
hashedPassword = "!"; # Locks password, SSH key only
|
||||
opensshKeys = [ "ssh-ed25519 ..." ];
|
||||
};
|
||||
```
|
||||
|
||||
### Change Password Later
|
||||
|
||||
On the system:
|
||||
```bash
|
||||
sudo passwd myuser
|
||||
```
|
||||
|
||||
Or regenerate hash and update `users.nix`.
|
||||
|
||||
## SSH Keys
|
||||
|
||||
### Adding SSH Keys
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
opensshKeys = [
|
||||
"ssh-ed25519 AAAAC3Nza... user@laptop"
|
||||
"ssh-rsa AAAAB3NzaC1... user@desktop"
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
### Generate SSH Key
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -C "user@hostname"
|
||||
cat ~/.ssh/id_ed25519.pub # Copy this
|
||||
```
|
||||
|
||||
### Multiple Keys
|
||||
|
||||
Users can have multiple SSH keys for different machines:
|
||||
|
||||
```nix
|
||||
opensshKeys = [
|
||||
"ssh-ed25519 ... user@work-laptop"
|
||||
"ssh-ed25519 ... user@home-desktop"
|
||||
"ssh-ed25519 ... user@tablet"
|
||||
];
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic User
|
||||
|
||||
```nix
|
||||
student = {
|
||||
description = "Student Account";
|
||||
extraGroups = [ "networkmanager" ];
|
||||
shell = pkgs.bash;
|
||||
hashedPassword = "$6$...";
|
||||
};
|
||||
```
|
||||
|
||||
### Admin User with SSH
|
||||
|
||||
```nix
|
||||
admin = {
|
||||
description = "System Administrator";
|
||||
extraGroups = [ "wheel" "networkmanager" "docker" ];
|
||||
shell = pkgs.zsh;
|
||||
hashedPassword = "$6$...";
|
||||
opensshKeys = [
|
||||
"ssh-ed25519 AAAA... admin@laptop"
|
||||
];
|
||||
};
|
||||
```
|
||||
|
||||
### User with External Dotfiles
|
||||
|
||||
```nix
|
||||
developer = {
|
||||
description = "Developer";
|
||||
extraGroups = [ "wheel" "docker" ];
|
||||
shell = pkgs.zsh;
|
||||
hashedPassword = "$6$...";
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/dotfiles";
|
||||
rev = "abc123def456...";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### WSL User
|
||||
|
||||
```nix
|
||||
wsl-user = {
|
||||
description = "WSL User";
|
||||
extraGroups = [ "wheel" ];
|
||||
shell = pkgs.zsh;
|
||||
hashedPassword = "$6$...";
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/dotfiles";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Enable in inventory.nix:
|
||||
```nix
|
||||
nix-wsl = {
|
||||
devices."my-wsl".ugaif.forUser = "wsl-user";
|
||||
};
|
||||
```
|
||||
|
||||
### User Without System Themes
|
||||
|
||||
For users who want complete control over their shell/editor:
|
||||
|
||||
```nix
|
||||
poweruser = {
|
||||
description = "Power User";
|
||||
extraGroups = [ "wheel" ];
|
||||
shell = pkgs.zsh;
|
||||
hashedPassword = "$6$...";
|
||||
useZshTheme = false; # Don't apply system theme
|
||||
useNvimPlugins = false; # Don't apply system nvim config
|
||||
home = builtins.fetchGit {
|
||||
url = "https://github.com/username/custom-dotfiles";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Theme Integration
|
||||
|
||||
### System Zsh Theme
|
||||
|
||||
When `useZshTheme = true` (default), the system applies:
|
||||
- Oh My Posh with custom theme
|
||||
- History substring search
|
||||
- Vi mode (for non-root users)
|
||||
- Zsh plugins (zplug)
|
||||
|
||||
Disable if you want full control in your dotfiles.
|
||||
|
||||
### System Neovim Config
|
||||
|
||||
When `useNvimPlugins = true` (default), the system applies:
|
||||
- LazyVim distribution
|
||||
- TreeSitter parsers
|
||||
- Language servers
|
||||
|
||||
Disable if you want to configure Neovim yourself.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### User Can't Login
|
||||
|
||||
**Check if enabled on host:**
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.ugaif.users.myuser.enable
|
||||
```
|
||||
|
||||
**Check if user exists:**
|
||||
```bash
|
||||
# On the system
|
||||
id myuser
|
||||
```
|
||||
|
||||
### SSH Key Not Working
|
||||
|
||||
**Check key in configuration:**
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.users.users.myuser.openssh.authorizedKeys.keys
|
||||
```
|
||||
|
||||
**Verify key format:**
|
||||
- Should start with `ssh-ed25519`, `ssh-rsa`, or `ssh-dss`
|
||||
- Should be all on one line
|
||||
- Should end with comment (optional)
|
||||
|
||||
### External Config Not Loading
|
||||
|
||||
**Check repository access:**
|
||||
```bash
|
||||
git ls-remote https://github.com/username/dotfiles
|
||||
```
|
||||
|
||||
**Verify structure:**
|
||||
- Must have `home.nix` at repository root
|
||||
- `nixos.nix` is optional
|
||||
- Check file permissions
|
||||
|
||||
**Test with local path first:**
|
||||
```nix
|
||||
home = /path/to/local/dotfiles;
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [docs/EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External module guide
|
||||
- [docs/INVENTORY.md](INVENTORY.md) - Host configuration
|
||||
- [docs/NAMESPACE.md](NAMESPACE.md) - Configuration options
|
||||
- [templates/user/](../templates/user/) - User module template
|
||||
- [README.md](../README.md) - Main documentation
|
||||
Reference in New Issue
Block a user