Repository: khuedoan/homelab
Stars: 9196
README.md
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-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 and eBPF |
| [![][homepage-demo]][homepage-demo] |
| Homepage powered by... Homepage |
| [![][grafana-demo]][grafana-demo] |
| Monitoring dashboard powered by Grafana |
| [![][gitea-demo]][gitea-demo] |
| Git server powered by Gitea |
| [![][matrix-demo]][matrix-demo] |
| Matrix chat server |
| [![][woodpecker-demo]][woodpecker-demo] |
| Continuous integration with Woodpecker CI |
| [![][argocd-demo]][argocd-demo] |
| Continuous deployment with ArgoCD |
| [![][alert-demo]][alert-demo] |
| ntfy displaying received alerts |
| [![][ai-demo]][ai-demo] |
| Self-hosted AI powered by Ollama (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
<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" src="https://helm.sh/img/helm.svg"></td>
<td><a href="https://helm.sh">Helm</a></td>
<td>The package manager for Kubernetes</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/49319725"></td>
<td><a href="https://k3s.io">K3s</a></td>
<td>Lightweight distribution of Kubernetes</td>
</tr>
<tr>
<td><img width="32" src="https://kanidm.com/images/logo.svg"></td>
<td><a href="https://kanidm.com">Kanidm</a></td>
<td>Modern and simple identity management platform</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/13629408"></td>
<td><a href="https://kubernetes.io">Kubernetes</a></td>
<td>Container-orchestration system, the backbone of this project</td>
</tr>
<tr>
<td><img width="32" src="https://github.com/grafana/loki/blob/main/docs/sources/logo.png?raw=true"></td>
<td><a href="https://grafana.com/oss/loki">Loki</a></td>
<td>Log aggregation system</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/1412239?s=200&v=4"></td>
<td><a href="https://www.nginx.com">NGINX</a></td>
<td>Kubernetes Ingress Controller</td>
</tr>
<tr>
<td><img width="32" src="https://raw.githubusercontent.com/NixOS/nixos-artwork/refs/heads/master/logo/nix-snowflake-colours.svg"></td>
<td><a href="https://nixos.org">Nix</a></td>
<td>Convenient development shell</td>
</tr>
<tr>
<td><img width="32" src="https://ntfy.sh/_next/static/media/logo.077f6a13.svg"></td>
<td><a href="https://ntfy.sh">ntfy</a></td>
<td>Notification service to send notifications to your phone or desktop</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/3380462"></td>
<td><a href="https://prometheus.io">Prometheus</a></td>
<td>Systems monitoring and alerting toolkit</td>
</tr>
<tr>
<td><img width="32" src="https://docs.renovatebot.com/assets/images/logo.png"></td>
<td><a href="https://www.whitesourcesoftware.com/free-developer-tools/renovate">Renovate</a></td>
<td>Automatically update dependencies</td>
</tr>
<tr>
<td><img width="32" src="https://raw.githubusercontent.com/rook/artwork/master/logo/blue.svg"></td>
<td><a href="https://rook.io">Rook Ceph</a></td>
<td>Cloud-Native Storage for Kubernetes</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/48932923?s=200&v=4"></td>
<td><a href="https://tailscale.com">Tailscale</a></td>
<td>VPN without port forwarding</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/13991055?s=200&v=4"></td>
<td><a href="https://www.wireguard.com">Wireguard</a></td>
<td>Fast, modern, secure VPN tunnel</td>
</tr>
<tr>
<td><img width="32" src="https://avatars.githubusercontent.com/u/84780935?s=200&v=4"></td>
<td><a href="https://woodpecker-ci.org">Woodpecker CI</a></td>
<td>Simple yet powerful CI/CD engine with great extensibility</td>
</tr>
<tr>
<td><img width="32" src="https://zotregistry.dev/v2.0.2/assets/images/logo.svg"></td>
<td><a href="https://zotregistry.dev">Zot Registry</a></td>
<td>Private container registry</td>
</tr>
</table>
Get Started
- Try it out locally without any hardware (just 4 commands!)
- Deploy on real hardware for production workload
Roadmap
See roadmap and open issues for a list of proposed features and known issues.
Contributing
Any contributions you make are greatly appreciated.
Please see contributing guide for more information.
License
Copyright © 2020 - 2024 Khue Doan
Distributed under the GPLv3 License.
See license page or LICENSE.md file for more information.
Acknowledgements
References:
- Ephemeral PXE server inspired by Minimal First Machine in the DC
- ArgoCD usage and monitoring configuration in locmai/humble
- README template
- Run the same Cloudflare Tunnel across many cloudflared processes
- MAC address environment variable in GRUB config
- Official k3s systemd service file
- Official Cloudflare Tunnel examples
- Initialize GitOps repository on Gitea and integrate with Tekton by RedHat
- SSO configuration from xUnholy/k8s-gitops
- Pre-commit config from k8s-at-home/flux-cluster-template
- Diátaxis technical documentation framework
- Official Terratest examples
- Self-host an automated Jellyfin media streaming stack
- App Template Helm chart by bjw-s
- Various application configurations in onedr0p/home-ops
Here is a list of the contributors who have helped to improve this project.
Big shout-out to them!
- <img width="24" height="24" src="https://github.com/locmai.png?size=24" /> @locmai
- <img width="24" height="24" src="https://github.com/MatthewJohn.png?size=24" /> @MatthewJohn
- <img width="24" height="24" src="https://github.com/karpfediem.png?size=24" /> @karpfediem
- <img width="24" height="24" src="https://github.com/linhng98.png?size=24" /> @linhng98
- <img width="24" height="24" src="https://github.com/elliotblackburn.png?size=24" /> @elliotblackburn
- <img width="24" height="24" src="https://github.com/dotdiego.png?size=24" /> @dotdiego
- <img width="24" height="24" src="https://github.com/Crimrose.png?size=24" /> @Crimrose
- <img width="24" height="24" src="https://github.com/eventi.png?size=24" /> @eventi
- <img width="24" height="24" src="https://github.com/Bourne-ID.png?size=24" /> @Bourne-ID
- <img width="24" height="24" src="https://github.com/akwan.png?size=24" /> @akwan
- <img width="24" height="24" src="https://github.com/trangmaiq.png?size=24" /> @trangmaiq
- <img width="24" height="24" src="https://github.com/tangowithfoxtrot.png?size=24" /> @tangowithfoxtrot
- <img width="24" height="24" src="https://github.com/raedkit.png?size=24" /> @raedkit
- <img width="24" height="24" src="https://github.com/ClashTheBunny.png?size=24" /> @ClashTheBunny
- <img width="24" height="24" src="https://github.com/retX0.png?size=24" /> @retX0
- <img width="24" height="24" src="https://github.com/zalsader.png?size=24" /> @zalsader
- <img width="24" height="24" src="https://github.com/serpro69.png?size=24" /> @serpro69
- <img width="24" height="24" src="https://github.com/llajas.png?size=24" /> @llajas
- <img width="24" height="24" src="https://github.com/zalsader.png?size=24" /> @zalsader
If you feel you're missing from this list, please feel free to add yourself in a PR.
Stargazers over time
