forked from Bos55/nix-config
Tibo De Peuter
3648b4d535
Some checks failed
Build / build (Testing) (pull_request) Has been cancelled
Build / build (Development) (pull_request) Has been cancelled
Build / Determining hosts to build (pull_request) Failing after 10m10s
Build / Determining hosts to build (push) Failing after 11m10s
Build / build (Testing) (push) Failing after 13m36s
Build / build (Development) (push) Failing after 15m18s
Create a modular, context-aware style guide for AI code assistants. - Add nixos-architecture skill for .nix file generation and networking patterns - Add dns-management rule to enforce Bind9 SOA serial increments - Add cicd-networking rule for direct-IP runner authentication - Add git-workflow rule to enforce conventional and atomic commits
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
---
|
|
name: bos55-nix-architecture
|
|
description: Implementation patterns for NixOS configurations, networking, and service modules.
|
|
globs: [".nix", "hosts/**/", "modules//*", "secrets//*"]
|
|
---
|
|
|
|
# NixOS Architecture Skill
|
|
|
|
When generating or modifying NixOS configuration files for the Bos55 project, strictly adhere to the following architectural patterns:
|
|
|
|
## 1. Minimal Hardcoding & Dynamic Discovery
|
|
|
|
- **Local IP Ownership**: Define IPv4/IPv6 addresses **only** within their respective host configuration files (e.g., `hosts/<HostName>/default.nix`). Do not use global IP mapping modules.
|
|
- **Inter-Host Discovery**: Resolve a host's IP or port by evaluating its configuration at build time. Never hardcode another host's IP.
|
|
**Pattern Example**:
|
|
```
|
|
let
|
|
bcConfig = inputs.self.nixosConfigurations.BinaryCache.config;
|
|
bcIp = (pkgs.lib.head bcConfig.networking.interfaces.ens18.ipv4.addresses).address;
|
|
in "http://${bcIp}:8080"
|
|
```
|
|
- **Unified Variables**: Use local variables (e.g., `let dbName = "attic"; in ...`) for shared values between host services and containers to ensure consistency.
|
|
|
|
## 2. Modular Service Encapsulation
|
|
|
|
- **Self-Contained Modules**: Service modules (`modules/services/<service>/default.nix`) must manage their own configurations. Prefer `lib.mkOption` over hardcoded strings for domains, ports, and credentials.
|
|
- **Firewall Responsibility**: Open ports (e.g., TCP 8080, SSH 22) directly within the service module based on its own options. Do not open service ports manually in host files.
|
|
- **Remote Builders**: Define `nix.settings.trusted-users`, `builder` user, and SSH rules directly within the service module if it supports remote building (e.g., Attic).
|
|
|
|
## 3. Networking & Connectivity
|
|
|
|
- **Container-to-Host**: Host services must connect to companion containers using the container name, not the bridge IP or `localhost`.
|
|
- **Host Resolution**: Map the container name to `127.0.0.1` using `networking.extraHosts` in the host service module to route traffic seamlessly.
|
|
- **Domain Deferral**: Client modules must defer their default domain settings to the server module's defined domain option.
|
|
|
|
## 4. Secrets Management
|
|
|
|
- **Sops-Nix Exclusivity**: Manage all secrets via `sops-nix`.
|
|
- **Centralized Config**: Rely on `modules/common/default.nix` for fleet-wide settings like `defaultSopsFile` and `age.keyFile`.
|
|
- **References**: Always reference credentials dynamically using `config.sops.secrets."path/to/secret".path`.
|
|
|
|
## 5. Security & Documentation
|
|
|
|
- **Supply Chain Protection**: Always verify and lock Nix flake inputs. Use fixed-output derivations for external resource downloads.
|
|
- **Assumptions Documentation**: Clearly document environment assumptions (e.g., Proxmox virtualization, Tailscale networking, and specific IP ranges) in host or service READMEs.
|
|
- **Project Structure**: Maintain the strict separation of `hosts/`, `modules/`, `users/`, and `secrets/` to ensure clear ownership and security boundaries.
|
|
|