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

2026-03-17 22:52:15 +01:00

2.9 KiB

Raw Blame History

name

description

globs

bos55-nix-architecture

Implementation patterns for NixOS configurations, networking, and service modules.

.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.

2.9 KiB Raw Blame History