fireproof/nixos
1
0
Fork 0
mirror of https://github.com/nickolaj-jepsen/nixos.git synced 2026-01-22 08:06:50 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: update copilot-instructions.md

Browse source
This commit is contained in:
Nickolaj Jepsen 2026-01-21 00:14:09 +01:00
parent 9dc3bb6785
commit e752b0ee17
1 changed files with 53 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

140
.github/copilot-instructions.md vendored
View file

@ -1,130 +1,94 @@
# NixOS Configuration - AI Assistant Instructions # NixOS Configuration - Copilot Instructions
## Architecture Overview ## Architecture Overview
This is a **NixOS flake-based configuration** managing multiple hosts (desktop, laptop, homelab, work, WSL) with: This is a **NixOS flake-based configuration** using flake-parts, managing multiple hosts (desktop, laptop, work, homelab, desktop-wsl, bootstrap). The configuration uses a custom module system under `fireproof.*` options.
- **flake-parts** for modular flake organization ### Key Structural Patterns
- **home-manager** integrated via `fireproof.home-manager` option (not standalone)
- **agenix + agenix-rekey** for YubiKey-based secret management
- **disko** for declarative disk partitioning
### Module Structure - **Host definitions**: `hosts/<hostname>/default.nix` sets `fireproof.hostname`, `fireproof.username`, and feature flags
- **Module organization**: `modules/` contains themed directories (`base/`, `desktop/`, `programs/`, `homelab/`, `system/`, `scripts/`)
- **Host configuration flow**: `hosts/default.nix` defines `mkSystem` which imports all module directories plus the specific host
``` ### The `fireproof` Options System
modules/
├── base/ # Core: fireproof options, secrets, home-manager integration
├── desktop/ # Desktop environment (niri WM, greetd, audio, fonts)
├── homelab/ # Self-hosted services (nginx, postgres, arr stack, etc.)
├── programs/ # User applications (ghostty, neovim, vscode, etc.)
└── system/ # System config (boot, networking, ssh, tailscale)
```
### Host Configuration Pattern All custom options live under `fireproof.*`. Key options:
Each host in `hosts/<hostname>/` sets `fireproof.*` options to enable feature groups:
```nix ```nix
# hosts/desktop/default.nix fireproof.hostname = "desktop"; # Required per host
config.fireproof = { fireproof.username = "nickolaj"; # Required per host
hostname = "desktop"; fireproof.desktop.enable = true; # Enables niri + desktop modules
username = "nickolaj"; fireproof.homelab.enable = true; # Enables server services
desktop.enable = true; # Enables all desktop modules fireproof.work.enable = true; # Work-related tools
work.enable = true; # Enables work-related programs fireproof.dev.enable = true; # Development tools
dev.enable = true; # Enables development tools
};
```
### Key Pattern: Feature Modules with `lib.mkIf`
Modules conditionally apply based on `fireproof.*` flags:
```nix
# Module pattern - check enabling flag first
{config, lib, ...}: {
config = lib.mkIf config.fireproof.desktop.enable {
# Configuration only applied when desktop is enabled
};
}
``` ```
### Home Manager Integration ### Home Manager Integration
Use `fireproof.home-manager` instead of `home-manager.users.<user>`: Use `fireproof.home-manager` instead of `home-manager.users.<username>`:
```nix ```nix
# Correct: Uses fireproof wrapper # Correct pattern (from modules/programs/ghostty.nix)
fireproof.home-manager = { fireproof.home-manager.programs.ghostty.enable = true;
programs.ghostty.enable = true;
};
# Incorrect: Don't use directly # NOT: home-manager.users.nickolaj.programs...
home-manager.users.nickolaj = { ... };
``` ```
## Developer Commands ### Theme System
All operations use **just** - run `just` for command list: Colors are defined in `modules/base/theme.nix` under `config.fireproof.theme.colors.*`. Access them as:
```nix
let c = config.fireproof.theme.colors;
in {
background = c.bg; # No # prefix in the option
border = "#${c.accent}"; # Add # when needed
}
```
## Developer Workflow
Use `just` for all operations:
```bash ```bash
just switch # Rebuild current host just switch # Rebuild current host
just switch homelab 10.0.0.11 # Deploy to remote host just switch desktop <IP> # Rebuild specific host
just build-system desktop # Build without switching just update nixpkgs # Update single input
just diff # Compare changes before switching just diff # Preview changes before switching
nix fmt # Format with alejandra, deadnix, statix
just secret-edit <name> # Edit encrypted secret
just secret-rekey # Rekey after adding hosts/secrets
just new-host <hostname> <user> # Bootstrap new host config
``` ```
## Secret Management ## Secret Management
Secrets use **agenix-rekey** with YubiKey master identity: Secrets use agenix + agenix-rekey with YubiKey master identity:
- Global secrets: `secrets/*.age` - Global secrets: `secrets/*.age`
- Host-specific: `secrets/hosts/<hostname>/` (includes rekeyed secrets in `.rekey/`) - Per-host secrets: `secrets/hosts/<hostname>/`
- Reference secrets via `config.age.secrets.<name>.path` - Host keys are in `secrets/hosts/<hostname>/id_ed25519.{pub,age}`
- Rekey after adding hosts/secrets: `just secret-rekey`
```nix ## Adding New Features
# Declaring a secret in a module
age.secrets.my-secret.rekeyFile = ../../secrets/hosts/homelab/my-secret.age;
# Using the decrypted path 1. **New program**: Create `modules/programs/<name>.nix`, guard with `lib.mkIf config.fireproof.desktop.enable` or similar
services.myapp.environmentFile = config.age.secrets.my-secret.path; 2. **New homelab service**: Create `modules/homelab/<name>.nix`, add to `modules/homelab/default.nix` imports
``` 3. **New host**: Run `just new-host <hostname> <username>`, then add to `hosts/default.nix`
## Code Style
- **Formatter**: `nix fmt` (alejandra + deadnix + statix)
- **nixpkgs-unstable**: Available as `pkgsUnstable` in module arguments
- **Theme colors**: Flexoki palette defined in README.md - use consistent HSL/Hex values
## Common Patterns ## Common Patterns
### Adding a new program module ### Conditional Module Loading
1. Create `modules/programs/myapp.nix`
2. Guard with appropriate enable flag
3. Import in `modules/programs/default.nix`
```nix ```nix
# modules/programs/myapp.nix {config, lib, ...}: {
{config, lib, pkgs, ...}: { config = lib.mkIf config.fireproof.desktop.enable {
config = lib.mkIf config.fireproof.dev.enable { # Desktop-only configuration
environment.systemPackages = [pkgs.myapp];
fireproof.home-manager.programs.myapp = { ... };
}; };
} }
``` ```
### Adding a homelab service ### Using Unstable Packages
1. Create `modules/homelab/myservice.nix` `pkgsUnstable` is available via `specialArgs` when packages need bleeding-edge versions.
2. Guard with `lib.mkIf config.fireproof.homelab.enable`
3. Add nginx virtualHost for HTTPS proxy
4. Import in `modules/homelab/default.nix`
5. Update `glance.nix` for dashboard link
### Hardware config ### Hardware Config
Use `just factor <hostname>` to generate `facter.json` for hardware detection (replaces nixos-generate-config). Use `facter.reportPath = ./facter.json;` in host config; generate with `just factor <hostname>`.