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

• [x] Common applications: Gitea, Jellyfin, Paperless...
• [x] Automated bare metal provisioning with PXE boot
• [x] Automated Kubernetes installation and management
• [x] Installing and managing applications using GitOps
• [x] Automatic rolling upgrade for OS and Kubernetes
• [x] Automatically update apps (with approval)
• [x] Modular architecture, easy to add or remove features/components
• [x] Automated certificate management
• [x] Automatically update DNS records for exposed services
• [x] VPN (Tailscale or Wireguard)
• [x] Expose services to the internet securely with Cloudflare Tunnel
• [x] CI/CD platform
• [x] Private container registry
• [x] Distributed storage
• [x] Support multiple environments (dev, prod)
• [x] Monitoring and alerting
• [x] Automated backup and restore
• [x] Single sign-on
• [x] 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 Hubble, built on top of Cilium and eBPF | | | | Homepage powered by... Homepage | | | | Monitoring dashboard powered by Grafana | | | | Git server powered by Gitea | | | | Matrix chat server | | | | Continuous integration with Woodpecker CI | | | | Continuous deployment with ArgoCD | | | | ntfy displaying received alerts | | | | Self-hosted AI powered by Ollama (experimental, not very fast because I don't have a GPU) |

Tech stack

<table> <tr> <th>Logo</th> <th>Name</th> <th>Description</th> </tr> <tr> <td><img width="32" src="https://simpleicons.org/icons/ansible.svg"></td> <td><a href="https://www.ansible.com">Ansible</a></td> <td>Automate bare metal provisioning and configuration</td> </tr> <tr> <td><img width="32" src="https://avatars.githubusercontent.com/u/30269780"></td> <td><a href="https://argoproj.github.io/cd">ArgoCD</a></td> <td>GitOps tool built to deploy applications to Kubernetes</td> </tr> <tr> <td><img width="32" src="https://github.com/jetstack/cert-manager/raw/master/logo/logo.png"></td> <td><a href="https://cert-manager.io">cert-manager</a></td> <td>Cloud native certificate management</td> </tr> <tr> <td><img width="32" src="https://avatars.githubusercontent.com/u/21054566?s=200&v=4"></td> <td><a href="https://cilium.io">Cilium</a></td> <td>eBPF-based Networking, Observability and Security (CNI, LB, Network Policy, etc.)</td> </tr> <tr> <td><img width="32" src="https://avatars.githubusercontent.com/u/314135?s=200&v=4"></td> <td><a href="https://www.cloudflare.com">Cloudflare</a></td> <td>DNS and Tunnel</td> </tr> <tr> <td><img width="32" src="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"></td> <td><a href="https://www.docker.com">Docker</a></td> <td>Ephemeral PXE server</td> </tr> <tr> <td><img width="32" src="https://github.com/kubernetes-sigs/external-dns/raw/master/docs/img/external-dns.png"></td> <td><a href="https://github.com/kubernetes-sigs/external-dns">ExternalDNS</a></td> <td>Synchronizes exposed Kubernetes Services and Ingresses with DNS providers</td> </tr> <tr> <td><img width="32" src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Fedora_logo.svg/267px-Fedora_logo.svg.png"></td> <td><a href="https://getfedora.org/en/server">Fedora Server</a></td> <td>Base OS for Kubernetes nodes</td> </tr> <tr> <td><img width="32" src="https://upload.wikimedia.org/wikipedia/commons/b/bb/Gitea_Logo.svg"></td> <td><a href="https://gitea.com">Gitea</a></td> <td>Self-hosted Git service</td> </tr> <tr> <td><img width="32" src="https://grafana.com/static/img/menu/grafana2.svg"></td> <td><a href="https://grafana.com">Grafana</a></td> <td>Observability platform</td> </tr> <tr> <td><img width="32"