304 lines
9.6 KiB
Markdown
Executable File
304 lines
9.6 KiB
Markdown
Executable File
# Agent Guide
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
/etc/nixos/
|
|
├── flake.nix # Main flake configuration
|
|
├── flake.lock # Locked versions
|
|
├── AGENTS.md # This file
|
|
├── treefmt.nix # Code formatting config
|
|
├── qemu.nix # QEMU testing config
|
|
│
|
|
├── systems/ # System configurations by architecture
|
|
│ ├── aarch64-linux/
|
|
│ │ ├── macbook-pro-nixos/ # Apple Silicon MacBook
|
|
│ │ │ ├── default.nix
|
|
│ │ │ ├── boot.nix
|
|
│ │ │ ├── services.nix # logind, gdm, gnome, flatpak, etc.
|
|
│ │ │ ├── filesystems.nix
|
|
│ │ │ ├── hardware-configuration.nix
|
|
│ │ │ └── firmware/ # Asahi firmware
|
|
│ │ └── pi5/ # Raspberry Pi 5
|
|
│ │ ├── default.nix
|
|
│ │ ├── boot.nix
|
|
│ │ ├── adguard.nix
|
|
│ │ └── sops.nix
|
|
│ ├── x86_64-linux/
|
|
│ │ ├── matt-nixos/ # Desktop AMD system
|
|
│ │ │ ├── default.nix
|
|
│ │ │ ├── boot.nix
|
|
│ │ │ ├── filesystems.nix
|
|
│ │ │ ├── sops.nix
|
|
│ │ │ └── services/
|
|
│ │ │ ├── lsfg-vk/
|
|
│ │ │ ├── ratbagd/
|
|
│ │ │ └── restic/
|
|
│ │ ├── allyx/ # ASUS ROG Ally X
|
|
│ │ │ ├── default.nix
|
|
│ │ │ └── boot.nix
|
|
│ │ ├── nuc-nixos/ # Intel NUC
|
|
│ │ ├── jallen-nas/ # NAS server
|
|
│ │ └── iso-minimal/
|
|
│ └── aarch64-darwin/
|
|
│ └── macbook-pro/ # macOS (nix-darwin)
|
|
│
|
|
├── homes/ # Home-manager configurations
|
|
│ ├── aarch64-linux/
|
|
│ │ └── matt@macbook-pro-nixos/
|
|
│ │ └── default.nix
|
|
│ ├── x86_64-linux/
|
|
│ └── aarch64-darwin/
|
|
│
|
|
├── modules/ # Shared modules
|
|
│ ├── nixos/ # NixOS system modules
|
|
│ ├── home/ # Home-manager modules
|
|
│ └── darwin/ # nix-darwin modules
|
|
│
|
|
├── packages/ # Custom package overlays
|
|
│ ├── omnissa/
|
|
│ ├── bcachefs/
|
|
│ ├── raspberrypi/
|
|
│ ├── comfyui/
|
|
│ ├── homeassistant/
|
|
│ ├── librepods-beta/
|
|
│ └── ...
|
|
│
|
|
└── secrets/ # SOPS secrets
|
|
├── secrets.yaml # Master key config
|
|
└── *-secrets.yaml # Per-host secrets
|
|
```
|
|
|
|
## System Configurations
|
|
|
|
### macbook-pro-nixos (Apple Silicon MacBook)
|
|
- **Path**: `systems/aarch64-linux/macbook-pro-nixos/`
|
|
- **Key files**:
|
|
- `services.nix:72-81` - logind/sleep settings
|
|
- `default.nix` - main config, imports all parts
|
|
- `boot.nix` - systemd-boot, kernel params
|
|
- **Features**: Asahi Linux, GNOME, Hyprland option, battery management
|
|
|
|
### matt-nixos (AMD Desktop)
|
|
- **Path**: `systems/x86_64-linux/matt-nixos/`
|
|
- **Features**: AMD GPU (LACT), GNOME, gaming, Lanzaboote
|
|
|
|
### allyx (ASUS ROG Ally X)
|
|
- **Path**: `systems/x86_64-linux/allyx/`
|
|
- **Features**: Jovian NixOS, Steam, handheld-daemon, AMD GPU
|
|
|
|
### pi5 (Raspberry Pi 5)
|
|
- **Path**: `systems/aarch64-linux/pi5/`
|
|
- **Features**: Headless, AdGuard, Docker, static IP, UEFI boot
|
|
|
|
### jallen-nas (NAS Server)
|
|
- **Path**: `systems/x86_64-linux/jallen-nas/`
|
|
- **Features**: Headless, VPN, bcachefs, restic backups
|
|
|
|
## NixOS Modules (`modules/nixos/`)
|
|
|
|
### Desktop Environments
|
|
- `desktop/gnome/default.nix` - GNOME configuration
|
|
- `desktop/hyprland/default.nix` - Hyprland configuration
|
|
- `desktop/cosmic/default.nix` - Cosmic DE configuration
|
|
|
|
### Hardware
|
|
- `hardware/amd/default.nix` - AMD GPU (LACT)
|
|
- `hardware/nvidia/default.nix` - NVIDIA GPU
|
|
- `hardware/battery/default.nix` - Battery management
|
|
- `hardware/raspberry-pi/` - Raspberry Pi support
|
|
|
|
### Boot & System
|
|
- `boot/common/` - Common boot settings
|
|
- `boot/lanzaboote/` - Lanzaboote (secure boot)
|
|
- `boot/systemd-boot/` - Systemd-boot config
|
|
- `boot/plymouth/` - Plymouth splash screen
|
|
|
|
### Networking
|
|
- `network/default.nix` - Network configuration (hostname, firewall, NM)
|
|
- `network/options.nix` - Network module options
|
|
|
|
### Other Services
|
|
- `headless/default.nix` - Headless server config (watchdog, no suspend)
|
|
- `gaming/default.nix` - Steam, Gamescope, Gamemode
|
|
- `programs/default.nix` - System programs (nix-index, gnupg, etc.)
|
|
|
|
## Home-Manager Modules (`modules/home/`)
|
|
|
|
### Programs
|
|
- `programs/waybar/` - Wayland bar
|
|
- `programs/hyprland/` - Hyprland config
|
|
- `programs/kitty/` - Kitty terminal
|
|
- `programs/wofi/` - Wofi launcher
|
|
- `programs/wlogout/` - Logout menu
|
|
- `programs/btop/` - System monitor
|
|
- `programs/git/` - Git configuration
|
|
- `programs/zsh/` - Zsh configuration
|
|
- `programs/mako/` - Notification daemon
|
|
|
|
### Desktop
|
|
- `desktop/gnome/` - GNOME settings
|
|
- `desktop/stylix/` - Stylix theming
|
|
|
|
### Services
|
|
- `services/sops/` - SOPS integration
|
|
|
|
## Custom Packages (`packages/`)
|
|
|
|
- `omnissa/` - Omnissa Horizon client
|
|
- `bcachefs/` - Bcachefs tools
|
|
- `raspberrypi/` - Raspberry Pi firmware/tools
|
|
- `comfyui/` - ComfyUI packages
|
|
- `homeassistant/` - Home Assistant components
|
|
- `librepods-beta/` - LibrePODS beta (AirPods support)
|
|
|
|
## Common Patterns
|
|
|
|
### Enable a desktop environment
|
|
```nix
|
|
${namespace}.desktop.gnome.enable = true;
|
|
${namespace}.desktop.hyprland.enable = true;
|
|
```
|
|
|
|
### Enable SOPS
|
|
```nix
|
|
${namespace}.sops.enable = true;
|
|
```
|
|
|
|
### Enable headless mode
|
|
```nix
|
|
${namespace}.headless.enable = true;
|
|
```
|
|
|
|
### System imports
|
|
```nix
|
|
imports = [
|
|
./boot.nix
|
|
./filesystems.nix
|
|
./hardware-configuration.nix
|
|
./services.nix
|
|
];
|
|
```
|
|
|
|
### Namespace options (flake.nix:253)
|
|
```nix
|
|
namespace = "mjallen";
|
|
```
|
|
|
|
## SOPS Secrets
|
|
|
|
Secrets are encrypted with SOPS. Each system has its own secrets file:
|
|
- `secrets/mac-secrets.yaml` - macbook-pro-nixos
|
|
- `secrets/pi5-secrets.yaml` - pi5
|
|
- `secrets/allyx-secrets.yaml` - allyx
|
|
- `secrets/nuc-secrets.yaml` - nuc-nixos
|
|
- `secrets/nas-secrets.yaml` - jallen-nas
|
|
|
|
## Flake Inputs (flake.nix)
|
|
|
|
Key inputs:
|
|
- `nixpkgs-unstable` - Unstable channel
|
|
- `nixpkgs-stable` - Stable channel (25.11)
|
|
- `home-manager-unstable` - Home-manager
|
|
- `nixos-apple-silicon` - Apple Silicon support
|
|
- `nixos-hardware` - Common hardware configs
|
|
- `disko` - Disk partitioning
|
|
- `sops-nix` - Secrets management
|
|
- `lanzaboote` - Secure boot
|
|
- `jovian` - Steam Deck support (allyx)
|
|
|
|
## Lib Module (`lib/`)
|
|
|
|
Custom utility library exposed via `lib.mjallen.*` through Snowfall Lib. Used for creating modules and managing versions.
|
|
|
|
### Directory Structure
|
|
```
|
|
lib/
|
|
├── default.nix # Entry point: exports module, file, versioning
|
|
├── README.md # Detailed documentation
|
|
├── module/ # Module creation helpers
|
|
│ └── default.nix
|
|
├── file/ # File/path utilities
|
|
│ └── default.nix
|
|
└── versioning/ # Multi-source version pinning
|
|
└── default.nix
|
|
```
|
|
|
|
### Module Utilities (`lib.mjallen.module`)
|
|
|
|
**`mkModule`** - Create NixOS service modules with standardized options:
|
|
```nix
|
|
lib.mjallen.module.mkModule {
|
|
config, name, description, options, moduleConfig, domain ? "services"
|
|
}
|
|
```
|
|
Standard options: `enable`, `port`, `reverseProxy`, `firewall`, `createUser`, `configureDb`, `redis`, `puid`, `pgid`, `timeZone`, etc.
|
|
|
|
**`mkContainerService`** - For Podman/OCI containers (auto-generates container definition):
|
|
```nix
|
|
lib.mjallen.module.mkContainerService {
|
|
config, name, image, internalPort, description, options, volumes, environment
|
|
}
|
|
```
|
|
|
|
**`mkSopsEnvFile`** - Generate SOPS secrets + template env-file:
|
|
```nix
|
|
lib.mjallen.module.mkSopsEnvFile {
|
|
secrets, name, content, restartUnit, owner, group, mode, sopsFile
|
|
}
|
|
```
|
|
|
|
**Option Helpers:**
|
|
- `mkOpt type default description` - Standard option
|
|
- `mkBoolOpt default description` - Boolean option
|
|
- `mkReverseProxyOpt name` - Caddy reverse proxy sub-options
|
|
|
|
**Convenience Shorthands:**
|
|
- `enabled` = `{ enable = true; }`
|
|
- `disabled` = `{ enable = false; }`
|
|
|
|
### Home Manager Utilities
|
|
|
|
**`mkHomeModule`** - Create Home Manager modules:
|
|
```nix
|
|
lib.mjallen.module.mkHomeModule {
|
|
config, domain, name, description, options, moduleConfig
|
|
}
|
|
```
|
|
|
|
### File Utilities (`lib.mjallen.file`)
|
|
|
|
- `readFile path` - Read file contents
|
|
- `pathExists path` - Check if path exists
|
|
- `safeImport path default` - Safe Nix import
|
|
- `getFile relativePath` - Get path relative to flake root
|
|
- `importModulesRecursive path` - Recursively discover Nix modules
|
|
- `scanSystems systemsPath` - Discover system configurations
|
|
- `filterNixOSSystems systems` - Filter for Linux systems
|
|
- `filterDarwinSystems systems` - Filter for macOS systems
|
|
- `scanHomes homesPath` - Parse home-manager configurations
|
|
|
|
### Versioning Utilities (`lib.mjallen.versioning`)
|
|
|
|
For packages with `version.json` (multi-variant source pinning):
|
|
|
|
- `selectVariant spec variantName system` - Select variant from spec
|
|
- `render value variables` - Template substitution (`${var}`)
|
|
- `mkSrc pkgs comp variables` - Build single source
|
|
- `mkAllSources pkgs selected` - Build all sources for selected variant
|
|
|
|
See `lib/versioning/default.nix` for full API and `docs/version.schema.json` for schema.
|
|
|
|
### Usage in Packages
|
|
|
|
Create `packages/<name>/version.json` with variant definitions, then use:
|
|
```nix
|
|
let
|
|
versioning = inputs.self.lib.mjallen.versioning;
|
|
spec = inputs.self.lib.mjallen.file.readFile ./version.json;
|
|
selected = versioning.selectVariant spec variantName system;
|
|
sources = versioning.mkAllSources pkgs selected;
|
|
in
|
|
# Use sources.componentName for each source
|
|
```
|