mirror of
https://github.com/nickolaj-jepsen/nixos.git
synced 2026-01-22 16:16:50 +01:00
128 lines
3.8 KiB
Markdown
128 lines
3.8 KiB
Markdown
# NixOS Configuration - AI Assistant Instructions
|
|
|
|
## Architecture Overview
|
|
|
|
This is a **NixOS flake-based configuration** managing multiple hosts (desktop, laptop, homelab, work, WSL) with:
|
|
- **flake-parts** for modular flake organization
|
|
- **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
|
|
|
|
```
|
|
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
|
|
|
|
Each host in `hosts/<hostname>/` sets `fireproof.*` options to enable feature groups:
|
|
|
|
```nix
|
|
# hosts/desktop/default.nix
|
|
config.fireproof = {
|
|
hostname = "desktop";
|
|
username = "nickolaj";
|
|
desktop.enable = true; # Enables all desktop modules
|
|
work.enable = true; # Enables work-related programs
|
|
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
|
|
|
|
Use `fireproof.home-manager` instead of `home-manager.users.<user>`:
|
|
|
|
```nix
|
|
# Correct: Uses fireproof wrapper
|
|
fireproof.home-manager = {
|
|
programs.ghostty.enable = true;
|
|
};
|
|
|
|
# Incorrect: Don't use directly
|
|
home-manager.users.nickolaj = { ... };
|
|
```
|
|
|
|
## Developer Commands
|
|
|
|
All operations use **just** - run `just` for command list:
|
|
|
|
```bash
|
|
just switch # Rebuild current host
|
|
just switch homelab 10.0.0.11 # Deploy to remote host
|
|
just build-system desktop # Build without switching
|
|
just diff # Compare changes before switching
|
|
|
|
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
|
|
|
|
Secrets use **agenix-rekey** with YubiKey master identity:
|
|
- Global secrets: `secrets/*.age`
|
|
- Host-specific: `secrets/hosts/<hostname>/` (includes rekeyed secrets in `.rekey/`)
|
|
- Reference secrets via `config.age.secrets.<name>.path`
|
|
|
|
```nix
|
|
# Declaring a secret in a module
|
|
age.secrets.my-secret.rekeyFile = ../../secrets/hosts/homelab/my-secret.age;
|
|
|
|
# Using the decrypted path
|
|
services.myapp.environmentFile = config.age.secrets.my-secret.path;
|
|
```
|
|
|
|
## 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
|
|
|
|
### Adding a new program module
|
|
|
|
1. Create `modules/programs/myapp.nix`
|
|
2. Guard with appropriate enable flag
|
|
3. Import in `modules/programs/default.nix`
|
|
|
|
```nix
|
|
# modules/programs/myapp.nix
|
|
{config, lib, pkgs, ...}: {
|
|
config = lib.mkIf config.fireproof.dev.enable {
|
|
environment.systemPackages = [pkgs.myapp];
|
|
fireproof.home-manager.programs.myapp = { ... };
|
|
};
|
|
}
|
|
```
|
|
|
|
### Adding a homelab service
|
|
|
|
1. Create `modules/homelab/myservice.nix`
|
|
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
|
|
|
|
Use `just factor <hostname>` to generate `facter.json` for hardware detection (replaces nixos-generate-config).
|