---
name: bos55-nix-config
description: 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:
  ```nix
  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.