Bos55/nix-config
2
Fork 1
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity

docs: update README with project goals and quickstart

Browse source
This commit is contained in:
Tibo De Peuter 2026-07-22 21:23:39 +02:00
parent 78a20fbe00
commit 86b42b7f25
Signed by: tdpeuter
SSH key fingerprint: SHA256:u/h/LVoqKF1Iz02uOyxe6hcjmoZASCGV2HM0TG9ZMoU
1 changed files with 20 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

46
README.md
View file

@ -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.