Homelab Infrastructure
Design, architecture, and operations for a greenfield homelab rebuild. Documentation is grouped by topic; use this page as the index.
At a glance
The homelab is organized into six logical environments (VLANs) with different purposes:
| Environment | Purpose | Management |
|---|---|---|
| Prod | Production workloads | GitOps (Komodo) |
| Test | Pre-production validation | GitOps (Komodo) |
| Dev | Development, experimentation, OCP cluster | Mixed (Komodo for Docker, unmanaged for VMs/OCP) |
| User | Personal workstation | N/A |
| IoT | Smart home, cameras | Isolated |
| DMZ | Public-facing services (qBittorrent) | Isolated, restricted |
Prod, Test, and Dev (Docker containers) form a promotion path managed by Komodo. Dev also contains unmanaged nodes (VMs, OCP cluster) for experimentation.
Overview
Orienting views of the whole lab.
| Document | Contents |
|---|---|
| Homelab map | Hardware, VLANs, services, network topology |
| Visual overview (HTML) | Interactive layout (open locally or publish as static HTML) |
| Published graphic | Same idea hosted on the public site (path may differ from this repo) |
Network
Connectivity, edge, and remote access.
| Document | Contents |
|---|---|
| Tailscale | Overlay, remote access, Docktail, shared access model |
| UniFi configurations | SSIDs, VLANs, controller notes |
Platform
Architecture of environments, hardware, and infrastructure-as-code layout.
| Document | Contents |
|---|---|
| Architecture | System diagrams, environment map, GitOps flow |
| Environments | Detailed breakdown of each environment |
| Hardware | Physical inventory and specs |
| Planned repository structure | Infrastructure repo layout |
| Leantime MCP server | Leantime MCP bridge setup and how it reaches the homelab instance |
Observability
Public status and operator dashboards.
| Document | Contents |
|---|---|
| Observability index | Topic entry point |
| Status site & operator dashboard | status.samplayskeys.com, VPS hosting, single pane of glass |
Planning
Decisions, roadmap, ADRs, and working notes.
| Document | Contents |
|---|---|
| Decisions | Key decisions and rationale |
| ADRs | Architecture decision records (detailed, reference-friendly) |
| Roadmap | Open questions and future work |
| Scratchpad | Informal notes and state |
AI VM
Dedicated Debian VM with Quadro P5000 GPU passthrough, running LlamaFarm as the AI model management layer. Disposable — Ansible provisions, persistent storage holds models and data.
| Document | Contents |
|---|---|
| Architecture | VM specs, storage layout, GPU profile, provisioning flow |
| ADR 0001 | LlamaFarm as AI model management layer |
| Ansible playbook draft | Provisioning roles (os-hardening, nvidia-cuda, persistent-storage, llamafarm-install, llamafarm-service) |
Smart home (IoT)
| Document | Contents |
|---|---|
| IoT documentation | Home Assistant, Zigbee, automations, device decisions |
Tooling stack
- Infrastructure provisioning: Terraform
- System configuration: Ansible
- Container orchestration: Komodo (Core + Periphery agents)
- Version control: Git (GitHub)
Key principles
- GitOps for managed environments — Desired state lives in Git; Komodo reconciles actual state to match
- Promotion via file movement — Move/copy TOML files between
dev/→test/→prod/directories - Isolation for sandboxes — DevNode and DevOCP have no GitOps integration; they’re for experimentation
- Dedicated management plane — Komodo Controller runs on separate hardware (NUC) with no workloads