kenpat/homelab-mastery
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite architecture overview and build guide in simple plain-English

Browse source 
Both docs now use everyday analogies (Cloudflare = post office, Authentik = doorman)
instead of technical jargon, making them accessible to anyone learning the project.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
kenpat 2026-06-18 18:46:47 -05:00
parent c3eedf91af
commit 4f91c42780
2 changed files with 145 additions and 157 deletions
Download patch file Download diff file Expand all files Collapse all files

53
build-guide/README.md
View file

@ -1,52 +1,53 @@
# KiteStacks Build Guide
This guide walks you through rebuilding the entire KiteStacks homelab from scratch on a blank machine. Two paths are available — choose the one that fits how you work.
This guide walks you through rebuilding the entire KiteStacks homelab from scratch
on a blank machine. Two paths are available — choose the one that fits how you work.
---
## Choose Your Path
### Path A — With AI (Claude Code)
You provide the high-level goals, Claude Code writes the configs, debugs the errors, and explains every decision. Fastest path. Best for learning while doing.
Tell Claude Code what you want to build. Claude writes the configs, debugs errors,
and explains every decision as it goes. Fastest path. Great for learning while doing.
→ [Build with AI](./with-ai/README.md)
### Path B — Manual (No AI)
Step-by-step instructions you follow yourself. Every command, every config, every file. Best for deep understanding and exam prep (answering "how does this work" in interviews).
### Path B — Do It Yourself
Step-by-step instructions where you type every command yourself. Every config, every
file, explained. Best for really understanding how things work — great for exam prep.
→ [Build Manually](./without-ai/README.md)
---
## Prerequisites (Both Paths)
## What You Need Before Starting (Both Paths)
Before starting either path, have the following ready:
| Requirement | Details |
|-------------|---------|
| A Linux machine | Ubuntu 24.04+ or CachyOS/Arch recommended. At least 16GB RAM, 500GB SSD |
| A Cloudflare account | Free tier is fine. You need a domain pointed to Cloudflare |
| What you need | Details |
|---------------|---------|
| A Linux computer | Ubuntu 24.04 recommended. At least 16GB RAM, 500GB SSD |
| A Cloudflare account | Free tier. You need a domain name pointed to Cloudflare |
| A domain name | Any registrar works — point nameservers to Cloudflare |
| A Hetzner account (optional) | For the cloud replica (kscloud1). CAX11 or CX22 works |
| A Tailscale account | Free tier — needed for the private overlay network |
| Docker + Docker Compose | Install before starting either path |
| A Hetzner account (optional) | For the cloud backup machine (kscloud1). Any small VPS works |
| A Tailscale account | Free — creates the private network between machines |
| Docker installed | The foundation everything runs on |
---
## High-Level Build Order
## Build Order (Both Paths Follow This)
Regardless of which path you take, build in this order:
Build in this order — each step depends on the one before it:
```
1. Docker + networking foundation
2. Cloudflare Tunnel (cloudflared)
3. Authentik (SSO identity provider)
4. Core services (Portainer, Forgejo, BookStack)
5. Monitoring (Prometheus, Node Exporter, Grafana)
6. Application services (Karakeep, Kavita, OSTicket)
7. AI services (Open WebUI, LiteLLM)
8. Portal (homepage + metrics API)
9. kscloud1 cloud replica
Step 1: Install Docker and set up networking
Step 2: Set up Cloudflare Tunnel (the secret post-office connection)
Step 3: Set up Authentik (the single login system)
Step 4: Set up core services (Portainer, Forgejo, BookStack)
Step 5: Set up monitoring (Prometheus, Node Exporter, Grafana)
Step 6: Set up app services (Karakeep, Kavita, OSTicket)
Step 7: Set up AI services (Open WebUI, LiteLLM)
Step 8: Set up the portal (main homepage)
Step 9: Add the cloud backup machine (kscloud1)
```
Each layer depends on the one before it. Don't skip ahead.
Don't skip ahead — if you skip Authentik, none of the SSO logins will work.