Overview

Relevant source files

This document provides a high-level introduction to the dot.nix repository: a host-focused NixOS flake configuration that manages multiple systems and users across a homelab infrastructure. It explains the repository's purpose, architectural design, and how the major components interact.

For detailed information about specific subsystems:

Initial setup and development environment: see Getting Started
Flake structure and dependency management: see Flake Configuration and Dependency Management
Host definitions and specifications: see Host and User Definitions
Desktop environment configurations: see Desktop Environments
Infrastructure topology and networking: see Infrastructure and Networking

Purpose and Scope

dot.nix is a declarative, multi-host NixOS configuration that manages six physical hosts and two users across a homelab environment. The configuration emphasizes:

Modularity: Separation of system configurations (hosts/), user environments (home/), and reusable utilities (mix.nix)
Reproducibility: All system state is declared in version-controlled Nix expressions
Cache Coherence: Strategic derivation of nixpkgs from mix-nix to maximize binary cache hits
Security: Git-crypt encrypted secrets integrated into the build process

The repository does not contain package definitions, overlays, or library utilities—these are delegated to the external mix.nix library for clean separation of concerns.

Sources: readme.md1-18 flake.nix1-7

Repository Architecture

Entry Point and Dependency Graph

Title: Flake Architecture and Dependency Flow

The flake entry point (flake.nix) imports mix-nix as the foundational library, which provides the nixpkgs derivation used throughout the configuration. This design decision ensures that custom packages from mix.nix are served from binary caches rather than being rebuilt locally. The arroz-nix library extends mix.nix with desktop environment modules.

Sources: flake.nix1-155 readme.md15-52

Configuration Orchestration Flow

Title: Configuration Build Pipeline

The mix/default.nix file serves as the central orchestrator, declaring users and hosts which are then processed by mix.nix flake-parts modules. The hosts module auto-generates nixosConfigurations and homeConfigurations outputs, which are built into the Nix store and activated as system/user profiles.

Sources: readme.md59-68 mix/default.nix (not provided but referenced), modules/hosts/core/default.nix1-10

Core Architectural Decisions

1. nixpkgs Derivation Strategy

Rather than directly specifying nixpkgs, this configuration follows the nixpkgs input from mix-nix. This ensures that:

Custom packages built by mix.nix match the exact nixpkgs revision used here
Binary cache hits are maximized for mix.nix packages
Version consistency is maintained across the entire configuration stack

Sources: flake.nix5-7 readme.md126-129

2. Three-Tier Binary Cache Hierarchy

The binary cache strategy employs three tiers:

Local cache (cache.ryot.foo on nimbus): Checked first (priority=1) for custom packages and expensive builds
Private Cachix (psynk-private.cachix.org): For sensitive/proprietary builds (referenced in secrets)
Official cache (cache.nixos.org): Fallback for standard nixpkgs packages

The nimbus host itself excludes the local cache from its substituters to prevent circular dependencies.

Sources: modules/hosts/core/default.nix131-142 readme.md178-180

3. Module Discovery via lib.fs.scanPaths

Core modules use lib.fs.scanPaths to automatically discover and import sibling modules. This plugin-like architecture allows adding new modules without updating import lists. The same pattern is used for:

Host core modules: modules/hosts/core/
Home Manager core modules: modules/home/core/
Common modules: modules/home/common/

Sources: modules/hosts/core/default.nix24-27 modules/home/core/default.nix24-25

Infrastructure Overview

Host Inventory and Roles

Hostname	Type	Role	Hardware	Network	Services
rune	Desktop	Gaming/Dev Workstation	Ryzen 9 7900X3D, RX 9070 XT	10.4.4.4	Hyprland, Sunshine streaming, VMs
haze	Desktop	Secondary Workstation	Ryzen 5 7600x, RX 7600	10.2.2.13	GNOME, Development
norion	Laptop	Mobile Workstation	Ryzen AI 9 HX PRO 370	10.2.2.4	GNOME, Secure Boot (lanzaboote), VPN client
zebes	Server	Application Server	Ryzen 7 5700X, RX 7900 GRE	10.3.3.3	Komodo Core, MongoDB, AI (Ollama, ComfyUI)
nimbus	Server	Storage/Build Server	Ryzen 5 5600G	10.2.2.2	ZFS/BTRFS, NFS, nix-serve (port 4488), kernel-builder
nexus	Server	Router/Gateway	Intel N150 (2C), 2GB RAM	10.x.x.1	NAT, DHCP (DNSMasq), DNS (AdGuard), WireGuard VPN
caenus	VPS	Public Gateway	ARM 4vCPU, 24GB RAM	Public IP	Rathole server, Cloudflare tunnel

Sources: readme.md78-89

Network Topology to Code Mapping

Title: Network Topology Mapped to Configuration Files

Each network segment and service is defined in specific configuration files under the corresponding host directory. The hosts/<hostname>/config/ pattern contains service-specific modules that are auto-discovered via lib.fs.scanPaths.

Sources: readme.md78-89 readme.md217-225

Configuration Layer Hierarchy

System Configuration Structure

Title: NixOS Configuration Layer Hierarchy

The configuration is structured in three layers:

Core modules (modules/hosts/core/): Universally applied via mix.coreModules, containing essential settings like Nix configuration, base packages, and localization
Host-specific modules (hosts/<hostname>/): Unique configurations per host, with config/ subdirectories for service-specific settings
Common modules (modules/hosts/common/): Shared but not universal, imported selectively by hosts

Sources: modules/hosts/core/default.nix1-10 readme.md59-68

User Configuration Structure

Title: Home Manager Configuration Layer Hierarchy

User configurations follow a two-layer approach with optional overrides:

Core home modules (modules/home/core/): Universal user environment settings
Global user configs (home/users/<username>/): User-specific preferences that apply across all hosts (themes, packages)
Host-specific overrides (home/hosts/<hostname>/): Machine-specific adjustments (monitor setups, desktop-specific tweaks)
Common modules (modules/home/common/): Shared functionality imported as needed (gaming, browsers, development tools)

Sources: readme.md93-107 modules/home/core/default.nix1-10

System Management Workflow

Daily Operation via bonk

Title: System Management with bonk CLI

The bonk tool wraps common NixOS operations with sensible defaults configured in modules/hosts/core/default.nix. Key settings:

buildHost = "nimbus": Offload builds to the build server
flakePath = "/repo/Nix/dot.nix": Default configuration location
extraArgs = ["--impure"]: Allow impure evaluation for secrets

Users can override the flake path via the $FLAKE environment variable.

Sources: modules/hosts/core/default.nix29-35 readme.md301-318 devshell.nix59-60

Development Environment

The repository includes a development shell defined in devshell.nix that provides:

Tools Included:

Nix tools: nix, nixos-rebuild, home-manager
Secret management: git, git-crypt, gnupg
Network diagnostics: nmap, mtr, tcpdump, wireshark-cli
Configuration utilities: dconf2nix, compose2nix
Text editors: micro
The bonk CLI tool

Automatic Setup: