97646f3229
- Update NAMESPACE.md: filesystem.device and swapSize defaults now null - Update README.md: add 'Using Athenix as a Library' section with lib.mkFleet - Update copilot-instructions.md: reflect new directory structure and defaults - Update EXTERNAL_MODULES.md: correct paths from variants/ and glue/ to hw/ and fleet/ - Update PROXMOX_LXC.md: update hardware type path reference
324 lines
9.6 KiB
Markdown
324 lines
9.6 KiB
Markdown
# Athenix - UGA Innovation Factory NixOS Configuration
|
|
|
|
[](https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions)
|
|
|
|
Declarative NixOS configuration management for the Innovation Factory's fleet of workstations, laptops, tablets, and containers using Nix flakes.
|
|
|
|
## Quick Navigation
|
|
|
|
- **[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
|
|
|
|
## Getting Started
|
|
|
|
### For End Users
|
|
|
|
Update your system:
|
|
|
|
```bash
|
|
update-system
|
|
```
|
|
|
|
This automatically rebuilds your system with the latest configuration from the repository.
|
|
|
|
### For Administrators
|
|
|
|
Make configuration changes:
|
|
|
|
```bash
|
|
# Edit inventory
|
|
vim inventory.nix
|
|
|
|
# Validate changes
|
|
nix flake check
|
|
|
|
# Format code
|
|
nix fmt
|
|
|
|
# Commit and push
|
|
git add . && git commit -m "Your message" && git push
|
|
```
|
|
|
|
Users automatically get changes when they run `update-system`.
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
flake.nix # Flake entry point (inputs + outputs)
|
|
inventory.nix # Fleet inventory and host definitions
|
|
users.nix # User account definitions
|
|
|
|
flake.lock # Locked dependency versions
|
|
|
|
hw/ # Hardware type modules (exportable as nixosModules)
|
|
├── default.nix # Auto-exports all variant types
|
|
├── nix-desktop.nix # Desktop workstations
|
|
├── nix-laptop.nix # Laptop systems
|
|
├── nix-surface.nix # Surface Pro tablets
|
|
├── nix-lxc.nix # LXC containers
|
|
├── nix-wsl.nix # WSL instances
|
|
├── nix-zima.nix # ZimaBoard systems
|
|
└── nix-ephemeral.nix # Diskless/netboot systems
|
|
|
|
fleet/ # Fleet generation and common configuration
|
|
├── default.nix # Processes inventory.nix to generate all hosts
|
|
├── common.nix # Common NixOS configuration (all hosts)
|
|
├── boot.nix # Boot and filesystem configuration
|
|
└── user-config.nix # User account and home-manager integration
|
|
|
|
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-specific options use the `athenix` namespace to avoid conflicts with NixOS options.
|
|
|
|
### Common Options
|
|
|
|
```nix
|
|
# Host filesystem and hardware
|
|
athenix.host = {
|
|
filesystem.device = "/dev/sda";
|
|
filesystem.swapSize = "32G";
|
|
buildMethods = [ "installer-iso" ];
|
|
useHostPrefix = true;
|
|
};
|
|
|
|
# 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
|
|
```
|
|
|
|
See [docs/NAMESPACE.md](docs/NAMESPACE.md) for complete option reference.
|
|
|
|
## Common Tasks
|
|
|
|
### Adding Hosts
|
|
|
|
Edit `inventory.nix`:
|
|
|
|
```nix
|
|
# Simple: Create 5 identical laptops
|
|
nix-laptop = {
|
|
devices = 5;
|
|
};
|
|
|
|
# With custom configuration per device
|
|
nix-surface = {
|
|
devices = {
|
|
"1".athenix.sw.kioskUrl = "https://dashboard1.example.com";
|
|
"2".athenix.sw.kioskUrl = "https://dashboard2.example.com";
|
|
};
|
|
};
|
|
|
|
# With common overrides
|
|
nix-desktop = {
|
|
devices = 3;
|
|
overrides = {
|
|
athenix.users.student.enable = true;
|
|
};
|
|
};
|
|
```
|
|
|
|
**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
|
|
|
|
Reference external repositories for user dotfiles or system configurations:
|
|
|
|
```nix
|
|
# User dotfiles (in users.nix)
|
|
hdh20267.external = builtins.fetchGit {
|
|
url = "https://git.factory.uga.edu/hdh20267/dotfiles";
|
|
rev = "abc123...";
|
|
};
|
|
|
|
# System configuration (in inventory.nix)
|
|
nix-lxc = {
|
|
devices."special" = builtins.fetchGit {
|
|
url = "https://git.factory.uga.edu/org/server-config";
|
|
rev = "abc123...";
|
|
};
|
|
};
|
|
```
|
|
|
|
**See [docs/EXTERNAL_MODULES.md](docs/EXTERNAL_MODULES.md) for complete guide.**
|
|
|
|
### Building Installation Media
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
**See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.**
|
|
|
|
### Using Athenix as a Library
|
|
|
|
Import Athenix in your own flake to use its fleet generation logic with custom inventory:
|
|
|
|
```nix
|
|
{
|
|
inputs.athenix.url = "git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git";
|
|
|
|
outputs = { self, athenix, ... }: {
|
|
# Generate configurations with custom fleet and hardware types
|
|
nixosConfigurations = athenix.lib.mkFleet {
|
|
fleet = import ./my-inventory.nix;
|
|
hwTypes = import ./my-hardware-types.nix;
|
|
};
|
|
|
|
# Or use individual modules
|
|
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
|
modules = [
|
|
athenix.nixosModules.hw.nix-desktop # Use Athenix hardware configs
|
|
athenix.nixosModules.sw # Use Athenix software configs
|
|
./configuration.nix
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
**Exported modules:** `nix-desktop`, `nix-laptop`, `nix-surface`, `nix-lxc`, `nix-wsl`, `nix-ephemeral`, `nix-zima`, `sw`, `common`
|
|
|
|
## System Types
|
|
|
|
Set via `athenix.sw.type`:
|
|
|
|
- **`desktop`** - Full GNOME desktop environment
|
|
- **`tablet-kiosk`** - Surface tablets with Firefox kiosk browser
|
|
- **`stateless-kiosk`** - Diskless PXE-booted systems
|
|
- **`headless`** - Servers and containers without GUI
|
|
- **`builders`** - Build servers
|
|
|
|
## Development Workflow
|
|
|
|
```bash
|
|
# 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 detailed workflow.**
|
|
|
|
## Troubleshooting
|
|
|
|
| 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` |
|
|
|
|
## Prerequisites
|
|
|
|
Nix with flakes support:
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## More Information
|
|
|
|
- [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
|