khuedoan/homelab: a single-command GitOps homelab for Kubernetes

What khuedoan/homelab solves, and for whom

Most homelab guides stop at the first shell prompt. You install a hypervisor, then a cluster, then a Git server, then a certificate issuer, and the steps live in your head. khuedoan/homelab packages that sequence as a repository. The README describes it as a project that uses Infrastructure as Code and GitOps to automate provisioning, operating and updating self-hosted services, and says it can be used as a highly customizable framework to build your own homelab.

The intended reader is someone who already owns several small machines and wants them managed declaratively. The author's own hardware is listed in the README: four NEC SFF PC-MK26ECZDR units, each with an Intel Core i5-6600T, 16GB of RAM and a 128GB SSD, plus a TP-Link TL-SG108 gigabit switch. That is a modest footprint. Nothing in the feature list requires server-grade equipment.

The repository is explicit about its stage. The README states the project status is ALPHA, that the author does not use anything critical on it, and that breaking changes may require a complete redeployment. Treat this as a framework to read and adapt, not a product to install and forget.

How the layers fit together: metal, system, external

The Makefile is the clearest map of the architecture. Its default target runs five stages in order: metal, system, external, smoke-test and post-install, followed by clean. Each stage is a sub-make in its own directory, so the repository is organised as a chain rather than a single playbook.

The metal stage handles bare metal provisioning, which the README lists as automated with PXE boot. The system stage covers Kubernetes installation and management, and the topics list names k3s as the distribution. The external stage covers components that live outside the cluster boundary. After that, a smoke test runs with `make -C test filter=Smoke`, and a post-install script applies local adjustments.

Application delivery is GitOps. The README lists ArgoCD for continuous deployment and Gitea as the Git server, with Helm charts under the apps directory. Once the cluster exists, the desired state lives in Git and ArgoCD reconciles it. The KUBECONFIG is pinned to `metal/kubeconfig.yaml` inside the repository, which tells you the whole flow is expected to run from a checkout on your workstation.

There is also a Nix flake at the root, so the toolchain can be pinned rather than installed by hand. The README does not document that flake, but its presence in the repository layout is a signal about how the author keeps builds reproducible.

Installing khuedoan/homelab: configure, then one command

The README points to the documentation site for setup instructions and does not reproduce the full procedure. What the repository does show is the entry point. The Makefile defines a configure target that runs `./scripts/configure` and then `git status`, so the expectation is that you edit configuration files and review the diff before deploying anything.

After configuration, the default target is the deployment command:

make

That single invocation expands to the five stages described above. The README's demo video is captioned "Deploy with a single command (after updating the configuration files)", which matches the Makefile exactly. If your machines are configured to PXE boot from the provisioning server, the metal stage should bring them up without manual installation media.

For a narrower run, the stages are exposed as individual targets:

make configure
make metal
make system
make external

Running them separately is how you would debug a failure, since the combined target stops at the first error. The repository also ships a Dockerfile that builds the documentation with mkdocs-material and serves it from nginx, which is how the public documentation site is produced rather than how the homelab itself runs.

Before any of this, run `make git-hooks` to install pre-commit hooks, and note that `make docs` serves the documentation locally if you want to read it offline.

The alpha status and redeployment cost

The README is unusually direct about the main limitation. Project status is ALPHA, the author does not run anything critical on it, and breaking changes may require a complete redeployment. A proper upgrade path is described as planned for the stable release. That means the upgrade story today is often "rebuild", not "update in place".

The release history reinforces this. The most recent release listed is v0.0.8 from 2022-07-26, preceded by v0.0.7-alpha. The repository itself shows a last push on 2026-09-08, so development continues on the master branch while tagged releases lag far behind. If you pin to a tag, you are pinning to something four years old. If you track master, you accept the alpha warning at face value.

The Makefile contains a telling comment above the backup targets: "TODO maybe there's a better way to manage backup with GitOps?". The backup and restore targets are hardcoded to two namespaces and two PVCs, actualbudget and jellyfin. Automated backup and restore is on the feature list, but the repository's own tooling for it is per-application and manual. Anyone with other stateful workloads should plan to extend `./scripts/backup` themselves.

This is the wrong tool if you want a supported distribution with a stable API. It is also the wrong tool if your hardware cannot network boot, since PXE provisioning is the foundation the rest of the flow assumes.

How it differs from k3s-at-home style setups

The nearest point of comparison is the pattern the README itself references: a hand-built cluster where you install k3s on existing machines and manage applications with Helm or ArgoCD. That approach starts from a working operating system and assumes you provisioned it yourself. khuedoan/homelab starts one layer lower, at the empty disk, and includes the PXE server that installs the OS.

The difference is where the work sits. In a k3s-at-home setup, adding a node means installing an OS by hand and joining it to the cluster. Here, the metal stage is supposed to handle that step, and the repository's own documentation build and testing targets are part of the same tree. The trade-off is that you inherit the author's hardware assumptions and the PXE server's network requirements.

A second comparison is a general-purpose configuration management tool such as Ansible alone. The topics list includes Ansible, and the repository does use it, but Ansible is only the mechanism for the metal and system stages. The organising principle is GitOps with ArgoCD, which means the cluster continuously reconciles against Git rather than being pushed to. That is a different operational model, and it is the part worth copying even if you do not copy the hardware layer.

Licence and the cost of staying current

The project is licensed GPL-3.0, as stated in the README badge and the LICENSE.md file at the repository root. For a personal homelab this has no practical consequence. If you fork the repository and distribute modified versions, the copyleft terms apply to what you distribute. This is a description of the licence, not legal advice; read LICENSE.md if distribution is part of your plan.

Upgrade cost is the more immediate concern. Because the README says breaking changes may require a complete redeployment, the realistic maintenance model is to keep your configuration in a fork, pull upstream changes deliberately, and expect to rebuild rather than patch. The configure script writing into tracked files and the subsequent `git status` in the configure target suggest the author works the same way, reviewing configuration drift as a diff before deploying.

There is a Renovate configuration file at the root, so dependency updates are at least partially automated upstream. That reduces the effort of tracking new component versions, but it does not create an upgrade path for your own cluster. The gap between the 2022 releases and the 2026 development activity is the clearest signal: judge this project by the master branch, not by its tags.

Editorial conclusion

Adopt khuedoan/homelab if you want a working reference for GitOps-driven bare metal provisioning and are willing to adapt the configuration files to your own hardware. Do not adopt it if you need a supported release with an upgrade path, or if your machines cannot PXE boot. Before committing, verify that the configure script and the metal, system and external make targets match your network and storage layout, and confirm you can reach the documentation site for the current component list.

Frequently asked questions

Official sources

1. khuedoan/homelab on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases