documentation overhaul
This commit is contained in:
Hunter Halloran
@@ -1,109 +0,0 @@
|
|||||||
# External Module Support Implementation
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
Modified `nixos-systems` to support external system configurations via Nix modules instead of flakes. Device configurations can now point to URLs using `builtins.fetchGit`, `builtins.fetchTarball`, or local paths.
|
|
||||||
|
|
||||||
## Changes Made
|
|
||||||
|
|
||||||
### 1. `inventory.nix`
|
|
||||||
- Added documentation for external module syntax
|
|
||||||
- Added comprehensive examples showing different fetch methods
|
|
||||||
- Demonstrated usage: `devices."hostname" = builtins.fetchGit { url = "..."; rev = "..."; }`
|
|
||||||
|
|
||||||
### 2. `hosts/default.nix`
|
|
||||||
- Modified `mkHost` function to accept `externalModulePath` parameter
|
|
||||||
- Added logic to import and integrate external modules into the module list
|
|
||||||
- Updated device processing to detect path/derivation types (from fetchGit/fetchTarball)
|
|
||||||
- External modules are imported with `{ inputs; }` parameter, receiving same flake inputs
|
|
||||||
- External modules are merged alongside other configuration modules
|
|
||||||
|
|
||||||
### 3. `system-module-template/`
|
|
||||||
- Created `default.nix` template showing proper module structure
|
|
||||||
- Created `README.md` with usage instructions and examples
|
|
||||||
- Documented how external modules integrate with nixos-systems
|
|
||||||
|
|
||||||
## How It Works
|
|
||||||
|
|
||||||
### In inventory.nix:
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
"my-type" = {
|
|
||||||
devices = {
|
|
||||||
# Option 1: Traditional config attrset
|
|
||||||
"local-host" = {
|
|
||||||
extraUsers = [ "user1" ];
|
|
||||||
# ... normal NixOS config
|
|
||||||
};
|
|
||||||
|
|
||||||
# Option 2: External module from Git
|
|
||||||
"remote-host" = builtins.fetchGit {
|
|
||||||
url = "https://github.com/org/config";
|
|
||||||
rev = "abc123...";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Detection Logic:
|
|
||||||
The system detects if a device value is:
|
|
||||||
1. A path (`builtins.isPath`)
|
|
||||||
2. A string starting with `/` (absolute path)
|
|
||||||
3. A derivation (`lib.isDerivation`)
|
|
||||||
|
|
||||||
If any of these are true, it treats it as an external module path.
|
|
||||||
|
|
||||||
### Module Import:
|
|
||||||
External modules are imported as:
|
|
||||||
```nix
|
|
||||||
import externalModulePath { inherit inputs; }
|
|
||||||
```
|
|
||||||
|
|
||||||
They receive the same flake inputs and can use all available modules and packages.
|
|
||||||
|
|
||||||
### Integration Order:
|
|
||||||
1. User flake modules (from users.nix)
|
|
||||||
2. Host type module (from hosts/types/)
|
|
||||||
3. Config override module
|
|
||||||
4. Hostname assignment
|
|
||||||
5. External flake module (if flakeUrl specified in config)
|
|
||||||
6. External path module (if fetchGit/fetchurl/path detected)
|
|
||||||
|
|
||||||
## Benefits
|
|
||||||
|
|
||||||
- **Separation**: Keep system configs in separate repos
|
|
||||||
- **Reusability**: Share configs across multiple deployments
|
|
||||||
- **Versioning**: Pin to specific commits for reproducibility
|
|
||||||
- **Flexibility**: Mix external modules with local overrides
|
|
||||||
- **Compatibility**: Works with all existing build methods (ISO, LXC, Proxmox)
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
All existing configurations continue to work:
|
|
||||||
```bash
|
|
||||||
nix flake check # Passes ✓
|
|
||||||
nix eval .#nixosConfigurations.nix-desktop1.config.networking.hostName # Works ✓
|
|
||||||
```
|
|
||||||
|
|
||||||
## Example External Module Repository Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
my-server-config/
|
|
||||||
├── default.nix # Main module (required)
|
|
||||||
├── README.md # Documentation
|
|
||||||
└── custom-service.nix # Additional modules (optional)
|
|
||||||
```
|
|
||||||
|
|
||||||
The `default.nix` must export a NixOS module:
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
|
|
||||||
{
|
|
||||||
config = {
|
|
||||||
# Your configuration here
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
700
README.md
700
README.md
@@ -1,118 +1,105 @@
|
|||||||
# UGA Innovation Factory - NixOS Systems
|
# UGA Innovation Factory - NixOS Systems
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
## Table of Contents
|
## Documentation
|
||||||
|
|
||||||
- [Quick Start](#quick-start)
|
- **[Quick Start](#quick-start)** - Get started in 5 minutes
|
||||||
- [Repository Structure](#repository-structure)
|
- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Configure hosts and fleet inventory
|
||||||
- [Configuration Namespace](#configuration-namespace)
|
- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - Configuration options reference (`ugaif.*`)
|
||||||
- [User Management](#user-management)
|
- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User account management
|
||||||
- [Host Configuration](#host-configuration)
|
- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External configuration modules
|
||||||
- [External Modules](#external-modules)
|
- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs and container images
|
||||||
- [Building Artifacts](#building-artifacts)
|
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development and testing workflow
|
||||||
- [Development](#development)
|
|
||||||
- [Troubleshooting](#troubleshooting)
|
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### For End Users: Updating Your System
|
### For End Users
|
||||||
|
|
||||||
Update your system to the latest configuration from GitHub:
|
Update your system to the latest configuration:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
update-system
|
update-system
|
||||||
```
|
```
|
||||||
|
|
||||||
This command automatically:
|
This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds.
|
||||||
- Fetches the latest configuration
|
|
||||||
- Rebuilds your system
|
|
||||||
- Uses remote builders on Surface tablets to speed up builds
|
|
||||||
|
|
||||||
**Note:** If you use external user configurations (personal dotfiles), run `sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems --impure` instead.
|
**Note:** If you use external user configurations (personal dotfiles), run:
|
||||||
|
```bash
|
||||||
|
sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems --impure
|
||||||
|
```
|
||||||
|
|
||||||
### For Administrators: Applying Configuration Changes
|
### For Administrators
|
||||||
|
|
||||||
1. Make changes to configuration files
|
```bash
|
||||||
2. Test the configuration builds:
|
# 1. Make changes to configuration files
|
||||||
```bash
|
vim inventory.nix
|
||||||
nix flake check
|
|
||||||
```
|
# 2. Test configuration
|
||||||
3. Commit and push changes:
|
nix flake check
|
||||||
```bash
|
|
||||||
git add .
|
# 3. Format code
|
||||||
git commit -m "Description of changes"
|
nix fmt
|
||||||
git push
|
|
||||||
```
|
# 4. Commit and push
|
||||||
4. Users can now run `update-system` to get the changes
|
git add .
|
||||||
|
git commit -m "Description of changes"
|
||||||
|
git push
|
||||||
|
```
|
||||||
|
|
||||||
|
Users can now run `update-system` to get the changes.
|
||||||
|
|
||||||
|
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.**
|
||||||
|
|
||||||
## Repository Structure
|
## Repository Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
nixos-systems/
|
nixos-systems/
|
||||||
├── flake.nix # Flake entry point with inputs/outputs
|
├── flake.nix # Flake entry point
|
||||||
├── inventory.nix # Fleet inventory (hosts, types, counts)
|
├── inventory.nix # Fleet inventory - Define hosts here
|
||||||
├── users.nix # User account definitions
|
├── users.nix # User accounts - Define users here
|
||||||
├── hosts/ # Host generation logic and hardware types
|
├── hosts/ # Host generation logic
|
||||||
│ ├── default.nix # Core host generation functions
|
│ ├── types/ # Hardware types (desktop, laptop, surface, lxc, wsl, ephemeral)
|
||||||
│ ├── types/ # Hardware type definitions
|
│ └── ...
|
||||||
│ │ ├── nix-desktop.nix
|
|
||||||
│ │ ├── nix-laptop.nix
|
|
||||||
│ │ ├── nix-surface.nix
|
|
||||||
│ │ ├── nix-lxc.nix
|
|
||||||
│ │ ├── nix-wsl.nix
|
|
||||||
│ │ └── nix-ephemeral.nix
|
|
||||||
│ └── user-config.nix # User configuration integration
|
|
||||||
├── sw/ # Software configurations by system type
|
├── sw/ # Software configurations by system type
|
||||||
│ ├── desktop/ # Desktop system software
|
│ ├── desktop/ # Full desktop environment
|
||||||
│ ├── tablet-kiosk/ # Surface tablet kiosk mode
|
│ ├── tablet-kiosk/ # Surface kiosk mode
|
||||||
│ ├── stateless-kiosk/# Stateless kiosk systems
|
│ ├── stateless-kiosk/# Diskless PXE kiosks
|
||||||
│ ├── headless/ # Headless server systems
|
│ ├── headless/ # Servers and containers
|
||||||
│ ├── ghostty.nix # Ghostty terminal emulator
|
│ └── ...
|
||||||
│ ├── nvim.nix # Neovim configuration
|
├── installer/ # ISO and container builds
|
||||||
│ ├── python.nix # Python development tools
|
|
||||||
│ ├── theme.nix # UI theme configuration
|
|
||||||
│ └── updater.nix # System update service
|
|
||||||
├── installer/ # Build artifact generation
|
|
||||||
│ ├── artifacts.nix # ISO, LXC, Proxmox builds
|
|
||||||
│ ├── auto-install.nix # Automated installer
|
|
||||||
│ └── modules.nix # Exported modules
|
|
||||||
├── templates/ # Templates for external configs
|
├── templates/ # Templates for external configs
|
||||||
│ ├── system/ # System configuration template
|
│ ├── system/ # System configuration template
|
||||||
│ └── user/ # User 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.)
|
└── assets/ # Assets (Plymouth theme, etc.)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration Namespace
|
## Configuration Overview
|
||||||
|
|
||||||
All UGA Innovation Factory-specific options are under the `ugaif` namespace:
|
All Innovation Factory options use the `ugaif.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference.
|
||||||
|
|
||||||
### `ugaif.host` - Hardware Configuration
|
**Quick examples:**
|
||||||
- **`ugaif.host.filesystem`**: Disk device and swap size settings
|
|
||||||
- `ugaif.host.filesystem.device` - Boot disk device (default: `/dev/sda`)
|
|
||||||
- `ugaif.host.filesystem.swapSize` - Swap file size (default: `"32G"`)
|
|
||||||
- **`ugaif.host.buildMethods`**: List of supported artifact types (`["iso"]`, `["lxc", "proxmox"]`, etc.)
|
|
||||||
- **`ugaif.host.useHostPrefix`**: Whether to prepend type prefix to hostname (default: `true`)
|
|
||||||
- **`ugaif.host.wsl`**: WSL-specific configuration
|
|
||||||
- `ugaif.host.wsl.user` - Default WSL user
|
|
||||||
|
|
||||||
### `ugaif.sw` - Software Configuration
|
```nix
|
||||||
- **`ugaif.sw.enable`**: Enable software configuration module (default: `true`)
|
# Host configuration
|
||||||
- **`ugaif.sw.type`**: System type - `"desktop"`, `"tablet-kiosk"`, `"stateless-kiosk"`, or `"headless"`
|
ugaif.host.filesystem.device = "/dev/nvme0n1";
|
||||||
- **`ugaif.sw.kioskUrl`**: URL for kiosk mode browsers
|
ugaif.host.filesystem.swapSize = "64G";
|
||||||
- **`ugaif.sw.python`**: Python development tools configuration
|
|
||||||
- `ugaif.sw.python.enable` - Enable Python tools (pixi, uv)
|
|
||||||
- **`ugaif.sw.remoteBuild`**: Remote build configuration
|
|
||||||
- `ugaif.sw.remoteBuild.enable` - Use remote builders (default: enabled on tablets)
|
|
||||||
- `ugaif.sw.remoteBuild.hosts` - List of build servers
|
|
||||||
- **`ugaif.sw.extraPackages`**: Additional system packages to install
|
|
||||||
|
|
||||||
### `ugaif.users` - User Management
|
# Software configuration
|
||||||
- **`ugaif.users.accounts`**: Attrset of user definitions with account settings
|
ugaif.sw.type = "desktop"; # or "headless", "tablet-kiosk"
|
||||||
- **`ugaif.users.enabledUsers`**: List of users to enable on this system (default: `["root", "engr-ugaif"]`)
|
ugaif.sw.extraPackages = with pkgs; [ vim docker ];
|
||||||
- **`ugaif.forUser`**: Convenience option to set up a system for a specific user (sets `enabledUsers` and `wslUser`)
|
|
||||||
|
|
||||||
### Prerequisites
|
# User management
|
||||||
|
ugaif.users.myuser.enable = true;
|
||||||
|
ugaif.forUser = "myuser"; # Convenience shortcut
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
To work with this repository, install Nix with flakes support:
|
To work with this repository, install Nix with flakes support:
|
||||||
|
|
||||||
@@ -120,538 +107,157 @@ To work with this repository, install Nix with flakes support:
|
|||||||
# Recommended: Determinate Systems installer (includes flakes)
|
# Recommended: Determinate Systems installer (includes flakes)
|
||||||
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
|
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
|
||||||
|
|
||||||
# Alternative: Official installer (requires enabling flakes)
|
# Alternative: Official installer (requires enabling flakes manually)
|
||||||
sh <(curl -L https://nixos.org/nix/install) --daemon
|
sh <(curl -L https://nixos.org/nix/install) --daemon
|
||||||
```
|
```
|
||||||
|
|
||||||
## User Management
|
## Common Tasks
|
||||||
|
|
||||||
### Understanding User Configuration
|
|
||||||
|
|
||||||
Users are defined in `users.nix` but are **not enabled by default** on all systems. Each system must explicitly enable users via `ugaif.users.enabledUsers` in `inventory.nix`.
|
|
||||||
|
|
||||||
**Default enabled users on all systems:**
|
|
||||||
- `root` - System administrator
|
|
||||||
- `engr-ugaif` - Innovation Factory default account
|
|
||||||
|
|
||||||
### Adding a New User
|
### Adding a New User
|
||||||
|
|
||||||
1. Edit `users.nix` and add a new user:
|
1. Edit `users.nix`:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
ugaif.users.accounts = {
|
myuser = {
|
||||||
# ... existing users ...
|
description = "My Full Name";
|
||||||
|
extraGroups = [ "wheel" "networkmanager" ];
|
||||||
myuser = {
|
shell = pkgs.zsh;
|
||||||
description = "My Full Name";
|
hashedPassword = "$6$..."; # Generate with: mkpasswd -m sha-512
|
||||||
extraGroups = [ "networkmanager" "wheel" ];
|
opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
|
||||||
shell = pkgs.zsh; # or pkgs.bash, pkgs.fish
|
|
||||||
hashedPassword = "$6$..."; # Generate with: mkpasswd -m sha-512
|
|
||||||
opensshKeys = [
|
|
||||||
"ssh-ed25519 AAAA... user@machine"
|
|
||||||
];
|
|
||||||
# enable = false; # Will be enabled per-system in inventory.nix
|
|
||||||
};
|
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Generate a hashed password:
|
2. Enable on hosts in `inventory.nix`:
|
||||||
```bash
|
|
||||||
mkpasswd -m sha-512 # Enter password when prompted
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Enable the user on specific hosts in `inventory.nix`:
|
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
nix-laptop = {
|
nix-laptop = {
|
||||||
devices = 2;
|
devices = 2;
|
||||||
overrides.extraUsers = [ "myuser" ]; # Enables on all nix-laptop hosts
|
overrides.ugaif.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
|
||||||
|
nix-laptop = {
|
||||||
|
devices = 5; # Creates nix-laptop1 through nix-laptop5
|
||||||
};
|
};
|
||||||
|
|
||||||
# Or for individual devices:
|
# With configuration
|
||||||
nix-desktop = {
|
nix-surface = {
|
||||||
devices = {
|
devices = {
|
||||||
"1".extraUsers = [ "myuser" "otheruser" ];
|
"1".ugaif.sw.kioskUrl = "https://dashboard1.example.com";
|
||||||
|
"2".ugaif.sw.kioskUrl = "https://dashboard2.example.com";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
# With overrides for all devices
|
||||||
|
nix-desktop = {
|
||||||
|
devices = 3;
|
||||||
|
overrides = {
|
||||||
|
ugaif.users.student.enable = true;
|
||||||
|
ugaif.sw.extraPackages = with pkgs; [ vim ];
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
### User Configuration Options
|
**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.**
|
||||||
|
|
||||||
Each user in `users.nix` can have:
|
### Using External Configurations
|
||||||
|
|
||||||
|
Users and systems can reference external Git repositories for configuration:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
|
# In users.nix - External dotfiles
|
||||||
myuser = {
|
myuser = {
|
||||||
description = "Full Name"; # User's full name
|
description = "My Name";
|
||||||
isNormalUser = true; # Default: true
|
|
||||||
extraGroups = [ ... ]; # Additional groups (wheel, docker, etc.)
|
|
||||||
shell = pkgs.zsh; # Login shell
|
|
||||||
hashedPassword = "$6$..."; # Hashed password
|
|
||||||
opensshKeys = [ "ssh-ed25519 ..." ]; # SSH public keys
|
|
||||||
homePackages = with pkgs; [ ... ]; # Home-manager packages (if no external config)
|
|
||||||
useZshTheme = true; # Use system Zsh theme (default: true)
|
|
||||||
useNvimPlugins = true; # Use system Neovim config (default: true)
|
|
||||||
|
|
||||||
# External home-manager configuration (optional)
|
|
||||||
home = builtins.fetchGit {
|
home = builtins.fetchGit {
|
||||||
url = "https://github.com/username/dotfiles";
|
url = "https://github.com/username/dotfiles";
|
||||||
rev = "abc123...";
|
rev = "abc123...";
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
```
|
|
||||||
|
|
||||||
### External User Configuration
|
# In inventory.nix - External system config
|
||||||
|
|
||||||
Users can maintain their dotfiles and home-manager configuration in separate repositories. See [External Modules](#external-modules) and [USER_CONFIGURATION.md](USER_CONFIGURATION.md) for details.
|
|
||||||
|
|
||||||
**Quick example:**
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
home = builtins.fetchGit {
|
|
||||||
url = "https://github.com/username/dotfiles";
|
|
||||||
rev = "commit-hash";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
The external repository should contain:
|
|
||||||
- `home.nix` (required) - Home-manager configuration
|
|
||||||
- `nixos.nix` (optional) - System-level user configuration
|
|
||||||
|
|
||||||
**Create a template:**
|
|
||||||
```bash
|
|
||||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#user
|
|
||||||
```
|
|
||||||
|
|
||||||
## Host Configuration
|
|
||||||
|
|
||||||
### Understanding Inventory Structure
|
|
||||||
|
|
||||||
The `inventory.nix` file defines all hosts in the fleet using a flexible system:
|
|
||||||
|
|
||||||
**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`)
|
|
||||||
- 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
|
|
||||||
extraUsers = [ "student" ];
|
|
||||||
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
|
|
||||||
|
|
||||||
**Convenience shortcuts** (automatically converted to proper options):
|
|
||||||
- `extraUsers` → `ugaif.users.enabledUsers`
|
|
||||||
- `hostname` → Custom hostname (overrides default naming)
|
|
||||||
- `buildMethods` → `ugaif.host.buildMethods`
|
|
||||||
- `wslUser` → `ugaif.host.wsl.user`
|
|
||||||
|
|
||||||
**Direct configuration** (any NixOS or ugaif option):
|
|
||||||
```nix
|
|
||||||
"1" = {
|
|
||||||
# Convenience
|
|
||||||
extraUsers = [ "myuser" ];
|
|
||||||
|
|
||||||
# UGAIF options
|
|
||||||
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:
|
|
||||||
- Adds user to `extraUsers` (enables the account)
|
|
||||||
- Sets `ugaif.host.wsl.user` to the username (for WSL)
|
|
||||||
|
|
||||||
### External System Configuration
|
|
||||||
|
|
||||||
For complex configurations, use external modules. See [External Modules](#external-modules) and [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md).
|
|
||||||
|
|
||||||
```nix
|
|
||||||
nix-lxc = {
|
nix-lxc = {
|
||||||
devices = {
|
devices."server" = builtins.fetchGit {
|
||||||
"special-server" = builtins.fetchGit {
|
url = "https://github.com/org/server-config";
|
||||||
url = "https://github.com/org/server-config";
|
rev = "abc123...";
|
||||||
rev = "abc123...";
|
|
||||||
};
|
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
**Create a template:**
|
**Create templates:**
|
||||||
```bash
|
```bash
|
||||||
|
# User configuration (dotfiles)
|
||||||
|
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#user
|
||||||
|
|
||||||
|
# System configuration
|
||||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#system
|
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#system
|
||||||
```
|
```
|
||||||
|
|
||||||
## External Modules
|
**See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.**
|
||||||
|
|
||||||
External modules allow you to maintain user or system configurations in separate Git repositories and reference them from `users.nix` or `inventory.nix`.
|
### Building Installation Media
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
### Templates
|
|
||||||
|
|
||||||
Initialize a new external configuration:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# User configuration (home-manager, dotfiles)
|
# Build installer ISO
|
||||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#user
|
|
||||||
|
|
||||||
# System configuration (services, packages, hardware)
|
|
||||||
nix flake init -t github:UGA-Innovation-Factory/nixos-systems#system
|
|
||||||
```
|
|
||||||
|
|
||||||
### User Module Example
|
|
||||||
|
|
||||||
In `users.nix`:
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
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 user configuration
|
|
||||||
```
|
|
||||||
|
|
||||||
See [USER_CONFIGURATION.md](USER_CONFIGURATION.md) and [templates/user/](templates/user/) for details.
|
|
||||||
|
|
||||||
### System Module Example
|
|
||||||
|
|
||||||
In `inventory.nix`:
|
|
||||||
```nix
|
|
||||||
nix-lxc = {
|
|
||||||
devices = {
|
|
||||||
"custom-server" = builtins.fetchGit {
|
|
||||||
url = "https://github.com/org/server-config";
|
|
||||||
rev = "abc123...";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
External repository structure:
|
|
||||||
```
|
|
||||||
server-config/
|
|
||||||
└── default.nix # Required: NixOS module
|
|
||||||
```
|
|
||||||
|
|
||||||
See [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) and [templates/system/](templates/system/) for details.
|
|
||||||
|
|
||||||
### Fetch Methods
|
|
||||||
|
|
||||||
**Recommended: fetchGit with revision**
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "https://github.com/user/repo";
|
|
||||||
rev = "abc123def456..."; # Full commit hash
|
|
||||||
ref = "main"; # Optional: branch name
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Local path (for testing)**
|
|
||||||
```nix
|
|
||||||
/path/to/local/config
|
|
||||||
```
|
|
||||||
|
|
||||||
**Tarball (for releases)**
|
|
||||||
```nix
|
|
||||||
builtins.fetchTarball {
|
|
||||||
url = "https://github.com/user/repo/archive/v1.0.0.tar.gz";
|
|
||||||
sha256 = "sha256:...";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Building Artifacts
|
|
||||||
|
|
||||||
Build installation media and container images from this flake.
|
|
||||||
|
|
||||||
### Installer ISOs
|
|
||||||
|
|
||||||
Build an auto-install ISO for a specific host:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Build locally
|
|
||||||
nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1
|
nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1
|
||||||
|
|
||||||
# Build using remote builder
|
# Build LXC container
|
||||||
nix build github:UGA-Innovation-Factory/nixos-systems#installer-iso-nix-laptop1 \
|
nix build .#lxc-nix-builder
|
||||||
--builders "ssh://engr-ugaif@nix-builder x86_64-linux"
|
|
||||||
```
|
|
||||||
|
|
||||||
Result: `result/iso/nixos-*.iso`
|
# List all available artifacts
|
||||||
|
|
||||||
### Available Artifacts
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# List all available builds
|
|
||||||
nix flake show github:UGA-Innovation-Factory/nixos-systems
|
nix flake show github:UGA-Innovation-Factory/nixos-systems
|
||||||
|
|
||||||
# Common artifacts:
|
|
||||||
nix build .#installer-iso-nix-laptop1 # Installer ISO
|
|
||||||
nix build .#iso-nix-ephemeral1 # Live ISO (no installer)
|
|
||||||
nix build .#ipxe-nix-ephemeral1 # iPXE netboot
|
|
||||||
nix build .#lxc-nix-builder # LXC container tarball
|
|
||||||
nix build .#proxmox-nix-builder # Proxmox VMA
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using Remote Builders
|
**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.**
|
||||||
|
|
||||||
Speed up builds by offloading to a build server:
|
## System Types
|
||||||
|
|
||||||
```bash
|
- **`desktop`** - Full GNOME desktop environment
|
||||||
# In ~/.config/nix/nix.conf or /etc/nix/nix.conf:
|
- **`tablet-kiosk`** - Surface tablets in kiosk mode
|
||||||
builders = ssh://engr-ugaif@nix-builder x86_64-linux
|
- **`stateless-kiosk`** - Diskless PXE boot kiosks
|
||||||
|
- **`headless`** - Servers and containers (no GUI)
|
||||||
|
|
||||||
# Or use --builders flag for one-time builds
|
Set via `ugaif.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options.
|
||||||
nix build ... --builders "ssh://engr-ugaif@nix-builder x86_64-linux"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
### Testing Configuration Changes
|
**Quick commands:**
|
||||||
|
|
||||||
Before committing changes:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Check all configurations build correctly
|
nix flake check # Validate all configurations
|
||||||
nix flake check
|
nix fmt # Format code
|
||||||
|
nix flake update # Update dependencies
|
||||||
# Check with verbose trace on error
|
nix build .#installer-iso-nix-laptop1 # Build specific artifact
|
||||||
nix flake check --show-trace
|
|
||||||
|
|
||||||
# Build a specific host configuration
|
|
||||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
|
||||||
|
|
||||||
# Test rebuild locally
|
|
||||||
sudo nixos-rebuild test --flake .
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Manual System Rebuilds
|
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.**
|
||||||
|
|
||||||
For testing or emergency fixes:
|
|
||||||
|
|
||||||
```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
|
|
||||||
|
|
||||||
# Rebuild from GitHub
|
|
||||||
sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems
|
|
||||||
```
|
|
||||||
|
|
||||||
### Updating Flake Inputs
|
|
||||||
|
|
||||||
Update nixpkgs, home-manager, and other dependencies:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Update all inputs
|
|
||||||
nix flake update
|
|
||||||
|
|
||||||
# Update specific input
|
|
||||||
nix flake lock --update-input nixpkgs
|
|
||||||
|
|
||||||
# After updating, test and commit
|
|
||||||
git add flake.lock
|
|
||||||
git commit -m "Update flake inputs"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Python Development
|
|
||||||
|
|
||||||
All systems include `pixi` and `uv` for project-based Python environments:
|
|
||||||
|
|
||||||
**Pixi (recommended for projects):**
|
|
||||||
```bash
|
|
||||||
pixi init my-project
|
|
||||||
cd my-project
|
|
||||||
pixi add pandas numpy matplotlib
|
|
||||||
pixi run python script.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**uv (quick virtual environments):**
|
|
||||||
```bash
|
|
||||||
uv venv
|
|
||||||
source .venv/bin/activate
|
|
||||||
uv pip install requests
|
|
||||||
```
|
|
||||||
|
|
||||||
### Adding Packages System-Wide
|
|
||||||
|
|
||||||
**To all desktop systems:**
|
|
||||||
- Edit `sw/desktop/programs.nix`
|
|
||||||
|
|
||||||
**To all tablet kiosks:**
|
|
||||||
- Edit `sw/tablet-kiosk/programs.nix`
|
|
||||||
|
|
||||||
**To all headless systems:**
|
|
||||||
- Edit `sw/headless/programs.nix`
|
|
||||||
|
|
||||||
**To specific hosts:**
|
|
||||||
- Add to `ugaif.sw.extraPackages` in `inventory.nix`
|
|
||||||
|
|
||||||
Example:
|
|
||||||
```nix
|
|
||||||
nix-laptop = {
|
|
||||||
devices = 2;
|
|
||||||
overrides = {
|
|
||||||
ugaif.sw.extraPackages = with pkgs; [ vim docker ];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### Changing System Type
|
|
||||||
|
|
||||||
System types are defined in `hosts/types/` and set the software profile:
|
|
||||||
|
|
||||||
- **`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
|
|
||||||
|
|
||||||
To change a host's type, edit the type module it imports in `hosts/types/`.
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
### Common Issues
|
**Common issues:**
|
||||||
|
|
||||||
**"error: executing 'git': No such file or directory"**
|
- **Build errors:** Run `nix flake check --show-trace` for details
|
||||||
- The `update-system` service needs git in PATH (fixed in latest version)
|
- **External modules not loading:** Check repository access and module structure (see templates)
|
||||||
- Workaround: Run `sudo nixos-rebuild switch --flake github:UGA-Innovation-Factory/nixos-systems` manually
|
- **Remote build failures:** Test SSH access: `ssh engr-ugaif@nix-builder`
|
||||||
|
- **Out of disk space:** Run `nix-collect-garbage -d && nix store optimise`
|
||||||
|
|
||||||
**Build errors after flake update**
|
**Useful commands:**
|
||||||
```bash
|
```bash
|
||||||
# Check what changed
|
nix flake show # List all available outputs
|
||||||
git diff flake.lock
|
nix flake metadata # Show flake info
|
||||||
|
nix eval .#nixosConfigurations --apply builtins.attrNames # List all hosts
|
||||||
# Try with show-trace for details
|
|
||||||
nix flake check --show-trace
|
|
||||||
|
|
||||||
# Revert if needed
|
|
||||||
git checkout flake.lock
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**External modules not loading**
|
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.**
|
||||||
- Ensure repository is accessible (public or SSH configured)
|
|
||||||
- Module must export proper structure (see templates)
|
|
||||||
- For users: requires `home.nix` and optionally `nixos.nix`
|
|
||||||
- For systems: requires `default.nix` that accepts `{ inputs, ... }`
|
|
||||||
|
|
||||||
**Remote build failures**
|
## Getting Help
|
||||||
```bash
|
|
||||||
# Test SSH access
|
|
||||||
ssh engr-ugaif@nix-builder
|
|
||||||
|
|
||||||
# Check builder disk space
|
- Review documentation in `docs/` directory
|
||||||
ssh engr-ugaif@nix-builder df -h
|
- Check templates: `templates/user/` and `templates/system/`
|
||||||
|
|
||||||
# Temporarily disable remote builds in inventory.nix:
|
|
||||||
ugaif.sw.remoteBuild.enable = false;
|
|
||||||
```
|
|
||||||
|
|
||||||
**"dirty git tree" warnings**
|
|
||||||
- Commit or stash uncommitted changes
|
|
||||||
- These warnings don't prevent builds but affect reproducibility
|
|
||||||
|
|
||||||
### Getting Help
|
|
||||||
|
|
||||||
- Check documentation: [USER_CONFIGURATION.md](USER_CONFIGURATION.md), [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md)
|
|
||||||
- Review templates: `templates/user/` and `templates/system/`
|
|
||||||
- Contact Innovation Factory IT team
|
- Contact Innovation Factory IT team
|
||||||
|
|
||||||
### Useful Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Show all available outputs
|
|
||||||
nix flake show
|
|
||||||
|
|
||||||
# Evaluate a 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
|
|
||||||
|
|
||||||
# Update and show what changed
|
|
||||||
nix flake update && git diff flake.lock
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -1,288 +0,0 @@
|
|||||||
# External User Configuration
|
|
||||||
|
|
||||||
This document explains how to use external modules for user configuration in nixos-systems.
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Users can now maintain their home-manager configurations in separate Git repositories and reference them from `users.nix` using `builtins.fetchGit`, similar to how external system configurations work.
|
|
||||||
|
|
||||||
## Changes from Previous System
|
|
||||||
|
|
||||||
### Before (Flakes)
|
|
||||||
```nix
|
|
||||||
hdh20267 = {
|
|
||||||
description = "Hunter Halloran";
|
|
||||||
flakeUrl = "github:hdh20267/dotfiles";
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### After (Modules with fetchGit)
|
|
||||||
```nix
|
|
||||||
hdh20267 = {
|
|
||||||
description = "Hunter Halloran";
|
|
||||||
home = builtins.fetchGit {
|
|
||||||
url = "https://github.com/hdh20267/dotfiles";
|
|
||||||
rev = "abc123...";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration Methods
|
|
||||||
|
|
||||||
### 1. External Repository (fetchGit)
|
|
||||||
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
extraGroups = [ "wheel" "networkmanager" ];
|
|
||||||
home = builtins.fetchGit {
|
|
||||||
url = "https://github.com/username/dotfiles";
|
|
||||||
rev = "commit-hash"; # For reproducibility
|
|
||||||
ref = "main"; # Optional branch
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Local Path (for testing)
|
|
||||||
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
home = /home/username/dev/dotfiles;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Inline Configuration
|
|
||||||
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
home = {
|
|
||||||
home.packages = with pkgs; [ vim git ];
|
|
||||||
programs.git = {
|
|
||||||
enable = true;
|
|
||||||
userName = "My Name";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. No External Config (legacy)
|
|
||||||
|
|
||||||
```nix
|
|
||||||
myuser = {
|
|
||||||
description = "My Name";
|
|
||||||
homePackages = [ pkgs.vim ];
|
|
||||||
# home = null; # Default
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## External Repository Structure
|
|
||||||
|
|
||||||
When using `fetchGit` or a path, the repository must contain:
|
|
||||||
|
|
||||||
### Required: home.nix
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
|
|
||||||
{ config, lib, pkgs, osConfig, ... }:
|
|
||||||
|
|
||||||
{
|
|
||||||
# Home-manager configuration
|
|
||||||
home.packages = with pkgs; [ ... ];
|
|
||||||
programs.git = { ... };
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Optional: nixos.nix
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
|
|
||||||
{
|
|
||||||
# System-level configuration (if needed)
|
|
||||||
users.users.myuser.extraGroups = [ "docker" ];
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Integration with System
|
|
||||||
|
|
||||||
External user modules:
|
|
||||||
|
|
||||||
1. **Receive inputs**: Same flake inputs as nixos-systems (nixpkgs, home-manager, etc.)
|
|
||||||
2. **Access osConfig**: Can read system configuration via `osConfig` parameter
|
|
||||||
3. **Merged with system settings**: Combined with inventory.nix user settings
|
|
||||||
4. **System themes applied**: Zsh/nvim themes from system if enabled
|
|
||||||
|
|
||||||
### Module Loading Order
|
|
||||||
|
|
||||||
For home-manager configuration:
|
|
||||||
1. External module (`home.nix`)
|
|
||||||
2. System theme module (if `useZshTheme = true`)
|
|
||||||
3. System nvim config (if `useNvimPlugins = true`)
|
|
||||||
|
|
||||||
For NixOS configuration:
|
|
||||||
1. User's NixOS module (`nixos.nix`, if exists)
|
|
||||||
2. All other system modules
|
|
||||||
|
|
||||||
## Available Parameters
|
|
||||||
|
|
||||||
In `home.nix`, you receive:
|
|
||||||
- `inputs` - Flake inputs (nixpkgs, home-manager, etc.)
|
|
||||||
- `config` - Home-manager configuration
|
|
||||||
- `lib` - Nixpkgs library functions
|
|
||||||
- `pkgs` - Package set
|
|
||||||
- `osConfig` - OS-level configuration (readonly)
|
|
||||||
|
|
||||||
In `nixos.nix`, you receive:
|
|
||||||
- `inputs` - Flake inputs
|
|
||||||
- `config` - NixOS configuration
|
|
||||||
- `lib` - Nixpkgs library functions
|
|
||||||
- `pkgs` - Package set
|
|
||||||
|
|
||||||
## User Options in users.nix
|
|
||||||
|
|
||||||
When defining a user with external config:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
username = {
|
|
||||||
# Required
|
|
||||||
description = "Full Name";
|
|
||||||
|
|
||||||
# External configuration
|
|
||||||
home = builtins.fetchGit { ... };
|
|
||||||
|
|
||||||
# System settings (still configured here)
|
|
||||||
extraGroups = [ "wheel" ];
|
|
||||||
hashedPassword = "$6$...";
|
|
||||||
opensshKeys = [ "ssh-ed25519 ..." ];
|
|
||||||
shell = pkgs.zsh;
|
|
||||||
|
|
||||||
# Control system integration
|
|
||||||
useZshTheme = true; # Apply system zsh theme
|
|
||||||
useNvimPlugins = true; # Apply system nvim config
|
|
||||||
|
|
||||||
# Legacy options (ignored if home is set)
|
|
||||||
homePackages = [ ]; # Use home.packages in home.nix instead
|
|
||||||
extraImports = [ ]; # Use imports in home.nix instead
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## Examples
|
|
||||||
|
|
||||||
### Minimal Dotfiles Repository
|
|
||||||
|
|
||||||
```
|
|
||||||
my-dotfiles/
|
|
||||||
├── home.nix
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**home.nix:**
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
{
|
|
||||||
home.packages = with pkgs; [ vim git htop ];
|
|
||||||
|
|
||||||
programs.git = {
|
|
||||||
enable = true;
|
|
||||||
userName = "My Name";
|
|
||||||
userEmail = "me@example.com";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### With Dotfiles
|
|
||||||
|
|
||||||
```
|
|
||||||
my-dotfiles/
|
|
||||||
├── home.nix
|
|
||||||
├── nixos.nix
|
|
||||||
├── dotfiles/
|
|
||||||
│ ├── bashrc
|
|
||||||
│ └── vimrc
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**home.nix:**
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
{
|
|
||||||
home.file.".bashrc".source = ./dotfiles/bashrc;
|
|
||||||
home.file.".vimrc".source = ./dotfiles/vimrc;
|
|
||||||
|
|
||||||
programs.git = {
|
|
||||||
enable = true;
|
|
||||||
userName = "My Name";
|
|
||||||
userEmail = "me@example.com";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### With System Configuration
|
|
||||||
|
|
||||||
**nixos.nix:**
|
|
||||||
```nix
|
|
||||||
{ inputs, ... }:
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
{
|
|
||||||
# Add user to docker group
|
|
||||||
users.users.myusername.extraGroups = [ "docker" ];
|
|
||||||
|
|
||||||
# Install system-level packages
|
|
||||||
environment.systemPackages = [ pkgs.docker ];
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Migration Guide
|
|
||||||
|
|
||||||
### From flakeUrl to home
|
|
||||||
|
|
||||||
1. **Update users.nix:**
|
|
||||||
```diff
|
|
||||||
- flakeUrl = "github:user/dotfiles";
|
|
||||||
+ home = builtins.fetchGit {
|
|
||||||
+ url = "https://github.com/user/dotfiles";
|
|
||||||
+ rev = "latest-commit-hash";
|
|
||||||
+ };
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Update your dotfiles repository:**
|
|
||||||
- Rename or ensure you have `home.nix` (not `flake.nix`)
|
|
||||||
- Change module signature from flake to simple module:
|
|
||||||
```diff
|
|
||||||
- { inputs, outputs, ... }:
|
|
||||||
+ { inputs, ... }:
|
|
||||||
{ config, lib, pkgs, ... }:
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Optional: Add nixos.nix** for system-level config
|
|
||||||
|
|
||||||
4. **Test locally first:**
|
|
||||||
```nix
|
|
||||||
home = /path/to/local/dotfiles;
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Deploy:**
|
|
||||||
```bash
|
|
||||||
nix flake check
|
|
||||||
./deploy hostname
|
|
||||||
```
|
|
||||||
|
|
||||||
## Benefits
|
|
||||||
|
|
||||||
- **No Flakes Required**: Simpler for users unfamiliar with flakes
|
|
||||||
- **Explicit Versioning**: Pin to specific commits with `rev`
|
|
||||||
- **Faster Evaluation**: No flake evaluation overhead
|
|
||||||
- **Local Testing**: Easy to test with local paths
|
|
||||||
- **Flexibility**: Supports Git, paths, or inline configs
|
|
||||||
- **Reproducibility**: Commit hashes ensure exact versions
|
|
||||||
|
|
||||||
## Templates
|
|
||||||
|
|
||||||
See `/home/engr-ugaif/user-config-template/` for templates and detailed examples.
|
|
||||||
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