refactor: Module to ugaif and readme update
This commit is contained in:
UGA Innovation Factory
committed by
Hunter Halloran
Hunter Halloran
parent
c46b0aa685
commit
205f03337a
355
README.md
355
README.md
@@ -1,6 +1,19 @@
|
||||
# UGA Innovation Factory - NixOS Systems
|
||||
|
||||
This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, and surface tablets.
|
||||
This repository contains the NixOS configuration for the Innovation Factory's fleet of laptops, desktops, and surface tablets. It provides a declarative, reproducible system configuration using Nix flakes.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Repository Structure](#repository-structure)
|
||||
- [Configuration Namespace](#configuration-namespace)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Building Artifacts](#building-artifacts-isos-lxc-proxmox)
|
||||
- [Configuration Guide](#configuration-guide)
|
||||
- [User Management](#user-management)
|
||||
- [Host Configuration](#host-configuration)
|
||||
- [External Flake Templates](#external-flake-templates)
|
||||
- [Development](#development)
|
||||
|
||||
## Repository Structure
|
||||
|
||||
@@ -10,6 +23,27 @@ This repository contains the NixOS configuration for the Innovation Factory's fl
|
||||
- **`hosts/`**: Contains the logic for generating host configurations and hardware-specific types.
|
||||
- **`sw/`**: Software modules (Desktop, Kiosk, Python, Neovim, etc.).
|
||||
|
||||
## Configuration Namespace
|
||||
|
||||
All UGA Innovation Factory-specific NixOS options are organized under the `ugaif` namespace to clearly distinguish them from standard NixOS options. The main option groups are:
|
||||
|
||||
- **`ugaif.host`**: Hardware and host-level configuration
|
||||
- `ugaif.host.filesystem`: Disk device and swap size settings
|
||||
- `ugaif.host.buildMethods`: Supported artifact build methods (ISO, LXC, etc.)
|
||||
- `ugaif.host.wsl`: WSL-specific configuration
|
||||
|
||||
- **`ugaif.sw`**: Software and system type configuration
|
||||
- `ugaif.sw.enable`: Enable the software configuration module
|
||||
- `ugaif.sw.type`: System type (`desktop`, `tablet-kiosk`, `headless`, `stateless-kiosk`)
|
||||
- `ugaif.sw.kioskUrl`: URL for kiosk mode browsers
|
||||
- `ugaif.sw.python`: Python development tools settings
|
||||
- `ugaif.sw.remoteBuild`: Remote build configuration
|
||||
|
||||
- **`ugaif.users`**: User account management
|
||||
- `ugaif.users.accounts`: User account definitions
|
||||
- `ugaif.users.enabledUsers`: List of users enabled on the system
|
||||
- `ugaif.users.shell`: Default shell for users
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To work with this repository on a non-NixOS system (like macOS or another Linux distro), you need to install Nix. We recommend the Determinate Systems installer for a reliable and feature-complete setup (including Flakes support out of the box).
|
||||
@@ -20,42 +54,72 @@ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Updating the System
|
||||
### For End Users: Updating Your System
|
||||
|
||||
The system includes a utility script `update-system` that handles rebuilding and switching configurations. It automatically detects if it is running on a Surface tablet and offloads the build to a more powerful host if necessary.
|
||||
|
||||
To apply changes to the current system:
|
||||
The easiest way to update your system is using the included `update-system` utility:
|
||||
|
||||
```bash
|
||||
update-system
|
||||
```
|
||||
|
||||
This command pulls the latest configuration from GitHub and rebuilds the system.
|
||||
This command:
|
||||
- Pulls the latest configuration from GitHub
|
||||
- Rebuilds the system with any changes
|
||||
- Automatically uses remote builders if you're on a Surface tablet
|
||||
|
||||
If your configuration uses external flakes (e.g., via `flakeUrl`), you may need to allow impure evaluation:
|
||||
If you use external flakes (personal dotfiles), add the `--impure` flag:
|
||||
|
||||
```bash
|
||||
update-system --impure
|
||||
```
|
||||
|
||||
### Manual Rebuilds
|
||||
### For Administrators: Managing the Fleet
|
||||
|
||||
If you need to rebuild manually or target a specific host:
|
||||
#### Applying Configuration Changes
|
||||
|
||||
After modifying files in this repository:
|
||||
|
||||
```bash
|
||||
# Local build
|
||||
sudo nixos-rebuild switch --flake .
|
||||
# Test the configuration builds
|
||||
nix flake check
|
||||
|
||||
# Build for a specific host
|
||||
sudo nixos-rebuild switch --flake .#nix-laptop1
|
||||
# Push changes to GitHub
|
||||
git add .
|
||||
git commit -m "Description of changes"
|
||||
git push
|
||||
|
||||
# Users can then run: update-system
|
||||
```
|
||||
|
||||
### Updating Flake Inputs
|
||||
#### Manual Rebuilds
|
||||
|
||||
To update the lockfile (nixpkgs, home-manager versions, etc.):
|
||||
For testing or emergency fixes:
|
||||
|
||||
```bash
|
||||
# Rebuild current host
|
||||
sudo nixos-rebuild switch --flake .
|
||||
|
||||
# Rebuild specific host
|
||||
sudo nixos-rebuild switch --flake .#nix-laptop1
|
||||
|
||||
# Test without switching
|
||||
sudo nixos-rebuild test --flake .#nix-laptop1
|
||||
```
|
||||
|
||||
#### Updating Dependencies
|
||||
|
||||
Update nixpkgs, home-manager, and other flake inputs:
|
||||
|
||||
```bash
|
||||
# Update all inputs
|
||||
nix flake update
|
||||
|
||||
# Update specific input
|
||||
nix flake lock --update-input nixpkgs
|
||||
|
||||
# After updating, test and commit the new flake.lock
|
||||
git add flake.lock
|
||||
git commit -m "Update flake inputs"
|
||||
```
|
||||
|
||||
## Building Artifacts (ISOs, LXC, Proxmox)
|
||||
@@ -95,103 +159,159 @@ nix build .#proxmox-nix-lxc1
|
||||
|
||||
## Configuration Guide
|
||||
|
||||
### Adding a New User
|
||||
### User Management
|
||||
|
||||
#### Adding a New User
|
||||
|
||||
1. Open `users.nix`.
|
||||
2. Add a new entry to `modules.users.accounts`.
|
||||
3. Generate a hashed password using `mkpasswd -m sha-512` (requires `whois` package or similar).
|
||||
- Hashed passwords are intended for shared credentials as a minimal layer of safety; do not treat them as secure storage for personal secrets (use per-user secrets managed outside the flake instead).
|
||||
4. Commit and push.
|
||||
2. Add a new entry to `ugaif.users.accounts`:
|
||||
|
||||
### Assigning Users to Hosts
|
||||
```nix
|
||||
ugaif.users.accounts = {
|
||||
# ... existing users ...
|
||||
|
||||
newuser = {
|
||||
description = "New User Name";
|
||||
extraGroups = [ "networkmanager" "wheel" ];
|
||||
hashedPassword = "$6$..."; # Generate with: mkpasswd -m sha-512
|
||||
opensshKeys = [ "ssh-ed25519 AAAA..." ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
By default, only `root` and `engr-ugaif` are enabled. To enable a specific student user on a specific device:
|
||||
3. Generate a hashed password using `mkpasswd -m sha-512` (requires `whois` package).
|
||||
4. Commit and push the changes.
|
||||
|
||||
**Note:** Hashed passwords are for shared credentials only. For personal secrets, use external secret management.
|
||||
|
||||
#### Assigning Users to Hosts
|
||||
|
||||
By default, only `root` and `engr-ugaif` are enabled on all systems. To enable additional users on specific devices:
|
||||
|
||||
1. Open `inventory.nix`.
|
||||
2. Locate the host type (e.g., `nix-laptop`).
|
||||
3. Add or update the `devices` section for the specific index:
|
||||
3. Add the user to the device's `extraUsers` list:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
count = 2;
|
||||
devices = {
|
||||
"1" = { extraUsers = [ "student_username" ]; };
|
||||
"1".extraUsers = [ "newuser" "hdh20267" ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Using External Flakes for User Configuration
|
||||
#### Using External Flakes for User Configuration
|
||||
|
||||
### Customizing the Kiosk URL for Surfaces
|
||||
Users can manage their own dotfiles and configuration in a separate flake repository. This allows full control over shell configuration, editor settings, and Home Manager modules.
|
||||
|
||||
Surface tablets run the kiosk configuration and delegate the Chromium launch URL via `sw.kioskUrl`. You can set a per-device URL directly from `inventory.nix` by providing a `modules` override for the device entry:
|
||||
**Security Note:** External flakes run with the same privileges as the system configuration. Only use trusted flakes and pin to specific commits.
|
||||
|
||||
To enable this:
|
||||
|
||||
1. Open `users.nix`.
|
||||
2. Set the `flakeUrl` for the user:
|
||||
|
||||
```nix
|
||||
hdh20267 = {
|
||||
description = "User Name";
|
||||
extraGroups = [ "networkmanager" "wheel" ];
|
||||
hashedPassword = "$6$...";
|
||||
flakeUrl = "github:hdh20267/dotfiles";
|
||||
|
||||
# Optional: Disable system defaults
|
||||
useZshTheme = false; # Manage your own Zsh config
|
||||
useNvimPlugins = false; # Manage your own Neovim config
|
||||
};
|
||||
```
|
||||
|
||||
The external flake must provide a `nixosModules.default` output. See [User Flake Template](#user-flake-for-usersnix) below for an example.
|
||||
|
||||
### Host Configuration
|
||||
|
||||
#### Adding a New Host
|
||||
|
||||
To add more devices of an existing type:
|
||||
|
||||
1. Open `inventory.nix`.
|
||||
2. Increment the `count` for the host type:
|
||||
|
||||
```nix
|
||||
nix-laptop.count = 3; # Creates nix-laptop1, nix-laptop2, nix-laptop3
|
||||
```
|
||||
|
||||
#### Device-Specific Configuration Overrides
|
||||
|
||||
You can customize individual devices in `inventory.nix` using either shortcut keys or direct configuration.
|
||||
|
||||
**Shortcut Keys** (for common settings):
|
||||
- `extraUsers` → Sets `ugaif.users.enabledUsers`
|
||||
- `hostname` → Sets a custom hostname (default: `{type}{number}`)
|
||||
- `buildMethods` → Sets `ugaif.host.buildMethods`
|
||||
- `wslUser` → Sets `ugaif.host.wsl.user`
|
||||
- `flakeUrl` → Imports an external system flake
|
||||
|
||||
**Direct Configuration** (using the `ugaif` namespace or standard NixOS options):
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
count = 2;
|
||||
devices = {
|
||||
"1" = {
|
||||
# Shortcut keys
|
||||
extraUsers = [ "hdh20267" ];
|
||||
hostname = "laptop-special";
|
||||
|
||||
# UGAIF options
|
||||
ugaif.host.filesystem.swapSize = "64G";
|
||||
ugaif.sw.extraPackages = with pkgs; [ docker vim ];
|
||||
|
||||
# Standard NixOS options
|
||||
networking.firewall.enable = false;
|
||||
services.openssh.enable = true;
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
#### Customizing Kiosk URLs for Surface Tablets
|
||||
|
||||
Surface tablets run in kiosk mode with a full-screen Chromium browser. Set the URL per-device:
|
||||
|
||||
```nix
|
||||
nix-surface = {
|
||||
count = 3;
|
||||
devices = {
|
||||
"1" = {
|
||||
modules = {
|
||||
sw = {
|
||||
kioskUrl = "https://ha.factory.uga.edu/surface-1";
|
||||
};
|
||||
};
|
||||
};
|
||||
"1".ugaif.sw.kioskUrl = "https://ha.factory.uga.edu/dashboard-1";
|
||||
"2".ugaif.sw.kioskUrl = "https://ha.factory.uga.edu/dashboard-2";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Any other device attributes (filesystem overrides, extra users) can still sit beside `modules`; they are merged into the generated host configuration so you just need to set the `kioskUrl` value you want to use for that Surface.
|
||||
#### Using External Flakes for System Configuration
|
||||
|
||||
Users can manage their own configuration (both Home Manager and System-level settings) in a separate flake repository. External flakes run with the same privileges as the primary configuration, so audit any flake before pointing to it and pin to a known-good commit when possible.
|
||||
To use this:
|
||||
|
||||
1. Open `users.nix`.
|
||||
2. In the user's configuration block, set the `flakeUrl` option:
|
||||
|
||||
```nix
|
||||
hdh20267 = {
|
||||
# ... other settings ...
|
||||
flakeUrl = "github:hdh20267/dotfiles";
|
||||
};
|
||||
```
|
||||
|
||||
The external flake must provide a `nixosModules.default` output. This module is imported into the system configuration, allowing the user to override their own system settings (like `shell`, `extraGroups`) and define their Home Manager configuration.
|
||||
|
||||
You can also opt-out of the default system configurations for Zsh and Neovim if you prefer to manage them entirely yourself:
|
||||
|
||||
* `useZshTheme` (default: `true`): Set to `false` to disable the system-wide Zsh theme and configuration.
|
||||
* `useNvimPlugins` (default: `true`): Set to `false` to disable the system-wide Neovim plugins and configuration.
|
||||
|
||||
### Using External Flakes for System Configuration
|
||||
|
||||
You can also override the system-level configuration for a specific host using an external flake. This is useful for adding system services (like Docker), changing boot parameters, installing system-wide packages, or even overriding hardware settings (like swap size) without modifying `inventory.nix`.
|
||||
|
||||
1. Open `inventory.nix`.
|
||||
2. In the `devices` override for the host, set the `flakeUrl`:
|
||||
For complex system customizations (Docker, custom services, hardware tweaks), use an external flake:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
count = 2;
|
||||
devices = {
|
||||
"2" = {
|
||||
flakeUrl = "github:myuser/my-system-config";
|
||||
};
|
||||
"2".flakeUrl = "github:myuser/my-system-config";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
The external flake must provide a `nixosModules.default` output. Any configuration defined in that module will be merged with the host's configuration, so treat these flakes as privileged code and audit them before importing.
|
||||
The external flake must provide a `nixosModules.default` output. See [System Flake Template](#system-flake-for-inventorynix) below for an example.
|
||||
|
||||
## External Flake Templates
|
||||
|
||||
If you are creating a new flake to use with `flakeUrl`, use these templates as a starting point.
|
||||
If you're creating a flake to use with `flakeUrl`, use these templates as starting points.
|
||||
|
||||
**Important:** Do not specify `inputs` in your flake. This ensures your flake uses the exact same `nixpkgs` version as the main system, preventing version drift and saving disk space.
|
||||
|
||||
### User Flake (for `users.nix`)
|
||||
|
||||
Use this for user-specific dotfiles, shell configuration, and user packages. It can also override system-level user settings.
|
||||
|
||||
Note that `inputs` are omitted. This ensures the flake uses the exact same `nixpkgs` version as the main system, preventing version drift and saving disk space.
|
||||
Use this template for user-specific dotfiles, shell configuration, Home Manager modules, and overriding user account settings.
|
||||
|
||||
```nix
|
||||
{
|
||||
@@ -204,7 +324,7 @@ Note that `inputs` are omitted. This ensures the flake uses the exact same `nixp
|
||||
nixosModules.default = { pkgs, lib, ... }: {
|
||||
|
||||
# 1. Override System-Level User Settings
|
||||
modules.users.accounts.hdh20267 = {
|
||||
ugaif.users.accounts.hdh20267 = {
|
||||
shell = pkgs.fish;
|
||||
extraGroups = [ "docker" ];
|
||||
|
||||
@@ -239,7 +359,7 @@ Note that `inputs` are omitted. This ensures the flake uses the exact same `nixp
|
||||
|
||||
### System Flake (for `inventory.nix`)
|
||||
|
||||
Use this for host-specific system services, hardware tweaks, or root-level packages.
|
||||
Use this template for host-specific system services (Docker, databases, web servers), hardware configuration tweaks, or system-wide packages.
|
||||
|
||||
```nix
|
||||
{
|
||||
@@ -255,10 +375,10 @@ Use this for host-specific system services, hardware tweaks, or root-level packa
|
||||
virtualisation.docker.enable = true;
|
||||
|
||||
# Example: Override hardware settings defined in the main repo
|
||||
host.filesystem.swapSize = lib.mkForce "64G";
|
||||
ugaif.host.filesystem.swapSize = lib.mkForce "64G";
|
||||
|
||||
# Example: Enable specific users
|
||||
modules.users.enabledUsers = [ "myuser" ];
|
||||
ugaif.users.enabledUsers = [ "myuser" ];
|
||||
|
||||
# Example: Add a custom binary cache
|
||||
nix.settings.substituters = [ "https://nix-community.cachix.org" ];
|
||||
@@ -268,20 +388,93 @@ Use this for host-specific system services, hardware tweaks, or root-level packa
|
||||
}
|
||||
```
|
||||
|
||||
### Adding a New Host
|
||||
|
||||
1. Open `inventory.nix`.
|
||||
2. Increment the `count` for the relevant host type.
|
||||
3. The new host will be named sequentially (e.g., `nix-laptop3`).
|
||||
|
||||
## Development
|
||||
|
||||
### Python Environment
|
||||
|
||||
The system comes with `pixi` and `uv` for Python project management. It is recommended to use these tools for project-specific environments rather than installing global Python packages.
|
||||
All systems include `pixi` and `uv` for Python project management. Use these tools for project-specific environments instead of installing global Python packages (which can cause conflicts).
|
||||
|
||||
**Creating a new project with Pixi:**
|
||||
|
||||
```bash
|
||||
pixi init my_project
|
||||
cd my_project
|
||||
pixi add pandas numpy
|
||||
pixi add pandas numpy matplotlib
|
||||
pixi run python script.py
|
||||
```
|
||||
|
||||
**Using uv for quick tasks:**
|
||||
|
||||
```bash
|
||||
uv venv
|
||||
source .venv/bin/activate
|
||||
uv pip install requests
|
||||
```
|
||||
|
||||
### Testing Changes Locally
|
||||
|
||||
Before pushing changes, verify your configuration builds correctly:
|
||||
|
||||
```bash
|
||||
# Check all configurations
|
||||
nix flake check
|
||||
|
||||
# Build a specific configuration
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
||||
|
||||
# Test an ISO build
|
||||
nix build .#installer-iso-nix-laptop1
|
||||
```
|
||||
|
||||
### Common Configuration Patterns
|
||||
|
||||
#### Adding System Packages to All Hosts
|
||||
|
||||
Edit `sw/desktop/programs.nix` (or the appropriate type directory) to add packages to the base system:
|
||||
|
||||
```nix
|
||||
basePackages = with pkgs; [
|
||||
htop
|
||||
vim
|
||||
git
|
||||
# Add your packages here
|
||||
];
|
||||
```
|
||||
|
||||
#### Changing Default User Shell
|
||||
|
||||
Edit `users.nix` to set a different shell for a specific user:
|
||||
|
||||
```nix
|
||||
myuser = {
|
||||
description = "My User";
|
||||
shell = pkgs.fish; # or pkgs.zsh, pkgs.bash
|
||||
# ... other settings
|
||||
};
|
||||
```
|
||||
|
||||
Then ensure the program is enabled in the system configuration (usually already done for common shells).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Flake Check Errors
|
||||
|
||||
If `nix flake check` fails, use `--show-trace` for detailed error information:
|
||||
|
||||
```bash
|
||||
nix flake check --show-trace
|
||||
```
|
||||
|
||||
### External Flakes Not Loading
|
||||
|
||||
If using `flakeUrl`, ensure:
|
||||
1. The flake repository is public or you have SSH access configured
|
||||
2. The flake has a `nixosModules.default` output
|
||||
3. You're using `--impure` flag if the flake has impure operations
|
||||
|
||||
### Build Failures on Surface Tablets
|
||||
|
||||
Surface tablets automatically offload builds to remote builders. If builds fail:
|
||||
1. Verify the remote builder is accessible: `ssh engr-ugaif@nix-builder`
|
||||
2. Check remote builder has sufficient disk space: `df -h`
|
||||
3. Try building locally with remote builds disabled by commenting out `ugaif.sw.remoteBuild.enable`
|
||||
|
||||
Reference in New Issue
Block a user