This repository manages my homelab entirely as code so that AI tools can manage the environment running AI workloads. Everything from virtual machines to Kubernetes manifests is stored and documented here.
The design follows a layered approach. It begins with a clear purpose: automate and document the homelab. AI manages the infrastructure that powers AI workloads. Below that sits the automation layer which contains Proxmox orchestration scripts, Kubernetes manifests and GitOps configuration for reproducible deployments. Next comes the service layer where LXC containers - created with Tteck's Proxmox VE helper scripts - and guides describe GPU servers, monitoring, and networking. Ubuntu MAAS handles bare-metal installs before nodes join Proxmox. At the base is the documentation layer with extensive Sphinx content explaining how everything fits together.
graph TD
Purpose --> Automation
Automation --> Services
Services --> Documentation
Documentation --> Purpose
See the Homelab AI Overview for a deeper explanation and additional diagrams. See the Ubuntu MAAS and Proxmox Overview for details on bare metal installs and container provisioning.
- Ollama GPU Server Guide - deploy via Flux
- Ollama Service Guide
- Coral TPU Automation System - automated Coral TPU initialization
- Frigate Storage Migration Report - Samsung T5 to 3TB HDD migration
- Stable Diffusion Web UI Guide
- Flux Bootstrap Guide
- MetalLB Setup Guide
- Monitoring Setup Guide - deployed via Flux
- Monitoring Troubleshooting - fix common issues
- K3s Too Many Open Files Runbook - troubleshoot descriptor errors
- Coral TPU Automation Runbook - maintain and troubleshoot automated Coral TPU initialization
- Docs Workflow Guide
- documentation is deployed from
masterusingmake -C docs html
- documentation is deployed from
- Docs Build Guide - build docs locally before pushing
- Docs Symlink Guide - fix broken markdown links
- Docs Publishing Guide - update the
gh-pagesbranch - Python Tests Guide
- Agent Guidelines
- Project Documentation
- 2.5 GbE Migration Guide — step-by-step migration from 1 GbE to 2.5 GbE, with lessons learned.
- Flint 3 VLAN40 Split Guide — bridge Wi-Fi while isolating Proxmox
- VLAN Troubleshooting Checklist & Guide - diagnose common VLAN issues