Add GitHub Copilot instructions
Co-authored-by: Jyumpp <11142390+Jyumpp@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
243
.github/copilot-instructions.md
vendored
Normal file
243
.github/copilot-instructions.md
vendored
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user