| .. | ||
| README.md | ||
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.
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.
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).
Prerequisites (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 |
| 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 |
High-Level Build Order
Regardless of which path you take, build in this order:
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
Each layer depends on the one before it. Don't skip ahead.