UGA-Innovation-Factory/athenix
3
1
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

docs: Copilot update all docs files
All checks were successful
CI / Format Check (push) Successful in 6s
Details
CI / Flake Check (push) Successful in 1m25s
Details
CI / Evaluate Key Configurations (nix-builder) (push) Successful in 10s
Details
CI / Evaluate Key Configurations (nix-desktop1) (push) Successful in 11s
Details
CI / Evaluate Key Configurations (nix-laptop1) (push) Successful in 8s
Details
CI / Evaluate Artifacts (installer-iso-nix-laptop1) (push) Successful in 16s
Details
CI / Evaluate Artifacts (lxc-nix-builder) (push) Successful in 10s
Details

Browse Source
This commit is contained in:
UGA Innovation Factory
2026-01-05 10:05:41 -05:00
parent 0378268dcc
commit f07ccc071e
8 changed files with 2052 additions and 1136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
README.md
View File

@@ -1,156 +1,156 @@
# UGA Innovation Factory - Athenix
# Athenix - UGA Innovation Factory NixOS Configuration
[![CI](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions/workflows/ci.yml/badge.svg)](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions)
This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, Surface tablets, and containers. It provides a declarative, reproducible system configuration using Nix flakes.
Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.
## Documentation
## Quick Navigation
- **[Quick Start](#quick-start)** - Get started in 5 minutes
- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Configure hosts and fleet inventory
- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - Configuration options reference (`athenix.*`)
- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User account management
- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External configuration modules
- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs and container images
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development and testing workflow
- **[docs/INVENTORY.md](docs/INVENTORY.md)** - Define and configure hosts
- **[docs/NAMESPACE.md](docs/NAMESPACE.md)** - All `athenix.*` options reference
- **[docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md)** - User accounts and dotfiles
- **[docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md)** - External system and user configurations
- **[docs/BUILDING.md](docs/BUILDING.md)** - Build ISOs, containers, and artifacts
- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development workflow and testing
## Quick Start
## Getting Started
### For End Users
Update your system to the latest configuration:
Update your system:
```bash
update-system
```
This command automatically fetches the latest configuration, rebuilds your system, and uses remote builders on Surface tablets to speed up builds.
**Note:** If you use external user configurations (personal dotfiles), run:
```bash
sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure
```
This automatically rebuilds your system with the latest configuration from the repository.
### For Administrators
Make configuration changes:
```bash
# 1. Make changes to configuration files
# Edit inventory
vim inventory.nix
# 2. Test configuration
# Validate changes
nix flake check
# 3. Format code
# Format code
nix fmt
# 4. Commit and push
git add .
git commit -m "Description of changes"
git push
# Commit and push
git add . && git commit -m "Your message" && git push
```
Users can now run `update-system` to get the changes.
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development workflow.**
Users automatically get changes when they run `update-system`.
## Repository Structure
```
nixos-systems/
├── flake.nix # Flake entry point
├── inventory.nix # Fleet inventory - Define hosts here
├── users.nix # User accounts - Define users here
├── hosts/ # Host generation logic
│ ├── types/ # Hardware types (desktop, laptop, surface, lxc, wsl, ephemeral)
│ └── ...
├── sw/ # Software configurations by system type
│ ├── desktop/ # Full desktop environment
│ ├── tablet-kiosk/ # Surface kiosk mode
│ ├── stateless-kiosk/# Diskless PXE kiosks
│ ├── headless/ # Servers and containers
│ └── ...
├── installer/ # ISO and container builds
├── templates/ # Templates for external configs
│ ├── system/ # System configuration template
│ └── user/ # User configuration template
├── docs/ # Documentation
│ ├── INVENTORY.md # Host configuration guide
│ ├── NAMESPACE.md # Option reference
│ ├── BUILDING.md # Building artifacts
│ └── DEVELOPMENT.md # Development guide
└── assets/ # Assets (Plymouth theme, etc.)
flake.nix # Flake entry point (inputs + outputs)
inventory.nix # Fleet inventory and host definitions
users.nix # User account definitions
flake.lock # Locked dependency versions
hosts/ # Host generation logic
├── default.nix # Main host generator
├── boot.nix # Boot and filesystem configuration
├── common.nix # Common system configuration
├── user-config.nix # User configuration integration
└── types/ # Hardware type modules
├── nix-desktop.nix
├── nix-laptop.nix
├── nix-surface.nix
├── nix-lxc.nix
├── nix-wsl.nix
└── nix-ephemeral.nix
sw/ # Software configurations by system type
├── default.nix # Software module entry point
├── python.nix # Python tools (pixi, uv)
├── nvim.nix # Neovim configuration
├── ghostty.nix # Ghostty terminal
├── theme.nix # System theme configuration
├── updater.nix # System update scripts
├── update-ref.nix # Update reference tracking
├── builders/ # Build server configuration
├── desktop/ # Desktop environment
├── headless/ # Server/container without GUI
├── tablet-kiosk/ # Surface tablet kiosk mode
└── stateless-kiosk/ # Diskless PXE netboot systems
installer/ # Build artifacts
├── default.nix # Build configuration
├── artifacts.nix # ISO/LXC/Proxmox definitions
├── auto-install.nix # Installer scripts
├── modules.nix # Installer-specific modules
├── deploy-proxmox-lxc.sh # Proxmox deployment script
└── PROXMOX_LXC.md # Proxmox guide
templates/ # Templates for external modules
├── user/ # User configuration template
│ ├── user.nix # User options + home-manager config
│ └── README.md
└── system/ # System configuration template
├── default.nix # NixOS module
└── README.md
docs/ # Documentation
├── README.md # This file
├── INVENTORY.md # Host configuration guide
├── NAMESPACE.md # Option reference
├── USER_CONFIGURATION.md # User management
├── EXTERNAL_MODULES.md # External module integration
├── BUILDING.md # Build and deployment
└── DEVELOPMENT.md # Development workflow
assets/ # Assets
└── plymouth-theme/ # Boot splash theme
```
## Configuration Overview
All Innovation Factory options use the `athenix.*` namespace. See **[docs/NAMESPACE.md](docs/NAMESPACE.md)** for complete reference.
All Innovation Factory-specific options use the `athenix` namespace to avoid conflicts with NixOS options.
**Quick examples:**
### Common Options
```nix
# Host configuration
athenix.host.filesystem.device = "/dev/nvme0n1";
athenix.host.filesystem.swapSize = "64G";
# Host filesystem and hardware
athenix.host = {
filesystem.device = "/dev/sda";
filesystem.swapSize = "32G";
buildMethods = [ "installer-iso" ];
useHostPrefix = true;
};
# Software configuration
athenix.sw.type = "desktop"; # or "headless", "tablet-kiosk"
athenix.sw.extraPackages = with pkgs; [ vim docker ];
# System type and packages
athenix.sw = {
type = "desktop"; # desktop, tablet-kiosk, stateless-kiosk, headless, builders
extraPackages = with pkgs; [ vim docker ];
};
# User management
athenix.users.myuser.enable = true;
athenix.forUser = "myuser"; # Convenience shortcut
```
## Prerequisites
To work with this repository, install Nix with flakes support:
```bash
# Recommended: Determinate Systems installer (includes flakes)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
# Alternative: Official installer (requires enabling flakes manually)
sh <(curl -L https://nixos.org/nix/install) --daemon
```
See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference.
## Common Tasks
### Adding a New User
1. Edit `users.nix`:
```nix
myuser = {
description = "My Full Name";
extraGroups = [ "wheel" "networkmanager" ];
shell = pkgs.zsh;
hashedPassword = "$6$..."; # Generate with: mkpasswd -m sha-512
opensshKeys = [ "ssh-ed25519 AAAA... user@host" ];
};
```
2. Enable on hosts in `inventory.nix`:
```nix
nix-laptop = {
devices = 2;
overrides.athenix.users.myuser.enable = true;
};
```
**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete user management guide.**
### Adding Hosts
Edit `inventory.nix`:
```nix
# Simple: Create 5 laptops
# Simple: Create 5 identical laptops
nix-laptop = {
devices = 5; # Creates nix-laptop1 through nix-laptop5
devices = 5;
};
# With configuration
# With custom configuration per device
nix-surface = {
devices = {
"1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
@@ -158,107 +158,134 @@ nix-surface = {
};
};
# With overrides for all devices
# With common overrides
nix-desktop = {
devices = 3;
overrides = {
athenix.users.student.enable = true;
athenix.sw.extraPackages = with pkgs; [ vim ];
};
};
```
**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete host configuration guide.**
**See [docs/INVENTORY.md](docs/INVENTORY.md) for complete guide.**
### Managing Users
Edit `users.nix`:
```nix
athenix.users.myuser = {
description = "My Name";
extraGroups = [ "wheel" "networkmanager" ];
shell = pkgs.zsh;
hashedPassword = "$6$..."; # mkpasswd -m sha-512
opensshKeys = [ "ssh-ed25519 AAAA..." ];
};
```
Enable in `inventory.nix`:
```nix
nix-laptop = {
overrides.athenix.users.myuser.enable = true;
};
```
**See [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) for complete guide.**
### Using External Configurations
Users and systems can reference external Git repositories for configuration:
Reference external repositories for user dotfiles or system configurations:
```nix
# In users.nix - External dotfiles with user configuration
myuser.external = builtins.fetchGit {
url = "https://git.factory.uga.edu/username/dotfiles";
# User dotfiles (in users.nix)
hdh20267.external = builtins.fetchGit {
url = "https://git.factory.uga.edu/hdh20267/dotfiles";
rev = "abc123...";
};
# The external user.nix file contains both athenix.users.myuser options
# AND home-manager configuration
# In inventory.nix - External system config
# System configuration (in inventory.nix)
nix-lxc = {
devices."server" = builtins.fetchGit {
devices."special" = builtins.fetchGit {
url = "https://git.factory.uga.edu/org/server-config";
rev = "abc123...";
};
};
```
**Create templates:**
```bash
# User configuration (dotfiles)
nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#user
# System configuration
nix flake init -t git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#system
```
**See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.**
### Building Installation Media
```bash
# Build installer ISO
nix build git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#installer-iso-nix-laptop1
# Build installer ISO for a specific host
nix build .#installer-iso-nix-laptop1
# Build LXC container
nix build .#lxc-nix-builder
# List all available artifacts
nix flake show git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
nix flake show
```
**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide on building ISOs, containers, and using remote builders.**
**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.**
## System Types
Set via `athenix.sw.type`:
- **`desktop`** - Full GNOME desktop environment
- **`tablet-kiosk`** - Surface tablets in kiosk mode
- **`stateless-kiosk`** - Diskless PXE boot kiosks
- **`headless`** - Servers and containers (no GUI)
- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser
- **`stateless-kiosk`** - Diskless PXE-booted systems
- **`headless`** - Servers and containers without GUI
- **`builders`** - Build servers
Set via `athenix.sw.type` option. See [docs/NAMESPACE.md](docs/NAMESPACE.md) for all options.
## Development Workflow
## Development
**Quick commands:**
```bash
nix flake check # Validate all configurations
nix fmt # Format code
nix flake update # Update dependencies
nix build .#installer-iso-nix-laptop1 # Build specific artifact
# Check all configurations
nix flake check
# Format code
nix fmt **/*.nix
# Build specific artifact
nix build .#installer-iso-nix-laptop1
# Update flake inputs
nix flake update
```
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for complete development guide.**
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed workflow.**
## Troubleshooting
**Common issues:**
| Issue | Solution |
|-------|----------|
| Build errors | Run `nix flake check --show-trace` for details |
| Configuration validation | `nix flake check` checks all 50+ hosts |
| External modules fail | Verify Git URL accessibility and module structure |
| Remote build issues | Test SSH: `ssh engr-ugaif@nix-builder` |
| List all hosts | `nix eval .#nixosConfigurations --apply builtins.attrNames` |
| Disk space | `nix-collect-garbage -d && nix store optimise` |
- **Build errors:** Run `nix flake check --show-trace` for details
- **External modules not loading:** Check repository access and module structure (see templates)
- **Remote build failures:** Test SSH access: `ssh engr-ugaif@nix-builder`
- **Out of disk space:** Run `nix-collect-garbage -d && nix store optimise`
## Prerequisites
Nix with flakes support:
**Useful commands:**
```bash
nix flake show # List all available outputs
nix flake metadata # Show flake info
nix eval .#nixosConfigurations --apply builtins.attrNames # List all hosts
# Recommended: Determinate Systems installer
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
# Or enable flakes in existing Nix installation
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
```
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/BUILDING.md](docs/BUILDING.md) for detailed troubleshooting.**
## More Information
## Getting Help
- Review documentation in `docs/` directory
- Check templates: `templates/user/` and `templates/system/`
- Contact Innovation Factory IT team
- [docs/INVENTORY.md](docs/INVENTORY.md) - Host configuration
- [docs/NAMESPACE.md](docs/NAMESPACE.md) - All option references
- [docs/USER_CONFIGURATION.md](docs/USER_CONFIGURATION.md) - User management
- [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) - External modules
- [docs/BUILDING.md](docs/BUILDING.md) - Building and deployment
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development guide