khuedoan-homelab/README.md

Homelab

⚠️ WORK IN PROGRESS

Hardware

• 4 nodes of NEC SFF PC PC-MK26ECZDR (Japanese version of the ThinkCentre M700)
  • CPU: Intel Core i5-6600T
  • RAM: 16GB
  • SSD: 128GB
• TP-Link TL-SG108 switch

Technology stack

Ansible	Cloudflare	Docker	Fedora	Gitea	Helm
Kubernetes	Prometheus	Rancher	Terraform	Vault	Wireguard

Architecture

Quick explanation

A single make command will build the following directories (layers):

• Build ./metal layer:
  • Ansible renders the configuration file for each bare metal machine (like IP, hostname...) and the PXE server from templates
  • The tools container creates sibling containers to build a PXE server (includes DHCP, TFTP and HTTP server)
  • Ansible wake the machines up using Wake on LAN
  • The machine start the boot process, the OS get installed (through PXE server) and the machine reboots to the new operating system
  • Ansible performs some basic configuration on the machine (like install Docker)
  • Ansible creates a Terraform state backend and generates the configuration file for it
• Build ./infra layer:
  • Terraform initialize using the backend configuration generated in the ./metal layer
  • Terraform creates a Kubernetes cluster using RKE
  • Terraform install some Helm chart for bootstrap
  • Terraform generate the Kubernetes config file
• Build ./apps layer:
  • Kustomize creates Argo applications using the Kubernetes config file generated in the ./infra layer
  • ArgoCD install those applications

Layers

Layer	Name	Description	Provisioner
0	metal	Bare metal OS installation, Terraform state backend,...	Ansible, PXE server
1	infra	Kubernetes clusters	Terraform, Helm
2	apps	Gitea, Vault and more in the future	Kustomize, ArgoCD

Get Started

Prerequisite

For the controller (to run Ansible, stateless PXE server, Terraform...):

• 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

Configurations

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

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

Build

Open the tools container:

make tools

Then build the homelab:

make

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