forked from Bos55/nix-config
47 lines
2.6 KiB
Markdown
47 lines
2.6 KiB
Markdown
---
|
|
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.
|