From 6ac20b65f4dfce0433ac4f8d5c3f97a1ac1ce94c Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Mon, 29 Dec 2025 18:55:52 +0100 Subject: [PATCH] AGENTS.md: add hierarchical documentation for hosts, home, features, services --- AGENTS.md | 48 ++++++++++++++++++++--- home/AGENTS.md | 51 ++++++++++++++++++++++++ home/features/AGENTS.md | 64 +++++++++++++++++++++++++++++++ hosts/AGENTS.md | 64 +++++++++++++++++++++++++++++++ hosts/m3-atlas/services/AGENTS.md | 63 ++++++++++++++++++++++++++++++ 5 files changed, 284 insertions(+), 6 deletions(-) create mode 100644 home/AGENTS.md create mode 100644 home/features/AGENTS.md create mode 100644 hosts/AGENTS.md create mode 100644 hosts/m3-atlas/services/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index c31d4f0..cadf74f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,23 @@ # AGENTS.md - NixOS Configuration Repository -This document provides guidelines for AI agents working on this NixOS flake configuration. - -## Repository Overview +**Generated:** 2025-12-29 | **Branch:** master | **Commit:** 460fc92 Multi-host NixOS flake managing servers and workstations with home-manager integration. -- **Hosts**: m3-aether, m3-ares, m3-atlas, m3-helios, m3-kratos -- **User**: m3tam3re -- **Key inputs**: nixpkgs (unstable), home-manager, agenix, disko, nix-colors + +## Host Inventory + +| Host | Type | Purpose | Key Services | +|------|------|---------|--------------| +| m3-atlas | VPS | Main server | Traefik, containers (n8n, ghost, baserow, vaultwarden, paperless, gitea) | +| m3-helios | VPS | DNS/Dashboard | AdGuard Home, Homarr, Traefik | +| m3-ares | Workstation | Desktop | WireGuard VPN, Tailscale, sound, podman | +| m3-kratos | Workstation | Desktop | WireGuard VPN, Tailscale, Hyprland, gaming | +| m3-aether | VM | Cloud-init | Minimal config | +| m3-daedalus | - | Home-manager only | Desktop environment (no NixOS config) | + +## Key Inputs + +nixpkgs (unstable), nixpkgs-stable (25.05), home-manager, agenix, disko, nix-colors, m3ta-nixpkgs (private fork) ## Build/Rebuild Commands @@ -245,3 +255,29 @@ Short, descriptive messages: - `+package` - Adding new package - `service-name: description` - Service changes - `host: description` - Host-specific changes + +## Container IP Registry (m3-atlas) + +Network: `10.89.0.0/24`, Gateway: `10.89.0.1` (postgres host) + +| Service | IP | Port | +|---------|-----|------| +| baserow | 10.89.0.4 | 3001 | +| ghost | 10.89.0.10 | 3002 | +| slash | 10.89.0.11 | 3010 | +| littlelink | 10.89.0.13 | 3004 | +| n8n | 10.89.0.14 | 5678 | +| restreamer | 10.89.0.15 | 3006 | +| kestra | 10.89.0.17 | 3018 | +| pangolin | 10.89.0.20 | 3020 | + +**Next available IP**: 10.89.0.22 + +## Feature Flags + +Home-manager features use `mkEnableOption` pattern: +- `features.cli.*` - Shell tools (nushell, fzf, nitch, starship, secrets) +- `features.desktop.*` - GUI apps (crypto, coding, gaming, hyprland, media, office, rofi, fonts, wayland) +- `extraServices.*` - NixOS services (ollama, podman, flatpak, virtualisation) + +Enable in per-host configs: `features.cli.nushell.enable = true;` diff --git a/home/AGENTS.md b/home/AGENTS.md new file mode 100644 index 0000000..928993e --- /dev/null +++ b/home/AGENTS.md @@ -0,0 +1,51 @@ +# home/ - Home Manager Configurations + +User-level configurations managed by home-manager. + +## Structure + +``` +home/ +├── common/ # Shared home-manager config +│ └── default.nix # Overlays, nix-colors, allowUnfree +├── features/ # Modular, toggle-able features +│ ├── cli/ # Shell tools (see features/AGENTS.md) +│ ├── coding/ # Dev tools +│ └── desktop/ # GUI, Hyprland, theming +└── m3tam3re/ # Per-host user configs + ├── home.nix # Shared user config (git, ssh, packages) + └── m3-.nix # Host-specific (imports features, monitor layouts) +``` + +## Per-Host Config Pattern + +Each `m3-.nix`: +1. Imports `../common`, `./home.nix`, and needed `../features/*` +2. Enables specific features via `features...enable` +3. Overrides host-specific settings (monitors, default apps) + +Example: +```nix +{ + imports = [../common ./home.nix ../features/cli ../features/desktop]; + + features.cli.nushell.enable = true; + features.desktop.hyprland.enable = true; + + wayland.windowManager.hyprland.settings.monitor = ["DP-1,2560x1440,0x0,1"]; +} +``` + +## Theming + +Uses nix-colors (Dracula scheme). Access colors: +```nix +"#${config.colorScheme.palette.base00}" # Background +"#${config.colorScheme.palette.base05}" # Foreground +``` + +## Adding New User Config + +1. Create `m3tam3re/m3-.nix` +2. Import needed features +3. Add to `flake.nix` homeConfigurations (standalone) or host's home-manager.users diff --git a/home/features/AGENTS.md b/home/features/AGENTS.md new file mode 100644 index 0000000..5f5d879 --- /dev/null +++ b/home/features/AGENTS.md @@ -0,0 +1,64 @@ +# features/ - Modular Home Manager Features + +Toggle-able feature modules using `mkEnableOption` pattern. + +## Structure + +``` +features/ +├── cli/ # Shell & terminal tools +│ ├── default.nix # Always-on CLI tools (bat, eza, direnv, carapace) +│ ├── nushell.nix # features.cli.nushell.enable +│ ├── fzf.nix # features.cli.fzf.enable +│ ├── starship.nix # features.cli.starship.enable +│ ├── zellij.nix # Always-on zellij config +│ └── secrets.nix # features.cli.secrets.enable +├── coding/ # Dev tools +│ └── default.nix # features.coding.* (zed, neovim) +└── desktop/ # GUI applications + ├── default.nix # Always-on (kitty, xdg, cursor) + ├── hyprland.nix # features.desktop.hyprland.enable + ├── gaming.nix # features.desktop.gaming.enable + ├── media.nix # features.desktop.media.enable + └── ... +``` + +## Creating a New Feature + +1. Create `/.nix`: +```nix +{config, lib, ...}: +with lib; let + cfg = config.features..; +in { + options.features...enable = + mkEnableOption "description"; + + config = mkIf cfg.enable { + # Configuration when enabled + }; +} +``` + +2. Import in `/default.nix` +3. Enable in user configs: `features...enable = true;` + +## Feature Categories + +| Category | Purpose | Key features | +|----------|---------|--------------| +| cli | Shell tools | nushell, fzf, starship, nitch, secrets | +| coding | Development | (in default.nix, no sub-features yet) | +| desktop | GUI/WM | hyprland, gaming, media, office, crypto, fonts, rofi, wayland | + +## Always-On vs Toggle-able + +- **default.nix**: Configuration that applies when the category is imported (no enable flag) +- **.nix**: Must be explicitly enabled via `features.*.enable = true` + +## Desktop Feature Details + +- `hyprland.nix`: Window manager config, keybinds, window rules (host overrides monitors/workspaces) +- `gaming.nix`: Steam, gamemode, mangohud +- `media.nix`: mpv, obs-studio, spotify +- `wayland.nix`: Clipboard, screenshots, idle management diff --git a/hosts/AGENTS.md b/hosts/AGENTS.md new file mode 100644 index 0000000..c7c88eb --- /dev/null +++ b/hosts/AGENTS.md @@ -0,0 +1,64 @@ +# hosts/ - NixOS Host Configurations + +Host-specific NixOS system configurations. Each `m3-*` directory is a complete host. + +## Structure + +``` +hosts/ +├── common/ # Shared by ALL hosts +│ ├── extraServices/ # Toggle-able services (ollama, podman, flatpak) +│ ├── users/ # User definitions +│ ├── ports.nix # Central port registry +│ └── default.nix # Overlays, nix settings, home-manager integration +└── m3-*/ # Per-host configurations + ├── default.nix # Entry point (imports common + enables extraServices) + ├── configuration.nix # Core system (boot, networking, stateVersion) + ├── hardware-configuration.nix + ├── programs.nix # Host-specific packages + ├── secrets.nix # Agenix secret declarations + └── services/ # Service configs + └── containers/ # OCI container definitions (m3-atlas only has many) +``` + +## Adding a New Host + +1. Create `hosts/m3-/` with required files +2. Add to `flake.nix` nixosConfigurations +3. Create matching `home/m3tam3re/m3-.nix` + +## Host Quick Reference + +| Host | extraServices | Has disko | Key services/ files | +|------|---------------|-----------|---------------------| +| m3-atlas | podman | Yes | traefik, postgres, gitea, containers/* | +| m3-helios | - | Yes | adguard, traefik, containers/homarr | +| m3-ares | podman | No | wireguard, tailscale, sound | +| m3-kratos | podman, ollama | No | wireguard, tailscale, sound | +| m3-aether | - | Yes | cloud-init (minimal) | + +## extraServices Pattern + +Enable in host's `default.nix`: +```nix +extraServices = { + podman.enable = true; + ollama.enable = true; + flatpak.enable = false; + virtualisation.enable = false; +}; +``` + +## Port Allocation + +ALWAYS check `common/ports.nix` before adding new services. Register new ports there. + +## Secrets Declaration + +Each host's `secrets.nix` declares only secrets it needs: +```nix +age.secrets.service-name = { + file = ../../secrets/service-name.age; + owner = "optional-user"; +}; +``` diff --git a/hosts/m3-atlas/services/AGENTS.md b/hosts/m3-atlas/services/AGENTS.md new file mode 100644 index 0000000..2fb7815 --- /dev/null +++ b/hosts/m3-atlas/services/AGENTS.md @@ -0,0 +1,63 @@ +# services/ - m3-atlas Service Configurations + +Main server services including Traefik reverse proxy and containerized apps. + +## Container Network + +- **Network**: `web` (podman network) +- **Subnet**: `10.89.0.0/24` +- **Gateway/Postgres**: `10.89.0.1` +- **DNS Challenge**: GoDaddy via Traefik + +## Adding a New Container + +1. Pick next available IP from registry (currently: `10.89.0.22`) +2. Register port in `hosts/common/ports.nix` +3. Create `containers/.nix`: + +```nix +{config, ...}: { + virtualisation.oci-containers.containers."service" = { + image = "registry/image:tag"; + environmentFiles = [config.age.secrets.service-env.path]; + ports = ["127.0.0.1:PORT:PORT"]; + volumes = ["service_data:/data"]; + extraOptions = [ + "--add-host=postgres:10.89.0.1" + "--ip=10.89.0.XX" + "--network=web" + ]; + }; + + services.traefik.dynamicConfigOptions.http = { + services.service.loadBalancer.servers = [{ url = "http://localhost:PORT/"; }]; + routers.service = { + rule = "Host(`service.domain.com`)"; + tls.certResolver = "godaddy"; + service = "service"; + entrypoints = "websecure"; + }; + }; +} +``` + +4. Import in `containers/default.nix` +5. Add secret to `secrets.nix` and root `secrets.nix` +6. Update IP registry in root AGENTS.md + +## Service Files (non-container) + +| File | Purpose | +|------|---------| +| traefik.nix | Reverse proxy, TLS, entrypoints | +| postgres.nix | Native PostgreSQL for containers | +| tailscale.nix | Mesh VPN | +| gitea.nix | Native Gitea (not containerized) | +| minio.nix | S3-compatible storage | + +## Traefik Patterns + +- HTTP redirect to HTTPS: automatic via `web` entrypoint +- TLS: `certResolver = "godaddy"` (DNS challenge) +- Auth middleware: `middlewares = ["auth"]` (basic auth) +- Domain redirects: See `traefik.nix` middlewares