# Khue's Homelab **[Features](#features) • [Get Started](#get-started) • [Documentation](https://homelab.khuedoan.com)** [![tag](https://img.shields.io/github/v/tag/khuedoan/homelab?style=flat-square&logo=semver&logoColor=white)](https://github.com/khuedoan/homelab/tags) [![document](https://img.shields.io/website?label=document&logo=gitbook&logoColor=white&style=flat-square&url=https%3A%2F%2Fhomelab.khuedoan.com)](https://homelab.khuedoan.com) [![license](https://img.shields.io/github/license/khuedoan/homelab?style=flat-square&logo=gnu&logoColor=white)](https://www.gnu.org/licenses/gpl-3.0.html) [![stars](https://img.shields.io/github/stars/khuedoan/homelab?logo=github&logoColor=white&color=gold&style=flat-square)](https://github.com/khuedoan/homelab) This project utilizes [Infrastructure as Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) and [GitOps](https://www.weave.works/technologies/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](https://www.reddit.com/r/homelab/wiki/introduction) and the > [Home Operations Discord community](https://discord.gg/home-operations) (formerly known as [k8s-at-home](https://k8s-at-home.com)). ## 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](#roadmap) below. ### Hardware ![Hardware](https://user-images.githubusercontent.com/27996771/98970963-25137200-2543-11eb-8f2d-f9a2d45756ef.JPG) - 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](https://www.cloudflare.com/products/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-demo]](https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7) | | Deploy with a single command (after updating the configuration files) | | [![][pxe-demo]](https://www.youtube.com/watch?v=y-d7btNNAT8) | | PXE boot | | [![][hubble-demo]][hubble-demo] | | Observe network traffic with Hubble, built on top of [Cilium](https://cilium.io) and eBPF | | [![][homepage-demo]][homepage-demo] | | Homepage powered by... [Homepage](https://gethomepage.dev) | | [![][grafana-demo]][grafana-demo] | | Monitoring dashboard powered by [Grafana](https://grafana.com) | | [![][gitea-demo]][gitea-demo] | | Git server powered by [Gitea](https://gitea.io/en-us) | | [![][matrix-demo]][matrix-demo] | | [Matrix](https://matrix.org/) chat server | | [![][woodpecker-demo]][woodpecker-demo] | | Continuous integration with [Woodpecker CI](https://woodpecker-ci.org) | | [![][argocd-demo]][argocd-demo] | | Continuous deployment with [ArgoCD](https://argoproj.github.io/cd) | | [![][alert-demo]][alert-demo] | | [ntfy](https://ntfy.sh) displaying received alerts | | [![][ai-demo]][ai-demo] | | Self-hosted AI powered by [Ollama](https://ollama.com) (experimental, not very fast because I don't have a GPU) | [deploy-demo]: https://asciinema.org/a/xkBRkwC6e9RAzVuMDXH3nGHp7.svg [pxe-demo]: https://user-images.githubusercontent.com/27996771/157303477-df2e7410-8f02-4648-a86c-71e6b7e89e35.png [hubble-demo]: https://github.com/khuedoan/homelab/assets/27996771/9c6677d0-3564-47c0-852b-24b6a554b4a3 [homepage-demo]: https://github.com/khuedoan/homelab/assets/27996771/d0eaf620-be08-48d8-8420-40bcaa86093b [grafana-demo]: https://github.com/khuedoan/homelab/assets/27996771/ad937b26-e9bc-4761-83ae-1c7f512ea97f [gitea-demo]: https://github.com/khuedoan/homelab/assets/27996771/c245534f-88d9-4565-bde8-b39f60ccee9e [matrix-demo]: https://user-images.githubusercontent.com/27996771/149448510-7163310c-2049-4ccd-901d-f11f605bfc32.png [woodpecker-demo]: https://github.com/khuedoan/homelab/assets/27996771/5d887688-d20a-44c8-8f77-0c625527dfe4 [argocd-demo]: https://github.com/khuedoan/homelab/assets/27996771/527e2529-4fe1-4664-ab8a-b9eb3c492d20 [alert-demo]: https://github.com/khuedoan/homelab/assets/27996771/c922f755-e911-4ca0-9d4a-6e552d387f18 [ai-demo]: https://github.com/khuedoan/homelab/assets/27996771/d77ba511-00b7-47c3-9032-55679a099e70 ### Tech stack
Logo Name Description
Ansible Automate bare metal provisioning and configuration
ArgoCD GitOps tool built to deploy applications to Kubernetes
cert-manager Cloud native certificate management
Cilium eBPF-based Networking, Observability and Security (CNI, LB, Network Policy, etc.)
Cloudflare DNS and Tunnel
Docker Ephemeral PXE server
ExternalDNS Synchronizes exposed Kubernetes Services and Ingresses with DNS providers
Fedora Server Base OS for Kubernetes nodes
Gitea Self-hosted Git service
Grafana Observability platform
Helm The package manager for Kubernetes
K3s Lightweight distribution of Kubernetes
Kanidm Modern and simple identity management platform
Kubernetes Container-orchestration system, the backbone of this project
Loki Log aggregation system
NGINX Kubernetes Ingress Controller
Nix Convenient development shell
ntfy Notification service to send notifications to your phone or desktop
Prometheus Systems monitoring and alerting toolkit
Renovate Automatically update dependencies
Rook Ceph Cloud-Native Storage for Kubernetes
Tailscale VPN without port forwarding
Wireguard Fast, modern, secure VPN tunnel
Woodpecker CI Simple yet powerful CI/CD engine with great extensibility
Zot Registry Private container registry
## Get Started - [Try it out locally](https://homelab.khuedoan.com/installation/sandbox) without any hardware (just 4 commands!) - [Deploy on real hardware](https://homelab.khuedoan.com/installation/production/prerequisites) for production workload ## Roadmap See [roadmap](https://homelab.khuedoan.com/reference/roadmap) and [open issues](https://github.com/khuedoan/homelab/issues) for a list of proposed features and known issues. ## Contributing Any contributions you make are greatly appreciated. Please see [contributing guide](https://homelab.khuedoan.com/reference/contributing) for more information. ## License Copyright © 2020 - 2024 Khue Doan Distributed under the GPLv3 License. See [license page](https://homelab.khuedoan.com/reference/license) or `LICENSE.md` file for more information. ## Acknowledgements References: - [Ephemeral PXE server inspired by Minimal First Machine in the DC](https://speakerdeck.com/amcguign/minimal-first-machine-in-the-dc) - [ArgoCD usage and monitoring configuration in locmai/humble](https://github.com/locmai/humble) - [README template](https://github.com/othneildrew/Best-README-Template) - [Run the same Cloudflare Tunnel across many `cloudflared` processes](https://developers.cloudflare.com/cloudflare-one/tutorials/many-cfd-one-tunnel) - [MAC address environment variable in GRUB config](https://askubuntu.com/questions/1272400/how-do-i-automate-network-installation-of-many-ubuntu-18-04-systems-with-efi-and) - [Official k3s systemd service file](https://github.com/k3s-io/k3s/blob/master/k3s.service) - [Official Cloudflare Tunnel examples](https://github.com/cloudflare/argo-tunnel-examples) - [Initialize GitOps repository on Gitea and integrate with Tekton by RedHat](https://github.com/redhat-scholars/tekton-tutorial/tree/master/triggers) - [SSO configuration from xUnholy/k8s-gitops](https://github.com/xUnholy/k8s-gitops) - [Pre-commit config from k8s-at-home/flux-cluster-template](https://github.com/k8s-at-home/flux-cluster-template) - [Diátaxis technical documentation framework](https://diataxis.fr) - [Official Terratest examples](https://github.com/gruntwork-io/terratest/tree/master/test) - [Self-host an automated Jellyfin media streaming stack](https://zerodya.net/self-host-jellyfin-media-streaming-stack) - [App Template Helm chart by bjw-s](https://bjw-s.github.io/helm-charts/docs/app-template) - [Various application configurations in onedr0p/home-ops](https://github.com/onedr0p/home-ops) Here is a list of the contributors who have helped to improve this project. Big shout-out to them! - ![](https://github.com/locmai.png?size=24) [@locmai](https://github.com/locmai) - ![](https://github.com/MatthewJohn.png?size=24) [@MatthewJohn](https://github.com/MatthewJohn) - ![](https://github.com/karpfediem.png?size=24) [@karpfediem](https://github.com/karpfediem) - ![](https://github.com/linhng98.png?size=24) [@linhng98](https://github.com/linhng98) - ![](https://github.com/elliotblackburn.png?size=24) [@elliotblackburn](https://github.com/elliotblackburn) - ![](https://github.com/dotdiego.png?size=24) [@dotdiego](https://github.com/dotdiego) - ![](https://github.com/Crimrose.png?size=24) [@Crimrose](https://github.com/Crimrose) - ![](https://github.com/eventi.png?size=24) [@eventi](https://github.com/eventi) - ![](https://github.com/Bourne-ID.png?size=24) [@Bourne-ID](https://github.com/Bourne-ID) - ![](https://github.com/akwan.png?size=24) [@akwan](https://github.com/akwan) - ![](https://github.com/trangmaiq.png?size=24) [@trangmaiq](https://github.com/trangmaiq) - ![](https://github.com/tangowithfoxtrot.png?size=24) [@tangowithfoxtrot](https://github.com/tangowithfoxtrot) - ![](https://github.com/raedkit.png?size=24) [@raedkit](https://github.com/raedkit) - ![](https://github.com/ClashTheBunny.png?size=24) [@ClashTheBunny](https://github.com/ClashTheBunny) - ![](https://github.com/retX0.png?size=24) [@retX0](https://github.com/retX0) If you feel you're missing from this list, please feel free to add yourself in a PR. ## Stargazers over time [![Stargazers over time](https://starchart.cc/khuedoan/homelab.svg)](https://starchart.cc/khuedoan/homelab)