{"id":42092660,"url":"https://github.com/rhajizada/homelab","last_synced_at":"2026-01-26T11:09:16.206Z","repository":{"id":280735576,"uuid":"924505645","full_name":"rhajizada/homelab","owner":"rhajizada","description":"My personal multi-node Proxmox home server setup managed as IaC with Terraform.","archived":false,"fork":false,"pushed_at":"2025-12-20T10:22:36.000Z","size":248,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-22T12:35:53.949Z","etag":null,"topics":["helm","homelab","infrastructure-as-code","kubernetes","terraform"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhajizada.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-01-30T06:04:24.000Z","updated_at":"2025-12-20T10:22:39.000Z","dependencies_parsed_at":"2025-04-19T07:37:16.821Z","dependency_job_id":"86f81e72-ffba-4125-825a-5d06192e4dd2","html_url":"https://github.com/rhajizada/homelab","commit_stats":null,"previous_names":["rhajizada/homelab"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/rhajizada/homelab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhajizada%2Fhomelab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhajizada%2Fhomelab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhajizada%2Fhomelab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhajizada%2Fhomelab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhajizada","download_url":"https://codeload.github.com/rhajizada/homelab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhajizada%2Fhomelab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28776576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T09:42:00.929Z","status":"ssl_error","status_checked_at":"2026-01-26T09:42:00.591Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helm","homelab","infrastructure-as-code","kubernetes","terraform"],"created_at":"2026-01-26T11:09:15.614Z","updated_at":"2026-01-26T11:09:16.197Z","avatar_url":"https://github.com/rhajizada.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# homelab\n\nThis repository contains the complete Terraform configuration for bootstrapping\nmy homelab environment. It automates every step—from provisioning Proxmox VMs\nand bootstrapping a Talos-based Kubernetes cluster to deploying Kubernetes\napplications using Infrastructure-as-Code (IaC) principles and configuring them.\n\n## Overview\n\nThe homelab setup is organized into two main layers:\n\n- **Infrastructure (`infra`):**\n  This layer uses Terraform modules to provision Proxmox VMs, set up a [Talos Linux](https://www.talos.dev/) based Kubernetes cluster, and configure essential networking. Key components include:\n  - **VM Provisioning:**\n    Ubuntu Server images are used for utility VMs (e.g., DNS/VPN), Talos images for cluster nodes, and optional Arch-based images for Devbox. CloudInit templates perform initial configuration tasks (e.g., installing necessary agents like the qemu-guest-agent, installing and configuring applications).\n  - **Kubernetes Cluster Bootstrap:**\n    Talos VMs are used to establish both control and worker nodes. A kube VIP ensures high availability of the Kubernetes API, while MetalLB allocates a dedicated IP for load balancing.\n  - **Networking \u0026 DNS:**\n    A designated CIDR range is used to automatically assign IP addresses for the DNS and VPN servers, the kube VIP, MetalLB, and Talos nodes.\n  - **DNS \u0026 Certificate Management:**\n    - **CoreDNS** is deployed as the local DNS server. It mirrors AWS Route53 records to support automatic certificate challenges via cert-manager.\n    - **Cert-manager** obtains certificates through ACME (using Route53 for DNS challenges) to secure the cluster.\n    - **Traefik** is deployed as the ingress controller on Kubernetes, routing wildcard DNS queries to the appropriate services.\n  - **Storage:**\n    **Longhorn** is used for persistent storage, enabling dynamic provisioning and volume management across the cluster.\n  - **AWS Integration:**\n    AWS is used in two key areas:\n    - **Terraform Backend:**\n      An AWS S3 bucket securely stores Terraform state files.\n    - **Route53 for DNS:**\n      Cert-manager leverages AWS Route53 (along with provided IAM credentials) to perform DNS challenges and update DNS records automatically.\n\n- **Kubernetes Applications (`apps`):**\n  Once the cluster is bootstrapped, configurations in the `apps` folder deploy various Kubernetes applications (e.g., authentik, argocd, gitea, grafana, harbor, openwebui, llamero, perplexica, openvscode, and prometheus) into the cluster.\n\n## Topology\n\n```mermaid\ngraph TD\n  subgraph Internet[\"Public Network\"]\n    User[\"fa:fa-user User\"]\n    VPNClient[\"fa:fa-laptop VPN Client\"]\n    Route53[\"fa:fa-cloud Route53 Hosted Zone\"]\n  end\n\n  subgraph Home[\"Home Network\"]\n    Gateway[\"fa:fa-router Gateway 192.168.1.1\"]\n    VPNServer[\"fa:fa-shield VPN Server\"]\n    DNS[\"fa:fa-network-wired CoreDNS\"]\n    Devbox[\"fa:fa-terminal Devbox VM\"]\n    Samba[\"fa:fa-folder-open Samba VM\"]\n\n    subgraph Talos[\"Talos | Kubernetes\"]\n      VIP[\"fa:fa-bullseye K8s Virtual IP\"]\n      Control1[\"fa:fa-server Control Node 1\"]\n      Control2[\"fa:fa-server Control Node 2\"]\n      MetalLB[\"fa:fa-random MetalLB\"]\n      Traefik[\"fa:fa-route Traefik Ingress\"]\n\n      subgraph Workers[\"Worker Nodes\"]\n        Worker1[\"fa:fa-server Worker Node 1 (GPU)\"]\n        Worker2[\"fa:fa-server Worker Node 2\"]\n\n        subgraph Apps[\"Apps\"]\n          ArgoCD[\"fa:fa-code-branch Argo CD\"]\n          Grafana[\"fa:fa-chart-line Grafana\"]\n          Harbor[\"fa:fa-box Harbor\"]\n          Gitea[\"fa:fa-code Gitea\"]\n          Llamero[\"fa:fa-brain Llamero\"]\n          OpenWebUI[\"fa:fa-comments OpenWebUI\"]\n          Perplexica[\"fa:fa-search Perplexica\"]\n          OpenVSCode[\"fa:fa-laptop-code OpenVSCode\"]\n        end\n      end\n    end\n  end\n\n  User --\u003e|login| VPNClient\n  VPNClient --\u003e|Wireguard| Route53\n  Route53 --\u003e|DNS -\u003e Public IP| Gateway\n  Gateway --\u003e|NAT| VPNServer\n  VPNServer --\u003e|private network| Gateway\n\n  Gateway --\u003e|DNS| DNS\n  DNS --\u003e|Ingress| Traefik\n\n  Gateway --\u003e|VIP| VIP\n  VIP --\u003e Control1\n  VIP --\u003e Control2\n  Control1 --\u003e MetalLB\n  Control2 --\u003e MetalLB\n  MetalLB --\u003e Traefik\n  Traefik --\u003e ArgoCD\n  Traefik --\u003e Grafana\n  Traefik --\u003e Harbor\n  Traefik --\u003e Gitea\n  Traefik --\u003e Llamero\n  Traefik --\u003e OpenWebUI\n  Traefik --\u003e Perplexica\n  Traefik --\u003e OpenVSCode\n\n  classDef external fill:#f7f3ee,stroke:#8a6d3b,color:#3d2c11;\n  classDef home fill:#eef5ff,stroke:#4b74b8,color:#1f2f4a;\n  classDef k8s fill:#f0fff4,stroke:#3c8c5a,color:#1d3a2a;\n  classDef apps fill:#fff7e6,stroke:#d99a2b,color:#3f2a00;\n\n  class User,VPNClient,Route53 external;\n  class Gateway,VPNServer,DNS,Devbox,Samba home;\n  class VIP,Control1,Control2,Worker1,Worker2,MetalLB,Traefik k8s;\n  class ArgoCD,Grafana,Harbor,Gitea,Llamero,OpenWebUI,Perplexica,OpenVSCode apps;\n\n```\n\n_The router is configured to route all DNS traffic to the dedicated DNS server and forward VPN traffic to the VPN node._\n\n- **VM Provisioning \u0026 Cluster Bootstrapping:**\n  Terraform provisions VMs for:\n  - **DNS Server:** Runs CoreDNS.\n  - **VPN Server:** Provides secure remote access.\n  - **Kubernetes Cluster Nodes:**\n    - **Talos Control Nodes:** Equipped with a kube VIP for high availability of the Kubernetes API.\n    - **Talos Worker Nodes:** Automatically assigned IP addresses from a specified CIDR range.\n- **Ingress \u0026 Storage:**\n  - **Traefik** manages inbound traffic by routing wildcard DNS domains to services deployed on Kubernetes.\n  - **Longhorn** provides the storage backend for the cluster.\n\n## Taskfile Workflow\n\nThis project leverages [Taskfile](https://github.com/go-task/task) to streamline _Terraform_ workflows. Each layer includes its own Taskfile, while a root Taskfile is also available to coordinate commands across both layers.\n\n### Available Tasks\n\n#### Infrastructure\n\n- **infra:apply:** Create or update infrastructure\n- **infra:destroy:** Create or update infrastructure\n- **infra:format:** Reformat your configuration in the standard style\n- **infra:init:** Prepare your working directory for other commands\n- **infra:kubeconfig:** Generate 'kubeconfig'\n- **infra:kubeseal:** Generate kubeseal cerificate\n- **infra:plan:** Show changes required by the current configuration\n- **infra:ssh:** Generate SSH key and connect to specified node (vpn or dns)\n- **infra:talosconfig:** Generate 'talosconfig'\n- **infra:validate:** Check whether the configuration is valid\n- **infra:wireguard:** Generate wireguard client configuration\n\n#### Applications\n\n- **apps:apply:** Create or update infrastructure\n- **apps:destroy:** Create or update infrastructure\n- **apps:format:** Reformat your configuration in the standard style\n- **apps:init:** Prepare your working directory for other commands\n- **apps:plan:** Show changes required by the current configuration\n- **apps:scale-runners:** Scale Gitea action runners to the specified count (0-10)\n- **apps:secrets:** Show bootstrap/admin credentials for a specified app\n- **apps:setup-runners:** Run setup script on gitea runners\n- **apps:validate:** Check whether the configuration is valid\n\n## AWS Integration\n\nThis homelab configuration integrates with AWS for two key purposes:\n\n- **Terraform Backend:**\n  An AWS S3 bucket is used to securely store Terraform state files. Configure your AWS S3 backend settings in your Terraform configuration or via environment variables.\n- **Route53 for DNS:**\n  Cert-manager leverages AWS Route53 to perform DNS challenges and update DNS records automatically. Ensure you provide the necessary AWS IAM credentials and the Route53 hosted zone ID in your configuration.\n\n## Getting Started\n\n1. **Clone the Repository:**\n\n   ```sh\n   git clone https://github.com/yourusername/homelab.git\n   cd homelab\n   ```\n\n2. Create a .env file (or configure variables directly) with the required parameters:\n\n```\nPROXMOX_VE_USERNAME=\"root@pam\"\nPROXMOX_VE_PASSWORD=\"\"\n```\n\n3. Install `terraform` or `tofu` (please configure `TF` variable in `Taskfile.yaml` accordingly)\n4. Setup `terraform` environment:\n\n```\ntask infra:init\ntask apps:init\n```\n\n5. Deploy:\n\n```\ntask infra:apply\ntask infra:kubeconfig symlink=true\ntask apps:apply\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhajizada%2Fhomelab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhajizada%2Fhomelab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhajizada%2Fhomelab/lists"}