Home-Ops Overview

Relevant source files

• .config.env.example
• .justfile
• .mise.toml
• .taskfiles/Repository/Taskfile.yaml
• LICENSE
• README.md
• docs/ai-context/CONVENTIONS.md
• docs/inventory.yaml
• docs/proxmox/gpu.md
• docs/proxmox/network.md
• docs/ups_sizing.md
• infrastructure/ansible/inventory/hosts.yaml
• infrastructure/terraform/proxmox/talos/inline-manifests/cilium-install.yaml
• infrastructure/terraform/s3/backblaze/b2.tf
• kubernetes/apps/database/dragonfly-operator/app/helmrelease.yaml
• kubernetes/apps/default/kustomization.yaml
• kubernetes/apps/downloads/kustomization.yaml
• kubernetes/apps/home-automation/kustomization.yaml
• kubernetes/apps/media/kustomization.yaml
• kubernetes/apps/observability/kromgo/app/resources/config.yaml
• kubernetes/apps/observability/kustomization.yaml
• kubernetes/apps/security/kustomization.yaml
• kubernetes/apps/storage/kustomization.yaml

This repository is a monorepo for managing home infrastructure using a GitOps philosophy. It automates the lifecycle of a Talos Linux cluster running on Proxmox, utilizing Flux CD for continuous delivery and Terraform/Ansible for infrastructure provisioning README.md:42-48().

The primary goal of this project is to maintain a self-healing, declarative environment for home automation, media services, and developer utilities while adhering to industry-standard Infrastructure as Code (IaC) practices README.md:47-48().

System Architecture

The environment is structured in layers, moving from physical hardware and virtualization up to containerized applications managed by Kubernetes.

Logical Architecture Overview

The following diagram illustrates the relationship between the management tools and the target infrastructure.

Management to Infrastructure Mapping

Sources:README.md:42-57(), hosts.yaml:2-10(), .mise.toml:1-12().

Key Technologies

Category	Tools	Purpose
Virtualization	Proxmox VE	Type-1 Hypervisor hosting the Talos nodes README.md:57-58().
OS	Talos Linux	Security-focused, API-managed Kubernetes operating system README.md:57-58().
GitOps	Flux CD	Syncs Kubernetes manifests from the kubernetes/ directory README.md:45().
Provisioning	Terraform & Ansible	Manages VM creation, Cloudflare DNS, and Proxmox host config README.md:45().
Secrets	SOPS & Age	Encrypts sensitive data within the Git repository .mise.toml:5().
Automation	Taskfile & Renovate	Handles developer workflows and automated dependency updates README.md:7, 62-64().

Repository Organization

The repository is organized into distinct functional areas that separate infrastructure concerns from application deployments.

Repository Structure and Entity Mapping

Sources:kustomization.yaml:5-6(), .mise.toml:1-18(), README.md:68-71().

Major Sections

• Infrastructure: Contains Ansible playbooks for host-level configuration (ZFS, NFS) and Terraform modules for provisioning VMs and cloud resources (Cloudflare, Backblaze B2) README.md:57-58().
• Kubernetes Apps: Organized by namespace (e.g., media, downloads, observability). Each application typically follows a standard pattern using the bjw-s/app-templatekustomization.yaml:9-23().
• Observability: A comprehensive stack including Prometheus, Grafana, Loki, and Tempo for monitoring cluster health and performance kustomization.yaml:9-20().
• External Resilience: Critical services like Gatus are deployed to Fly.io via Taskfile automation to ensure monitoring remains active even if the primary cluster is offline README.md:62-71().

Child Pages

For detailed documentation on specific subsystems, refer to the following pages:

• Repository Structure and Conventions: Detailed breakdown of the kubernetes/ directory, the ks.yaml entry point pattern, and shared Kustomize components.
• Getting Started and Developer Tooling: Guide to setting up the local environment using mise, managing secrets with sops, and using task for daily operations.

---

Sources:

• README.md:1-148()
• kustomization.yaml:1-27()
• .mise.toml:1-18()
• hosts.yaml:1-10()