From 2223df69dabebe366477ee3aed1ccffc7168d969 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Dec 2025 13:23:22 +0000 Subject: [PATCH] Add GitHub Copilot instructions Co-authored-by: Jyumpp <11142390+Jyumpp@users.noreply.github.com> --- .github/copilot-instructions.md | 243 ++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1cd86ed --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,243 @@ +# GitHub Copilot Instructions for nixos-systems + +This repository manages NixOS configurations for the UGA Innovation Factory's fleet of devices using Nix flakes and a custom configuration system. + +## Repository Overview + +This is a **NixOS system configuration repository** that uses: +- **Nix flakes** for dependency management and reproducible builds +- **Custom namespace** (`ugaif.*`) for all Innovation Factory-specific options +- **Inventory-based** host generation from `inventory.nix` +- **External module support** for user and system configurations +- **Multiple hardware types**: desktops, laptops, Surface tablets, LXC containers, WSL + +## Code Style and Conventions + +### Nix Code Style +- Use the repository's formatter: `nix fmt` (uses `nixfmt-rfc-style`) +- Follow existing indentation (2 spaces) +- Use descriptive variable names +- Add comments for complex logic, especially in host generation +- Preserve existing comment style and documentation + +### File Organization +- **`flake.nix`**: Entry point - inputs and outputs only +- **`inventory.nix`**: Fleet definitions - host configurations +- **`users.nix`**: User account definitions +- **`hosts/`**: Host generation logic and hardware types +- **`sw/`**: Software configurations organized by system type +- **`installer/`**: Build artifact generation (ISO, LXC, etc.) +- **`templates/`**: Templates for external configurations + +### Naming Conventions +- Module options: Use `ugaif.*` namespace for all custom options +- Hostnames: `{type}{number}` or `{type}-{name}` (e.g., `nix-laptop1`, `nix-surface-alpha`) +- Hardware types: Prefix with `nix-` (e.g., `nix-desktop`, `nix-laptop`) +- Software types: Use descriptive names (`desktop`, `tablet-kiosk`, `headless`) + +## Custom Namespace (`ugaif`) + +All Innovation Factory-specific options MUST use the `ugaif` namespace: + +### Host Options (`ugaif.host.*`) +```nix +ugaif.host = { + filesystem.device = "/dev/sda"; # Boot disk + filesystem.swapSize = "32G"; # Swap size + buildMethods = [ "iso" ]; # Artifact types + useHostPrefix = true; # Hostname prefix behavior + wsl.user = "username"; # WSL default user +}; +``` + +### Software Options (`ugaif.sw.*`) +```nix +ugaif.sw = { + type = "desktop"; # System type + kioskUrl = "https://..."; # Kiosk browser URL + python.enable = true; # Python tools (pixi, uv) + remoteBuild = { + enable = true; # Use remote builders + hosts = [ "nix-builder" ]; # Build servers + }; + extraPackages = with pkgs; [ ... ]; # Additional packages +}; +``` + +### User Options (`ugaif.users.*`) +```nix +ugaif.users = { + accounts = { ... }; # User definitions + enabledUsers = [ "root" "engr-ugaif" ]; # Enabled users +}; +ugaif.forUser = "username"; # Convenience: enable user + set WSL user +``` + +## Development Workflow + +### Testing Changes +1. **Always run `nix flake check` before committing** to validate all configurations +2. Use `nix flake check --show-trace` for detailed error messages +3. Test specific host builds: `nix build .#nixosConfigurations.{hostname}.config.system.build.toplevel` +4. For local testing: `sudo nixos-rebuild test --flake .` + +### Making Changes +1. **Minimal modifications**: Change only what's necessary +2. **Preserve existing functionality**: Don't break working configurations +3. **Test before committing**: Run `nix flake check` to validate all hosts +4. **Update documentation**: Keep README.md and other docs in sync with changes + +### Common Tasks + +#### Adding a New User +1. Edit `users.nix` to add user definition under `ugaif.users.accounts` +2. Enable user in `inventory.nix` via `extraUsers` or `ugaif.users.enabledUsers` +3. Test: `nix flake check` + +#### Adding a New Host +1. Edit `inventory.nix` to add device(s) under appropriate type +2. Use `devices = N` for simple count or `devices = { ... }` for custom configs +3. Test: `nix flake check` and build specific host + +#### Modifying Software Configuration +1. Edit appropriate file in `sw/` directory based on system type +2. For system-wide changes: modify `sw/{type}/programs.nix` +3. For specific hosts: use `ugaif.sw.extraPackages` in `inventory.nix` +4. Test: `nix flake check` + +#### Creating External Modules +1. Use templates: `nix flake init -t github:UGA-Innovation-Factory/nixos-systems#{user|system}` +2. User modules: Provide `home.nix` (required) and `nixos.nix` (optional) +3. System modules: Provide `default.nix` that accepts `{ inputs, ... }` +4. Reference in `inventory.nix` or `users.nix` using `builtins.fetchGit` + +## Important Constraints + +### What NOT to Do +- **Never** use options outside the `ugaif` namespace for Innovation Factory-specific functionality +- **Never** remove or modify working host configurations unless explicitly requested +- **Never** break existing functionality when adding new features +- **Never** hardcode values that should be configurable +- **Never** add global changes that affect all systems without careful consideration + +### What to ALWAYS Do +- **Always** run `nix flake check` before finalizing changes +- **Always** use the `ugaif.*` namespace for custom options +- **Always** preserve existing comment styles and documentation +- **Always** test that configurations build successfully +- **Always** consider impact on existing hosts when making changes +- **Always** use `nix fmt` to format code before committing + +## External Module Integration + +This repository supports external configurations via Git repositories: + +### User Configurations (Dotfiles) +```nix +# In users.nix +myuser = { + description = "My Name"; + home = builtins.fetchGit { + url = "https://github.com/username/dotfiles"; + rev = "abc123..."; # Pin to specific commit + }; +}; +``` + +### System Configurations +```nix +# In inventory.nix +nix-lxc = { + devices."special" = builtins.fetchGit { + url = "https://github.com/org/server-config"; + rev = "abc123..."; + }; +}; +``` + +**Key Points:** +- External modules receive `{ inputs }` parameter with flake inputs +- User modules must provide `home.nix` (home-manager config) +- System modules must provide `default.nix` (NixOS module) +- Always pin to specific commit hash (`rev`) for reproducibility + +## Building and Artifacts + +### Available Build Commands +```bash +# Check all configurations +nix flake check + +# Build installer ISO +nix build .#installer-iso-{hostname} + +# Build live ISO +nix build .#iso-{hostname} + +# Build LXC container +nix build .#lxc-{hostname} + +# Build Proxmox template +nix build .#proxmox-{hostname} + +# Show all available outputs +nix flake show +``` + +### Artifact Types +Set via `ugaif.host.buildMethods`: +- `"iso"` - Installer ISO with auto-install +- `"live-iso"` - Live boot ISO without installer +- `"lxc"` - LXC container tarball +- `"proxmox"` - Proxmox VMA template +- `"ipxe"` - iPXE netboot kernel and initrd + +## Troubleshooting + +### Common Issues +1. **Build failures**: Run `nix flake check --show-trace` for detailed errors +2. **External modules not loading**: Check URL accessibility and module structure +3. **User not appearing**: Ensure user is in `enabledUsers` for that host +4. **Formatting issues**: Run `nix fmt` to auto-format + +### Getting Help +- Review existing documentation: `README.md`, `USER_CONFIGURATION.md`, `EXTERNAL_MODULES.md` +- Check templates in `templates/` directory for examples +- Examine existing configurations in `inventory.nix` and `users.nix` + +## Additional Context + +### System Types +- **desktop**: Full GNOME desktop environment +- **tablet-kiosk**: Surface tablets with Firefox kiosk browser +- **stateless-kiosk**: Diskless PXE boot kiosks +- **headless**: Servers and containers without GUI + +### Hardware Types +- **nix-desktop**: Desktop workstations +- **nix-laptop**: Laptops +- **nix-surface**: Surface Pro tablets +- **nix-lxc**: LXC containers +- **nix-wsl**: WSL (Windows Subsystem for Linux) +- **nix-ephemeral**: Temporary/stateless systems + +### Key Dependencies +- NixOS 25.11 (nixpkgs) +- home-manager (user environment) +- disko (disk partitioning) +- nixos-hardware (hardware quirks) +- nixos-generators (ISO/LXC builds) +- nixos-wsl (WSL support) + +## Code Review Checklist + +When reviewing or generating code: +- [ ] Uses `ugaif.*` namespace for custom options +- [ ] Runs `nix flake check` successfully +- [ ] Follows existing code style and formatting +- [ ] Preserves existing functionality +- [ ] Updates relevant documentation if needed +- [ ] Uses appropriate abstractions (don't repeat logic) +- [ ] Considers impact on all system types +- [ ] Tests artifact builds if modifying build logic +- [ ] Pins external modules to specific commits