bos55-nix-config-cicd/.agent/skills/nixos-architecture/SKILL.md

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.