Homelab as Code

This is the documentation for my homelab, which is built and run entirely as code. It is a small Kubernetes cluster where every layer, from the bare-metal install through to the applications on top, is declared in this repository and reconciled through GitOps.

The guiding rule is that nothing is configured by hand. Hardware and VMs are provisioned with Ansible and OpenTofu, the nodes run Talos (an immutable, API-only Kubernetes OS), and Argo CD keeps the cluster matching Git. Changing a service means committing a file, not clicking through a UI, and if a node dies I rebuild it from the same code.

It also doubles as a portfolio. Parts of the journey are written up on my blog, Tower of Kubes. These docs exist so the project stays understandable, both to me months from now and to anyone curious about how it works.

Where to go next

The documentation follows the Diátaxis model, four sections for four kinds of need:

• Tutorials: build the whole stack from scratch, one layer at a time.
• Guides: focused how-tos for specific tasks, like adding an application.
• Reference: the concrete details, the tech stack, prerequisites, and environment variables.
• Explanation: how the pieces fit together and why it is built this way.

For the big picture, start with the architecture overview. To build the lab, head to Getting Started.