Bos55 NixOS Configuration Style Guide

Follow these rules when modifying or extending the Bos55 NixOS configuration.

1. Network & IP Management

Local Ownership: Define host IP addresses only within their respective host configuration files (e.g., hosts/BinaryCache/default.nix).

Dynamic Discovery: Do NOT use global IP mapping modules. Instead, use inter-host evaluation to resolve IPs and ports at build time:

# In another host's config
let
  bcConfig = inputs.self.nixosConfigurations.BinaryCache.config;
  bcIp = (pkgs.lib.head bcConfig.networking.interfaces.ens18.ipv4.addresses).address;
in "http://${bcIp}:8080"

2. Modular Service Design

Encapsulation: Services must be self-contained. Options like openFirewall, port, and enableRemoteBuilder should live in the service module (modules/services/<service>/default.nix).
Firewall Responsibility: The service module is responsible for opening firewall ports (e.g., TCP 8080, SSH 22) based on its own options. Do not open ports manually in host files if the service provides an option.
Remote Builders: If a service like Attic supports remote building, include the builder user, trusted-users, and SSH configuration within that module's options.

3. Container Networking

Discovery by Name: Host services should connect to their companion containers (e.g., PostgreSQL) using the container name rather than localhost or bridge IPs.
Host Resolution: Use networking.extraHosts in the service module to map the container name to 127.0.0.1 on the host for seamless traffic routing.

4. Secrets Management (sops-nix)

Centralized Config: Fleet-wide sops-nix settings (like defaultSopsFile and age.keyFile) must live in modules/common/default.nix.
No Hardcoded Paths: Always use config.sops.secrets."path/to/secret".path to reference credentials.

5. DNS & DNS Zone Files

Serial Increment: Every change to a Bind9 zone file (e.g., db.depeuter.dev) MUST increment the Serial number in the SOA record.
Specific Domains: Prefer a single, well-defined domain (e.g., nix-cache.depeuter.dev) over multiple aliases or magic values.

6. CI/CD Robustness

IP-Based Login: When CI runners (Gitea Actions) need to interact with internal services, use direct IP addresses (e.g., 192.168.0.25) for login/auth to bypass potential DNS resolution issues in the runner environment.

8. Git Workflow & Commits

Atomic Commits: Each commit should represent a single logical change and be easily revertible. Split docs, metadata, and core code changes into separate commits.
Conventional Commits: Use conventional commit messages (e.g., feat:, fix:, docs:, refactor:, ci:, meta:).
Branching: Always work in feature branches and push to origin to create pull requests.

2.8 KiB Raw Permalink Blame History