From 86b42b7f258b4efe8d320fb5b12ef53485cfe5d8 Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Wed, 22 Jul 2026 21:23:39 +0200 Subject: [PATCH] docs: update README with project goals and quickstart --- README.md | 46 ++++++++++++++++++++-------------------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index cfdb027..f2b7c8a 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,28 @@ -# NixOS GitOps Migration (v2) +# Bos55 Homelab (NixOS + Proxmox GitOps) -This branch contains the automated, pull-based GitOps architecture using `comin`, Terraform, and Forgejo. +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. -> [!IMPORTANT] -> **Getting Started:** If you are setting up this repository from scratch, you **must** follow the steps in [BOOTSTRAP.md](file:///c:/Users/tibod/Documents/projects/Bos55/nix-config/BOOTSTRAP.md) before the automated pipelines can function. +## Goals & Philosophy -## Secret Management (SOPS-Nix) +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. -This repository uses `sops-nix` for secret management, adhering to a strict separation between Production and Staging environments to prevent credential leakage during CI runs. +* **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`. -### Production Keys -* **`prod-master`**: This is the ultimate master key for production secrets. - * **Best Practice**: The private key is **NEVER** stored on any server (including the Control Center VM). It is kept locally on a securely backed-up USB key and a paper backup. - * You only import the private key to your local machine temporarily when you need to encrypt a new secret or during a disaster recovery scenario. -* **Host Keys**: Production VMs use their individual SSH host keys (generated during provisioning) to decrypt their specific secrets at boot time. +## Quickstart -### Staging Keys -* **`staging-master`**: This key is used exclusively for encrypting secrets inside the `secrets/staging/` directory. - * The public key is in `.sops.yaml`. - * The private key is stored securely in Forgejo Secrets. - * During CI runs, the Forgejo Runner injects this private key into the ephemeral Staging VMs via Cloud-Init. - * Even if this key is compromised, it cannot decrypt production data. +If you are setting up this repository from scratch, you **must** perform the initial bootstrap before the automated pipelines can function. -### Generating the Master Keys -To generate your master keys (run this on your secure local workstation): -```bash -# Generate the prod-master key (save the private key to your USB drive) -age-keygen -o prod-master.txt +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. -# Generate the staging-master key (upload the private key to Forgejo Secrets) -age-keygen -o staging-master.txt -``` -Update `.sops.yaml` with the public keys outputted by these commands. +## Documentation + +* [Bootstrap Guide](./BOOTSTRAP.md) - Initial setup instructions. +* [Disaster Recovery](./DISASTER_RECOVERY.md) - Protocols for handling hardware freezes and ZFS corruption.