nix-config/README.md

Bos55 Homelab (NixOS + Proxmox GitOps)

This repository contains the declarative infrastructure-as-code for the Bos55 Homelab. It leverages NixOS, Flakes, Terraform, and a custom native pull-based GitOps architecture to fully automate the provisioning, configuration, and maintenance of a home server environment.

Goals & Philosophy

The primary goal of this project is Zero-Login. Servers should be treated as cattle, not pets. If a configuration needs to change, it must be changed in this repository.

• Declarative Infrastructure: Every application, user, reverse proxy rule, and network configuration is defined declaratively using custom NixOS modules.
• Autonomous Pull-Based Deployments: Nodes autonomously pull updates from this repository via a custom homelab.gitops systemd service, securely offloading compilation to a dedicated Build farm.
• Instant Webhooks: Merging a Pull Request instantly triggers deployments across the cluster via cryptographic webhooks.
• Micro-segmented Security: Ephemeral staging environments are completely isolated from production datasets using Proxmox hypervisor-level firewalls.
• Secret Management: Strict separation between production and staging secrets using sops-nix and age.

Quickstart

If you are setting up this repository from scratch, you must perform the initial bootstrap before the automated pipelines can function.

1. Bootstrap Keys: Follow the BOOTSTRAP.md guide to generate your offline age master keys and configure Proxmox API access.
2. Deploy Builder: Ensure the dedicated Nix Builder host is running so other nodes can securely offload package compilation.
3. Commit & Push: Make your configuration changes to flake.nix or the hosts/ directory, and push to the v2 branch.
4. Autonomous Deployment: The nodes will automatically fetch the new hash and apply the configuration.

Documentation

• Bootstrap Guide - Initial setup instructions.
• Disaster Recovery - Protocols for handling hardware freezes and ZFS corruption.