# Castaldi Family Homelab

> **A GitOps-managed, Ansible-automated infrastructure running media services, container orchestration, and hypervisor management across distributed ARM and x86 nodes.**

[![GitOps](https://img.shields.io/badge/GitOps-Komodo-blue?style=flat-square)](https://komo.do)
[![Automation](https://img.shields.io/badge/Automation-Ansible-red?style=flat-square)](#automation)
[![Infrastructure](https://img.shields.io/badge/Infrastructure-Multi--Node-green?style=flat-square)](#architecture)
[![Documentation](https://img.shields.io/badge/Docs-KBAs%20%2B%20SOPs-orange?style=flat-square)](documentation/)

---

## 🚀 Why This Homelab?

- **Zero-Touch Deployments:** Push to Git → Auto-deploy via webhooks → Containers update automatically
- **Ansible Automation:** All nodes managed by Ansible from watchtower control plane
- **Infrastructure as Code:** Services defined in `compose.yaml` + infrastructure managed with Ansible playbooks
- **GPU Transcoding:** Hardware-accelerated media streaming with NVIDIA GTX 1060 Mobile
- **Distributed Architecture:** Services across physical servers with Proxmox hypervisor ready for VM deployment
- **Self-Hosted Git:** No external dependencies—Gitea runs on-premise with automated backups
- **Production-Grade Networking:** Traefik reverse proxy with automatic SSL (Cloudflare DNS challenge)
- **Hypervisor Management:** Proxmox VE ready for VM orchestration with automated post-install configuration

---

## 📊 Stats

- **Total Nodes:** 5 (1 hypervisor + 3 compute + 1 storage)
- **Automation:** Ansible managing 4 active nodes from Watchtower
- **Container Orchestration:** Komodo v2.1.2
- **Active Services:** 12+ (Traefik, Plex, Tunarr, Gitea, Trek, Vaultwarden, etc.)
- **Total RAM:** 62GB (15GB PVE01 + 15GB Heimdall + 16GB Waldorf + 16GB Watchtower)
- **Total CPU Cores:** 30 physical (14c i5-13500T + 8c i7-7820HQ + 4c N100 + 4c ARM)
- **Virtualization:** Proxmox VE 9.1.7 available (no VMs currently deployed)
- **GPU Acceleration:** NVIDIA GTX 1060 Mobile (6GB VRAM)
- **Storage:** TerraMaster NAS (NFSv3/v4)

---

## 🚢 Auto-Deploy

Merging a PR to `main` automatically deploys every stack whose folder changed.

**How it works:**
1. The Gitea Actions workflow (`.gitea/workflows/auto-deploy.yml`) detects which `nodes/{node}/{stack}/` paths changed
2. It POSTs to the corresponding Komodo webhook for each affected stack — no manual redeploy needed
3. Stacks with no matching webhook entry are logged as warnings (not silent failures); any non-2xx response fails the job loudly

**Before it goes live you need:**
- A Gitea Actions runner installed on Heimdall (see [SOP-003](documentation/SOPs/SOP-003-Gitea-Actions-Runner-Setup.md))
- All `TODO` webhook URLs in `WEBHOOK_MAP` replaced with the actual Komodo webhook URLs
  (Komodo UI → Stack → Webhooks tab → copy the full self-authenticating URL)

---

## 🤝 Contributing

This is a personal homelab, but documentation improvements and issue reports are welcome!

1. Fork via Gitea: `https://git.castaldifamily.com/nathan/homelab`
2. Create feature branch: `git checkout -b feat/my-improvement`
3. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
4. Push and create Pull Request

---

## 📜 License

Personal infrastructure configuration. Documentation licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).

---

**Maintained by:** Nathan Castaldi  
**Last Updated:** April 21, 2026  
**Status:** 🟢  
**Automation Status:** 🟢