Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/khuedoan/homelab

Fully automated homelab from empty disk to running services with a single command.
https://github.com/khuedoan/homelab
ansible argocd devops docker fedora gitops helm home-operations homelab k3s k8s-at-home kubernetes netboot pxe self-hosting terraform
Last synced: 1 day ago
JSON representation
Fully automated homelab from empty disk to running services with a single command.
Host: GitHub
URL: https://github.com/khuedoan/homelab
Owner: khuedoan
License: gpl-3.0
Created: 2020-06-21T13:48:40.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2025-01-21T17:07:00.000Z (22 days ago)
Last Synced: 2025-02-04T12:46:35.217Z (9 days ago)
Topics: ansible, argocd, devops, docker, fedora, gitops, helm, home-operations, homelab, k3s, k8s-at-home, kubernetes, netboot, pxe, self-hosting, terraform
Language: Python
Homepage: https://homelab.khuedoan.com
Size: 1.38 MB
Stars: 8,386
Watchers: 82
Forks: 782
Open Issues: 13
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project

awesome-hacking-lists - khuedoan/homelab - Fully automated homelab from empty disk to running services with a single command. (Python)
README

        # 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)).

If you encounter an issue, please create [a bug report](https://github.com/khuedoan/homelab/issues/new?template=bug_report.md)

(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](#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)