Homelab

! ⚠️ WORK IN PROGRESS

Overview

Hardware

• 4 nodes of 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

Technology stack

Ansible	Docker	Rocky Linux	K3s	Kubernetes
ArgoCD	Helm	Longhorn	Prometheus	Vault
Gitea	Tekton	Knative

This list might be outdated, please let me know if I forgot to update it.

Provisioning flow

Everything is automated, I just need to run a single make command and it will:

• Build the ./metal layer:
  • Create an ephemeral, stateless PXE server
  • Install Linux on all servers in parallel
  • Build a Kubernetes cluster (based on k3s)
• Build the ./bootstrap layer:
  • Install ArgoCD
  • Install ApplicationSet to manage other layers (and also manage itself)

From now on, ArgoCD will do the rest:

• Build the ./system layer (storage, networking, monitoring, etc)
• Build the ./platform layer (Gitea, Vault, SSO, etc)
• Build the ./apps layer: (Syncthing, Jellyfin, etc)

Please visit the Provisioning flow document to learn more.

Get Started

Harware requirements

Any modern x86_64 computer(s) should work, you can use old PCs, laptops or servers. A total of 3 or more nodes is recommended for high availability.

To view the detailed requirements, please visit the Hareware requirements document.

Prerequisite

For the controller (your laptop or desktop):

• SSH keys in ~/.ssh/{id_ed25519,id_ed25519.pub} (you can generate it with ssh-keygen -t ed25519)
• Docker with host networking driver (which means only Docker on Linux hosts, you can use a Linux virtual machine with bridged networking if you're on macOS or Windows)

For bare metal nodes:

• PXE IPv4 enabled
• Wake-on-LAN enabled and boot to network mode by default if turned on via Wake-on-LAN
• Secure boot disabled (optional, depending on the OS)
• Note their MAC addresses

To view the detailed instruction, please visit the Prerequisite document.

Configurations

Change these configuration files to match your hardware and network setup:

• Bare metal nodes settings (IP, MAC...)
• OS settings (PXE, network...)

To view the detailed instruction, please visit the Configuration document.

Build

You can install all the tools manually, or you can use the convenience tools container:

make tools

Then build the homelab:

make

If you encounter any issue, please visit Trouble shooting guide

Roadmap

See roadmap and open issues for a list of proposed features and known issues.

Contributing

Any contributions you make are greatly appreciated (feature, bug fixes, documentation, grammar or typo fix...).

License

Distributed under the GPLv3 License. See LICENSE for more information.

Acknowledgements

• ArgoCD usage in my coworker's homelab
• README template
• Run the same Cloudflare Tunnel across many cloudflared processes
• MAC address environment variable in GRUB config
• Official k3s systemd service file
• AWS Dex setup guide on EKS