NixOS Homelab Documentation¶

Welcome to the documentation for a declarative NixOS homelab configuration. This repository manages multiple NixOS hosts, macOS systems via nix-darwin, and user environments with Home Manager—all using Nix flakes.

Quick Links¶

- :material-rocket-launch: **[Getting Started](bootstrap-quickstart.md)** Bootstrap a new host or get up and running quickly - :material-sitemap: **[Architecture](repository-architecture.md)** Understand the repository structure and design decisions - :material-puzzle: **[Patterns](modular-design-patterns.md)** Learn the standardized patterns for service modules - :material-backup-restore: **[Operations](backup-system-onboarding.md)** Backup, disaster recovery, and operational procedures

Repository Overview¶

nix-config/
├── flake.nix              # Flake entry point
├── lib/                   # Shared library functions (mylib)
├── modules/               # Reusable NixOS/Darwin modules
│   ├── nixos/services/    # Service modules
│   └── nixos/storage/     # ZFS dataset management
├── hosts/                 # Host-specific configurations
│   ├── forge/             # Primary homelab server
│   └── luna/              # Secondary server
├── home/                  # Home Manager configurations
└── docs/                  # This documentation

Core Principles¶

1. Declarative Configuration¶

Everything is defined in Nix. No manual steps, no imperative configuration. The entire system state is reproducible from the flake.

2. Contribution Pattern¶

Services declare their infrastructure needs (storage, backup, monitoring). Infrastructure modules aggregate these contributions. See ADR-001.

3. Native Over Containers¶

Prefer NixOS service modules over containerized implementations when available. Containers are a last resort. See ADR-005.

4. Co-located Configuration¶

Service configuration, storage datasets, backup policies, and alerts are co-located in the same file. Related concerns stay together.

Key Hosts¶

Host	Role	Architecture
forge	Primary homelab server	Two-disk ZFS, tank pool for services
luna	Secondary server	Single-disk, impermanent root

Architecture Decision Records¶

This repository maintains ADRs documenting significant design choices:

ADR	Decision
001	Services declare needs; infrastructure aggregates
002	Parameterized factory for host-specific helpers
003	Centralized type definitions via `mylib.types`
004	Hosts control persistence, not modules
005	Prefer native NixOS modules over containers
006	Gatus for availability, Prometheus for internals
007	Preseed with Syncoid → Local priority
008	OIDC → Headers → Disable+Caddy priority
009	Lightweight stack modules without re-exposure

Common Tasks¶

Build a Host¶

task nix:build-forge

Apply Configuration¶

task nix:apply-nixos host=forge NIXOS_DOMAIN=holthome.net

Check Flake¶

nix flake check

Available Tasks¶

task --list

Contributing¶

Before making changes:

Read the Modular Design Patterns
Review relevant ADRs
Study existing service modules (sonarr, radarr, dispatcharr)
Follow the Monitoring Strategy for observability

License¶

This configuration is open source. See the repository for license details.