back to home

khuedoan / homelab

Fully automated homelab from empty disk to running services with a single command.

9,109 stars
865 forks
15 issues
PythonGoHCL
Chat with CodebaseArchitecture ScanSecurity AuditExplain Codebase

AI Architecture Analysis

This repository is indexed by RepoMind. By analyzing khuedoan/homelab in our AI interface, you can instantly generate complete architecture diagrams, visualize control flows, and perform automated security audits across the entire codebase.

Our Agentic Context Augmented Generation (Agentic CAG) engine loads full source files into context, avoiding the fragmentation of traditional RAG systems. Ask questions about the architecture, dependencies, or specific features to see it in action.

Click here to launch the interactive analysis workspace

Embed this Badge

Showcase RepoMind's analysis directly in your repository's README.

[![Analyzed by RepoMind](https://img.shields.io/badge/Analyzed%20by-RepoMind-4F46E5?style=for-the-badge)](https://repomind-ai.vercel.app/repo/khuedoan/homelab)
Preview:Analyzed by RepoMind

Repository Summary (README)

Preview

Khue's Homelab

Features • Get Started • Documentation

tag document license stars

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

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: Gitea, Jellyfin, Paperless...
  • Automated bare metal provisioning with PXE boot
  • Automated Kubernetes installation and management
  • Installing and managing applications using GitOps
  • Automatic rolling upgrade for OS and Kubernetes
  • Automatically update apps (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 (dev, prod)
  • 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 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" 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

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:

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

Stargazers over time