Khue’s Homelab

Features • Get Started • Documentation

This project utilizes Infrastructure as Code and GitOps to automate provisioning, operating, and updating self-hosted services in my homelab. It can be used as a highly customizable framework to build your own homelab.

What is a homelab?

Homelab is a laboratory at home where you can self-host, experiment with new technologies, practice for certifications, and so on. For more information, please see the r/homelab introduction and the Home Operations Discord community (formerly known as k8s-at-home).

If you encounter an issue, please create a bug report (avoid asking for support about issues specific to this project in other communication channels).

Overview

Project status: ALPHA

This project is still in the experimental stage, and I don’t use anything critical on it. Expect breaking changes that may require a complete redeployment. A proper upgrade path is planned for the stable release. More information can be found in the roadmap below.

Hardware

4 × NEC SFF PC-MK26ECZDR (Japanese version of the ThinkCentre M700):
- CPU: Intel Core i5-6600T @ 2.70GHz
- RAM: 16GB
- SSD: 128GB
TP-Link TL-SG108 switch:
- Ports: 8
- Speed: 1000Mbps

Features

Common applications: Forgejo, Immich, OpenCloud, Matrix…
Automated bare metal provisioning with PXE boot
Automated Kubernetes installation and management
Installing and managing applications using GitOps
Automatic OS rolling upgrade
Automated version update (with approval)
Modular architecture, easy to add or remove features/components
Automated certificate management
Automatically update DNS records for exposed services
VPN (Tailscale or WireGuard)
Expose services to the internet securely with Cloudflare Tunnel
CI/CD platform
Private container registry
Distributed storage
Support multiple environments (staging, production)
Monitoring and alerting
Automated backup and restore
Single sign-on
Infrastructure testing

Some demo videos and screenshots are shown here. They can’t capture all the project’s features, but they are sufficient to get a concept of it.

Demo

Deploy with a single command (after updating the configuration files)

PXE boot

Observe network traffic with Kiali

Homepage powered by… Homepage

Monitoring dashboard powered by Grafana

Git server powered by Forgejo

Matrix chat (FluffyChat UI)

Photo library powered by Immich

File storage powered by OpenCloud

Container registry powered by Zot

Continuous integration with Woodpecker CI

Continuous deployment with ArgoCD

ntfy displaying received alerts

Tech stack

Logo	Name	Description
	Argo CD	GitOps tool built to deploy applications to Kubernetes
	cert-manager	Cloud native certificate management
	Cloudflare	DNS, Tunnel and R2 for OpenTofu state
	ExternalDNS	Synchronizes exposed Kubernetes Services and HTTPRoutes with DNS providers
	Forgejo	Self-hosted Git service
	Go	Custom CLI and infrastructure tests with Terratest
	Grafana	Observability platform
	Helm	The package manager for Kubernetes
	Istio	Kubernetes service mesh and gateway
	K3s	Lightweight distribution of Kubernetes
	Kanidm	Modern and simple identity management platform
	kube-vip	Provides virtual IPs and load balancer for the Kubernetes API and Services
	Kubernetes	Container-orchestration system, the backbone of this project
	Loki	Log aggregation system
	NixOS / Nix	Base OS and convenient development shell
	Nixie	Open-source bare metal provisioning engine for NixOS
	OpenBao	Secrets management
	OpenTofu	Open-source Infrastructure as Code
	Prometheus	Systems monitoring and alerting toolkit
	Renovate	Automatically update dependencies
	Rook Ceph	Cloud-Native Storage for Kubernetes
	Terragrunt	Coordinate OpenTofu modules
	Velero	Backs up and restores Kubernetes
	Woodpecker CI	Simple yet powerful CI/CD engine with great extensibility
	Zot Registry	Private container registry