A modular, infrastructure-as-code (IaC) project for building and managing my self-hosted homelab environment. This repository automates the provisioning of virtual machines, Kubernetes clusters, and essential services using modern DevOps tools.

homelab provides a reproducible, automated way to deploy and manage a home infrastructure stack. It leverages:

• OpenTofu for infrastructure provisioning (VMs, networking, storage)
• Kubernetes for container orchestration and application management
• Packer for building custom VM images
• Vault, Proxmox, Longhorn, ArgoCD, and more for secrets, virtualization, storage, and GitOps

The project is designed for flexibility, modularity, and maintainability, making it easy to extend or adapt to my homelab needs.

• OpenTofu
• Packer
• Proxmox VE (for virtualization)
• kubectl
• k9s

Use Packer to build base images for your VMs.

cd packer/linux
packer init .
packer build -var-file=ubuntu-24042.pkrvars.hcl .

See packer/README.md for more details.

Use Tofu/Terraform to provision VMs, networks, and storage.

cd tofu/infrastructure
tofu init
tofu plan
tofu apply

Apply Kubernetes manifests to your cluster.

cd kubernetes/bootstrap
kubectl apply -k .

Then deploy applications from kubernetes/apps/ via ArgoCD.

• Vault, Postgres, and other services are managed under tofu/services/.
• See service-specific files for configuration and secrets management.

• apps/: Application manifests (e.g., Paperless NGX)
• bootstrap/: Cluster bootstrap resources (ArgoCD, Vault, Longhorn, MetalLB, etc.)
  • See kubernetes/bootstrap/README.md and subdirectory READMEs for details.

• linux/: Packer templates and scripts for building Linux VM images.
• See packer/README.md for image build instructions.

• infrastructure/: Tofu/Terraform modules for VMs, networking, storage, and Proxmox integration.
• services/: Service definitions and modules (Vault, Postgres, etc.)

• Packer Documentation
• Terraform Documentation
• OpenTofu Documentation
• Kubernetes Documentation
• Proxmox VE Documentation

See also:

• packer/README.md
• kubernetes/bootstrap/README.md
• kubernetes/bootstrap/resources/longhorn/README.md

This project is licensed under the terms of the GPL-3.0 license.