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

name	description
bos55-nix-config	Best practices and codestyle for the Bos55 NixOS configuration project.

Bos55 NixOS Configuration Skill

This skill provides the core principles and implementation patterns for the Bos55 NixOS project. Use this skill when adding new hosts, services, or networking rules.

Core Principles

1. Minimal Hardcoding

• Host IPs: Always define IPv4/IPv6 addresses within the host configuration (hosts/).
• Options: Prefer lib.mkOption over hardcoded strings for ports, domain names, and database credentials.
• Unified Variables: If a value is shared (e.g., between a PG container and a host service), define a local variable (e.g., let databaseName = "attic"; in ...) to ensure consistency.

2. Service-Driven Configuration

• Encapsulation: Service modules should manage their own firewall rules, users/groups, and SSH settings.
• Trusted Access: Use the service module to define nix.settings.trusted-users for things like remote builders.

3. Build-Time Discovery

• Inter-Host Evaluation: To avoid magic values, resolve a host's IP or port by evaluating its configuration in the flake's output:

  bcConfig = inputs.self.nixosConfigurations.BinaryCache.config;
  

• Domain Deferral: Client modules should defer their default domain settings from the server module's domain option.

Implementation Patterns

Container-Host Connectivity

• Pattern: Service on host -> Container via bridge mapping.
• Rule: Map the container name to 127.0.0.1 using networking.extraHosts to allow the host service to resolve the container by name without needing the bridge IP.

Secrets Management

• Rule: Standardize all secrets via sops-nix.
• Common Module: Ensure modules/common/default.nix handles the default sopsFile and age key configuration.

Bind9 Management

• Rule: ALWAYS increment the serial when editing zone records.

CI/CD Networking

• Rule: Use direct IPs for machine-to-machine login steps in Actions workflows to ensure reliability across different runner environments.

4. 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 separation of hosts, modules, users, and secrets to ensure clear ownership and security boundaries.

5. Git Standards

• Rule: Follow Conventional Commits (e.g., feat:, refactor:, docs:, meta:).
• Rule: Keep commits atomic and revertible. Never mix documentation, infrastructure, and style guide changes in a single commit.