https://samplayskeys.github.io/Workspace/homelab/index.htmlDesign, 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.Hugoen-usThu, 03 Sep 2026 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/leantime-mcp/index.htmlThu, 03 Sep 2026 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/leantime-mcp/index.htmlHow the Leantime MCP server is set up and running on this machine (sams-macbook-air), for use as an opencode MCP tool. Overview Leantime is a self-hosted project management tool running in the homelab. It exposes an MCP endpoint at /mcp. This machine runs the leantime-mcp npm bridge as a stdio-to-HTTP proxy: it speaks the MCP protocol over stdio to the client (opencode), then forwards every tool call as HTTP JSON-RPC to the remote Leantime endpoint using a personal access token.https://samplayskeys.github.io/Workspace/homelab/planning/adrs/index.htmlWed, 26 Aug 2026 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/planning/adrs/index.htmlADRs capture decisions that are stable enough to reference later, with context and trade-offs. They supplement the narrative Decisions page. Document Status Per-environment Git branches via Komodo ResourceSync Accepted Baremetal Docker Host OS Selection Proposed Container Runtime Tradeoffs Proposed Skip local Docker registry, focus on git pipeline Accepted Docker vs Kubernetes for an Orchestration platform Inconclusive Tailnet-per-environment with declarative node sharing Rejected Workload isolation in a single tailnet — access pools Proposedhttps://samplayskeys.github.io/Workspace/homelab/network/tailscale/index.htmlMon, 03 Aug 2026 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/network/tailscale/index.htmlNetwork connectivity strategy for the homelab using Tailscale mesh VPN. Overview Tailscale is a mesh VPN built on WireGuard that creates a secure network (called a “tailnet”) across devices regardless of their physical location. Unlike traditional VPNs, there’s no central server that all traffic flows through — devices connect directly to each other.https://samplayskeys.github.io/Workspace/homelab/platform/adr-podman-vs-docker/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/adr-podman-vs-docker/index.htmlStatus Draft Context We need a container runtime for local development, CI/CD pipelines, and homelab deployment. The ecosystem has two primary open-source contenders: Docker (the incumbent) and Podman (the rising alternative). Both implement OCI standards and can run the same container images, but differ significantly in architecture, security model, and ecosystem integration.https://samplayskeys.github.io/Workspace/homelab/ai-vm/architecture/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/ai-vm/architecture/index.htmlOverview A dedicated Debian VM with an NVIDIA Quadro P5000 passed through, running LlamaFarm natively as the AI management layer. The VM is fully disposable — Ansible provisions the OS and installs tooling; models and data live on persistent storage. If the VM is destroyed, a fresh provision + persistent volume mount restores full capability in minutes.https://samplayskeys.github.io/Workspace/homelab/platform/architecture/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/architecture/index.htmlSystem diagrams and visual documentation for the homelab infrastructure. Environment Map ┌─────────────────────────────────────────────────────────────────────────────┐ │ KOMODO CONTROLLER (NUC) │ │ ┌──────────────┬───────────┐ │ │ │ Komodo Core │ MongoDB │ │ │ └──────┬───────┴───────────┘ │ │ │ manages │ └────────────────────────────┼────────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ GITOPS MANAGED ENVIRONMENTS │ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌───────────────────────┐ │ │ │ PROD │ │ TEST │ │ DEV │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │ ┌─────────────────┐ │ │ │ │ │ Prod MiniPC │ │ │ │ Test MiniPC │ │ │ │ DevDocker VM │ │ │ │ │ │ [Periphery] │ │ │ │ [Periphery] │ │ │ │ (on ProxMox) │ │ │ │ │ │ │ │ │ │ │ │ │ │ [Periphery] │ │ │ │ │ │ • Plex │ │ │ │ • Plex (test) │ │ │ │ │ │ │ │ │ │ • *arr Suite │ │ │ │ • Test Apps │ │ │ │ • Experimental │ │ │ │ │ │ • ... │ │ │ │ │ │ │ │ containers │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───────────────┘ │ │ └───────────────┘ │ │ └─────────────────┘ │ │ │ │ ▲ │ │ ▲ │ │ │ │ │ │ │ NFS/SMB │ │ │ NFS/SMB │ │ │ │ │ │ ┌──────┴────────┐ │ │ ┌──────┴────────┐ │ │ │ │ │ │ │ UnRaid NAS │ │ │ │ Synology NAS │ │ │ │ │ │ │ │ (Media) │ │ │ │ (Test Data) │ │ │ │ │ │ │ └───────────────┘ │ │ └───────────────┘ │ │ │ │ │ └─────────────────────┘ └─────────────────────┘ └───────────────────────┘ │ │ │ │ Promotion path: DEV ──────────────▶ TEST ──────────────▶ PROD │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ UNMANAGED / SANDBOX ENVIRONMENTS │ │ │ │ ┌────────────────────────────────────┐ ┌───────────────────────────────┐ │ │ │ DEVNODE (ProxMox VMs) │ │ DEVOCP (Isolated) │ │ │ │ │ │ │ │ │ │ • Test VM 1 │ │ 3x MiniPC Cluster: │ │ │ │ • Test VM 2 │ │ • Control Plane │ │ │ │ • ... │ │ • Worker 1 │ │ │ │ │ │ • Worker 2 │ │ │ │ (bugfixes, themes, ad-hoc) │ │ │ │ │ │ │ │ (OpenShift - work projects) │ │ │ └────────────────────────────────────┘ └───────────────────────────────┘ │ │ │ │ No Komodo. No GitOps. Just sandboxes. │ └─────────────────────────────────────────────────────────────────────────────┘ Key Points Komodo Controller sits outside the environment groups — it manages but is not part of workload infrastructure Managed Docker hosts (Prod, Test, DevDocker) have Periphery agents and are GitOps-controlled DevDocker VM runs on ProxMox but is still Komodo-managed — promotion path to Test → Prod Unmanaged nodes in Dev — DevNode VMs and OCP cluster have no Komodo integration Storage is accessed via network mounts from UnRaid NAS (Prod) and Synology NAS (Test) GitOps Flow Each managed environment is driven by Komodo ResourceSync, which can target main or a named branch independently (so Dev can track a feature branch while Prod tracks main). The full branch-steering workflow and merge hygiene are in the ADR on per-environment ResourceSync branches; repo layout and promotion folders are in Planned repository structure.https://samplayskeys.github.io/Workspace/homelab/ai-vm/adr/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/ai-vm/adr/index.htmlADRs here capture decisions for the AI VM homelab project. # Title Status 0001 LlamaFarm as AI model management layer Proposedhttps://samplayskeys.github.io/Workspace/homelab/planning/decisions/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/planning/decisions/index.htmlKey architectural and tooling decisions, with rationale. Komodo over Kubernetes (K3s + ArgoCD) Decision: Use Komodo for container GitOps instead of deploying K3s with ArgoCD. Context: Needed GitOps capabilities (drift detection, continuous reconciliation) for Prod/Test environments. Current approach (GitHub Actions → Ansible playbooks) works but lacks: Drift detection Continuous reconciliation Sustainable operational model Options considered:https://samplayskeys.github.io/Workspace/homelab/platform/environments/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/environments/index.htmlDetailed breakdown of each environment (VLAN) in the homelab. Managed Environments (GitOps) These environments have Komodo Periphery agents on Docker hosts, managed via GitOps. Changes flow through Git → Komodo Core → Periphery Agent → Container. Prod Purpose: Production workloads — services that need to be reliable and always available.https://samplayskeys.github.io/Workspace/homelab/platform/hardware/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/hardware/index.htmlOverview Inventory of physical machines, virtual machines, and network-attached storage in the homelab. Physical Machines Name Hardware Specs Role & Environment OS Notes LenovoMini 1 8th Gen i7, NVIDIA GPU, 16GB RAM Prod Docker host Fedora Komodo periphery, Tailscale LenovoMini 2 7th Gen i5, NVIDIA GPU, 16GB RAM Test Docker host Fedora Komodo periphery, Tailscale LenovoMini 3 i5, 16GB RAM Dev (OCP node 1) — Tailscale Operator LenovoMini 4 i5, 16GB RAM Dev (OCP node 2) — Tailscale Operator LenovoMini 5 i5, 16GB RAM Dev (OCP node 3) — Tailscale Operator JONSBO NAS 6th Gen i7, 16GB RAM, NVIDIA GPU, 10TB (8TB usable) Prod NAS — Tailscale container, mapped to LenovoMini 1 Intel NUC Celeron CPU, 8GB RAM Prod management — Komodo instance, GitHub runner, Tailscale ProxMox Host Ryzen 3700, 16GB RAM, NVIDIA GPU Mixed ProxMox Tailscale, hosts VMs below Synology NAS 4GB RAM, 6TB storage Test NAS — Tailscale, mapped to LenovoMini 2 Gaming PC Ryzen 5700, 16GB RAM, NVIDIA GPU User (future) Windows Remote Windows access Virtual Machines Hosted on ProxMox (Tailscale installed on ProxMox host):https://samplayskeys.github.io/Workspace/homelab/overview/homelab-map/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/overview/homelab-map/index.htmlEnvironments Environment Purpose Subnet Hardware & Services Prod Production services 10.0.1.0/24 LenovoMini 1, UnRaid NAS, Intel NUC, Komodo, Docker workloads Test Staging and validation 10.0.2.0/24 LenovoMini 2, Synology NAS, Komodo periphery Dev Development & experimentation 10.0.3.0/24 ProxMox Host (DevDocker VM, DevNode VMs), LenovoMini 3–5 (OCP cluster), Tailscale Operator User Personal workstation 10.0.10.0/24 Gaming PC IoT Smart home & cameras 10.0.4.0/24 Reolink cameras, Google Home DMZ Public-facing services 10.0.5.0/24 Shared NIC on existing hosts OR dedicated seed box; qBittorrent; shared storage mount VLANs & Subnets VLAN Description Subnet Firewall Rules Unifi SSID / Notes 1 Prod 10.0.1.0/24 Allow all internal; restrict IoT → Prod Wired only 2 Test 10.0.2.0/24 Allow all internal; restrict IoT → Test Wired only 3 Dev 10.0.3.0/24 Allow all internal Wired only 4 IoT 10.0.4.0/24 Isolate from prod/test/dev IoT (WPA2) 5 DMZ 10.0.5.0/24 DMZ → External allowed (specific ports); External → DMZ restricted; DMZ → all internal blocked (except DMZ → UnRaid NFS for shared storage) Wired only 10 User 10.0.10.0/24 Isolate from prod/test/dev/IoT Home (WPA3) Network Topology GFiber (1Gbps) → Unifi UDM → Unifi 16-port PoE Switch │ ├── LenovoMini 1 (Prod Docker) → UnRaid NAS ├── LenovoMini 2 (Test Docker) → Synology NAS ├── ProxMox Host (Dev) → DevDocker VM, DevNode VMs ├── LenovoMini 3–5 (Dev OCP cluster) ├── Intel NUC (Prod management / Komodo Controller) ├── Gaming PC (User) ├── IoT VLAN (Reolink, Google Home) └── DMZ VLAN (qBittorrent, shared storage mount) Tailscale Overlay: All nodes Services & Dependencies Tailscale Services (on all Docker hosts):https://samplayskeys.github.io/Workspace/homelab/platform/planned-repo-structure/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/platform/planned-repo-structure/index.htmlLayout for the infrastructure-as-code repository that manages the homelab. Overview The infrastructure repository has three main sections: Section Tool Purpose terraform/ Terraform Provision VMs, networks, base infrastructure ansible/ Ansible System configuration, package management, agent installation komodo/ Komodo Container definitions and GitOps configs Full Structure infrastructure/ ├── terraform/ │ ├── prod/ │ ├── test/ │ ├── dev/ │ └── modules/ │ ├── ansible/ │ ├── inventory/ │ │ ├── prod.yml │ │ ├── test.yml │ │ └── dev.yml │ ├── playbooks/ │ │ ├── base-setup.yml # Common system config │ │ ├── install-periphery.yml # Install Komodo Periphery agent │ │ └── ... │ └── roles/ │ └── komodo/ ├── prod/ │ ├── servers.toml # Server definitions │ ├── arr-suite/ │ │ ├── arr-suite.toml │ │ └── compose.yaml │ ├── plex/ │ │ ├── plex.toml │ │ └── compose.yaml │ └── homepage.toml # Simple apps can be flat │ ├── test/ │ ├── servers.toml │ └── ... │ ├── dev/ │ ├── servers.toml │ └── ... │ └── shared/ └── variables.toml # Shared variables across envs Terraform Section Provisions the underlying infrastructure.https://samplayskeys.github.io/Workspace/homelab/iot/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/iot/index.htmlOverview and project plan for IoT deployment at the new house. Philosophy: Convenience first, security second. Self-hosted, local control where possible. Platform Stack Layer Choice Status Notes Hub Home Assistant Planned Phase 1: RPi 4, Phase 2: Container on Prod Docker Primary Protocol Zigbee Planned Via Sonoff Zigbee 3.0 coordinator Voice Google Home Existing TTS announcements via HA Network Unifi Network On order UDM + switches, foundation for VLANs Cameras Unifi Protect + Tapo On order / Existing Protect on UDM, 3x Tapo (existing) Thermostats Sensi (2 zones) Existing Cloud integration via HA (acceptable trade-off) See decisions/home-assistant-deployment.md for deployment architecture.https://samplayskeys.github.io/Workspace/homelab/observability/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/observability/index.htmlPlans for public user-facing status and private operator dashboards (metrics, deep links, navigation to Komodo and Uptime Kuma). Document Contents Status site & operator dashboard Phases, success criteria, sequencing, status.samplayskeys.com, single pane of glass For hardware, VLANs, and which services run where, start at the homelab map.https://samplayskeys.github.io/Workspace/homelab/planning/roadmap/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/planning/roadmap/index.htmlOpen questions, future work, and ideas for the homelab. Open Questions These need to be resolved as the build progresses. Network Topology Network segmentation between environments (VLANs) — defined in homelab-map.md Firewall rules between Prod/Test/Dev/IoT/DMZ — defined in unifi-configurations.md DNS strategy (internal DNS, split-horizon?) Reverse proxy / ingress strategy (Traefik, Caddy, nginx?) Storage Strategy UnRaid NAS role in Prod — just media, or also app data? Synology NAS role in Test — mirror of UnRaid structure, or different? Backup strategy across environments How does DevDocker access test data (if at all)? Terraform + Ansible Boundary Exactly which resources does Terraform manage? Does Terraform manage the physical MiniPCs, or just VMs on ProxMox? How do we bootstrap the Komodo Controller itself? DMZ Strategy DMZ VLAN defined (VLAN 5, 10.0.5.0/24) — see homelab-map.md Decide on shared NIC vs dedicated seed box hardware qBittorrent deployment (Docker on shared NIC or baremetal on seed box) NFS export for shared storage (DMZ → UnRaid NAS) Lock down firewall rules — strictly limit DMZ → Internal to NFS only Monitoring & Alerting Where does monitoring live? (Separate from workloads?) Komodo has built-in alerting — is that sufficient? Do we need a dedicated metrics/visualization stack (e.g. Prometheus/Grafana), or is Komodo + Uptime Kuma (+ existing logging) enough for the foreseeable future? (Prometheus/Grafana/Influx-style stack explicitly deferred — not pursuing yet.) Secrets Management How do secrets get into Komodo configs? Komodo supports variables — are those sufficient for secrets? Do we need external secrets management (Vault, etc.)? Planned Workloads Apps and stacks to deploy once infrastructure is ready.https://samplayskeys.github.io/Workspace/homelab/planning/scratchpad/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/planning/scratchpad/index.htmltype: Idea Machine List JONSBO NAS - 6th Gen i7, 16 GB RAM, NVIDIA GPU, 10TB of storage (8 usable) Synology NAS - 4GB RAM, 6TB storage Intel NUC - Celeron CPU, 8GB of RAMhttps://samplayskeys.github.io/Workspace/homelab/network/unifi-configurations/index.htmlMon, 01 Jan 0001 00:00:00 +0000https://samplayskeys.github.io/Workspace/homelab/network/unifi-configurations/index.htmlOverview This guide walks through configuring the homelab network using UniFi’s Zone-Based Firewalls (ZBF), available in UniFi Network 9.0+. ZBF shifts away from traditional LAN In/Out rules by grouping networks into Zones and defining Policies that dictate traffic flow between those zones. This is visualized in the Zone Matrix and is vastly superior for environment segmentation.