28 lines
2.1 KiB
Markdown
28 lines
2.1 KiB
Markdown
# 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](./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](./BOOTSTRAP.md) - Initial setup instructions.
|
|
* [Disaster Recovery](./DISASTER_RECOVERY.md) - Protocols for handling hardware freezes and ZFS corruption.
|