My Homelab

This project was created to automate my personal homelab, following GitOps principles.

This is not a framework. However, you can customize and extend it in any way you want.

💡 What is a homelab?

"Simply put, a home lab consists of one or more servers (or normal PCs acting as servers), that you have in your home and you use them to experiment and try out stuff." -techie-show

Requirements

Software

• kubernetes-cli
• helm
• ansible
• kompose
• kustomize
• age
• sops
• k9s - for cluster management

Using MacBook, I installed these with Homebrew.

Hardware

• A laptop or desktop, for bootstrapping the cluster.
• Mini PCs, like an Intel NUC, for the actual cluster.
• A Linux OS installed on each mini PC. I use Ubuntu Server.

Stack

System

Logo	Name	Description	Version
	K3s	Lightweight Kubernetes	v1.29.0+k3s1
	Flannel	Layer 3 network fabric designed for Kubernetes
	MetalLB	Network load-balancer implementation for Kubernetes
	Ingress Nginx	Ingress controller for Kubernetes
	Ansible	Automate bare metal provisioning and configuration
	Argo CD	Declarative Continuous Deployment for Kubernetes
	Helm	The Kubernetes Package Manager
	cert-manager	Automatically provision and manage TLS certificates in Kubernetes
	NFS CSI driver	Allows Kubernetes to access NFS server
	Longhorn	Block storage system for Kubernetes
	Minio	Object Storage (like S3)
	Grafana Mimir	Open source TSDB
	Cilium	eBPF-based Networking, Observability, Security solution	⛵ Optional
	Hubble	Networking and security observability platform	⛵ Optional

⚡ Apps

Logo	Name	Description	Notes
	homepage	Modern and highly customizable application dashboard	Annotation discovery
	Authentik	Identity Provider
	Outline	Modern Wiki
	Mealie	Recipe Manager
	Adguard Home	Network-wide software for blocking ads, tracking and DNS server
	Uptime-Kuma	A fancy self-hosted monitoring tool
	Overseer	Request manager for media library

Getting Started

1. Make sure you have ssh access to your servers.
2. Change ansible_username in metal/group_vars/all.yml to your username that has server access.
3. Using a command line, run:

> make

4. It will ask for user password and Cloudflare API Token. The token is needed to perform a DNS challenge with Lets Encrypt (TLS certificate generation).

❄️ You're done! Yes, that's the only command you'll need. 😄

Roadmap

• Automated Kubernetes installation and management
• Automated certificate management
• Automated installation of applications with GitOps
• Distributed block storage
• Network security and observability
• Bare metal load balancer
• Homepage view
• Automated Docker installation and management
• Prompts for global variables (user, ip pools etc)
• Secure external access via Cloudflare Tunnel
• Full-stack monitoring and alerting system
• Private code repository
• Private container registry
• Private artifactory
• Private code static analysis tool
• Identity Access and Management
• Automated backups
• Private CI/CD platform
• CI with Github Actions
• VPN without port forwarding
• Static site documentation
• Automated requirements installation (using brew)

Acknowledgements

This project was heavily-inspired by Khue's Homelab