236 lines
8 KiB
Markdown
236 lines
8 KiB
Markdown
# Build KiteStacks with AI (Claude Code)
|
|
|
|
This path uses Claude Code to set up the homelab. You describe what you want, Claude writes the configs, and you verify the results. Each section gives you the exact prompt to use.
|
|
|
|
**How to use this guide:**
|
|
1. Open Claude Code in your terminal: `claude`
|
|
2. Copy-paste the prompt for each section
|
|
3. Read Claude's explanation of what it did and why
|
|
4. Verify the result (Claude will tell you how to test)
|
|
5. Move to the next section
|
|
|
|
---
|
|
|
|
## Step 1 — Docker Foundation
|
|
|
|
**Prompt:**
|
|
```
|
|
I'm building a homelab on Ubuntu 24.04. Help me:
|
|
1. Install Docker Engine (not Docker Desktop) and Docker Compose v2
|
|
2. Add my user to the docker group so I don't need sudo
|
|
3. Create a shared Docker bridge network called "kitestacks" that all my containers will use
|
|
4. Verify Docker is working correctly
|
|
|
|
Explain what each command does as you go.
|
|
```
|
|
|
|
**What to verify:** `docker network ls` shows `kitestacks` in the list.
|
|
|
|
---
|
|
|
|
## Step 2 — Cloudflare Tunnel
|
|
|
|
**Prompt:**
|
|
```
|
|
I have a domain on Cloudflare and want to set up a Cloudflare Zero Trust Tunnel so my homelab services are accessible publicly without opening ports on my router.
|
|
|
|
Help me:
|
|
1. Create a cloudflared Docker container that connects to Cloudflare Tunnel
|
|
2. Store the tunnel token securely in a .env file
|
|
3. Set up the container on the "kitestacks" Docker network
|
|
4. Add the first hostname route in Cloudflare Zero Trust for my portal (www.kitestacks.com → http://homepage:80)
|
|
5. Verify the tunnel is connected
|
|
|
|
My domain is kitestacks.com. I want the cloudflared container at ~/kitestacks-live/docker/cloudflared/
|
|
```
|
|
|
|
**What to verify:** Cloudflare Zero Trust → Networks → Tunnels shows 1 healthy connector.
|
|
|
|
---
|
|
|
|
## Step 3 — Authentik (SSO)
|
|
|
|
**Prompt:**
|
|
```
|
|
I want to set up Authentik as my SSO identity provider. It will handle login for all my homelab services via OIDC/OAuth2.
|
|
|
|
Help me:
|
|
1. Create a docker-compose.yml for Authentik (server + worker + PostgreSQL + Redis)
|
|
2. Put it at ~/kitestacks-live/docker/authentik/
|
|
3. Connect it to the "kitestacks" network
|
|
4. Set up the Cloudflare Tunnel hostname: auth.kitestacks.com → http://authentik:9000
|
|
5. Complete the initial Authentik admin setup
|
|
6. Explain what each Authentik component does (server, worker, postgres, redis)
|
|
|
|
I want to understand OIDC flow — explain how a user logging into Grafana through Authentik actually works, step by step.
|
|
```
|
|
|
|
**What to verify:** Browse to `https://auth.kitestacks.com` — Authentik login page appears.
|
|
|
|
---
|
|
|
|
## Step 4 — Portainer
|
|
|
|
**Prompt:**
|
|
```
|
|
Set up Portainer CE for Docker management at ~/kitestacks-live/docker/portainer/.
|
|
|
|
Requirements:
|
|
- Connect to "kitestacks" Docker network
|
|
- Mount /var/run/docker.sock so it can manage containers
|
|
- Set up the Cloudflare Tunnel route: portainer.kitestacks.com → https://portainer:9443
|
|
- Configure Authentik SSO (OAuth2) so I log in with my Authentik account
|
|
|
|
After setup, explain:
|
|
- Why Portainer needs the Docker socket
|
|
- Why OAuth users need to be pre-created as admin before first login
|
|
- How to reset the admin password if I get locked out
|
|
```
|
|
|
|
---
|
|
|
|
## Step 5 — Forgejo (Git)
|
|
|
|
**Prompt:**
|
|
```
|
|
Set up Forgejo (self-hosted Git) at ~/kitestacks-live/docker/forgejo/.
|
|
|
|
Requirements:
|
|
- Connect to "kitestacks" network
|
|
- Port 2222 for SSH git, 3006 for web
|
|
- Cloudflare Tunnel route: gitforge.kitestacks.com → http://forgejo:3000
|
|
- Configure Authentik OIDC SSO
|
|
|
|
Explain:
|
|
- Why I should use SSH key auth for git operations instead of HTTPS
|
|
- How to generate an API token for automation
|
|
- How gitforge.kitestacks.com/SSH port 2222 both work through Cloudflare
|
|
```
|
|
|
|
---
|
|
|
|
## Step 6 — BookStack (Wiki)
|
|
|
|
**Prompt:**
|
|
```
|
|
Set up BookStack wiki at ~/kitestacks-live/docker/bookstack/ with Authentik SSO.
|
|
|
|
Requirements:
|
|
- BookStack + MariaDB containers
|
|
- APP_URL=https://wiki.kitestacks.com
|
|
- Authentik OIDC SSO configured (AUTH_METHOD=oidc)
|
|
- Cloudflare Tunnel route: wiki.kitestacks.com → http://bookstack:80
|
|
|
|
I've already set up an OAuth2 provider in Authentik for BookStack.
|
|
The provider is named "bookstack".
|
|
|
|
Important: explain the OIDC_ISSUER_DISCOVER setting and why it matters.
|
|
Also explain why the Authentik provider needs issuer_mode=per_provider for BookStack to work.
|
|
```
|
|
|
|
**What to verify:** Browse to `https://wiki.kitestacks.com`, click "Login with Authentik" — should redirect to Authentik login page.
|
|
|
|
---
|
|
|
|
## Step 7 — Monitoring Stack
|
|
|
|
**Prompt:**
|
|
```
|
|
Set up a monitoring stack for my homelab:
|
|
|
|
1. Prometheus at ~/kitestacks-live/docker/prometheus/
|
|
- Scrape node-exporter on localhost and on my cloud VPS public IP
|
|
|
|
2. Node Exporter (sidecar alongside Prometheus or standalone)
|
|
- Expose host metrics (CPU, RAM, disk, network)
|
|
|
|
3. Grafana at ~/kitestacks-live/docker/grafana/
|
|
- Connect to Prometheus as data source
|
|
- Authentik SSO configured
|
|
- Cloudflare Tunnel route: grafana.kitestacks.com → http://grafana:3000
|
|
|
|
Explain:
|
|
- The difference between Prometheus pull model vs push model
|
|
- Why node-exporter needs to be on the HOST network to see real metrics
|
|
- How Grafana dashboards are structured (data sources → panels → rows)
|
|
```
|
|
|
|
---
|
|
|
|
## Step 8 — Application Services
|
|
|
|
**Prompt:**
|
|
```
|
|
Set up these application services, each with Authentik SSO where applicable:
|
|
|
|
1. Karakeep (bookmark manager) at ~/kitestacks-live/docker/karakeep/
|
|
- Includes karakeep-chrome and karakeep-meilisearch
|
|
- Cloudflare Tunnel: links.kitestacks.com → http://karakeep:3000
|
|
|
|
2. Kavita (ebook reader) at ~/kitestacks-live/docker/kavita/
|
|
- Mount my books folder at /mnt/books
|
|
- Cloudflare Tunnel: kavita.kitestacks.com → http://kavita:5000
|
|
|
|
3. OSTicket (help desk) at ~/kitestacks-live/docker/osticket/
|
|
- With MariaDB
|
|
- SMTP configured for email notifications
|
|
- Cloudflare Tunnel: tasks.kitestacks.com → http://osticket:8080
|
|
|
|
For each, explain what the service does and why it's useful in a homelab.
|
|
```
|
|
|
|
---
|
|
|
|
## Step 9 — Portal (Homepage)
|
|
|
|
**Prompt:**
|
|
```
|
|
I have a custom portal at ~/kitestacks-live/docker/kitestacks-portal/
|
|
It's a static HTML/CSS/JS site served by nginx with a cyberpunk theme.
|
|
|
|
Help me set up:
|
|
1. nginx container serving the static files
|
|
2. A Python FastAPI metrics API (kitestacks-metrics-api) that provides:
|
|
- Real-time system stats (CPU, RAM, disk, network) using psutil
|
|
- Weather data from wttr.in
|
|
- Recent git activity from my Forgejo API
|
|
3. nginx proxy_pass /api/* → metrics API
|
|
|
|
The metrics API needs network_mode: host and pid: host to read real host stats.
|
|
|
|
Explain why host networking is needed and what pid: host does.
|
|
```
|
|
|
|
---
|
|
|
|
## Step 10 — Cloud Replica (kscloud1)
|
|
|
|
**Prompt:**
|
|
```
|
|
I want to add a Hetzner VPS (Ubuntu 24.04, 3 vCPU, 3.7GB RAM) as a cloud replica
|
|
of my homelab. Both my home machine and the VPS should serve the same services
|
|
via active-active Cloudflare Tunnel.
|
|
|
|
Help me:
|
|
1. Set up Tailscale on both machines for private networking
|
|
2. Move the Authentik PostgreSQL + Redis to the VPS (both machines share this DB)
|
|
3. Deploy all services on the VPS using the same docker-compose files
|
|
4. Add a second cloudflared connector on the VPS using the same tunnel token
|
|
5. Verify failover works (stop services on one host, verify the other serves traffic)
|
|
|
|
Explain:
|
|
- Why active-active is better than active-passive for this use case
|
|
- Why the shared DB must be on Tailscale (not public internet)
|
|
- What happens when my home machine is offline but the VPS is up
|
|
```
|
|
|
|
---
|
|
|
|
## Tips for Using Claude Code Effectively
|
|
|
|
- **Be specific about file paths.** "Put it at ~/kitestacks-live/docker/bookstack/" saves back-and-forth.
|
|
- **Ask for explanations.** "Explain what OIDC_ISSUER_DISCOVER does" teaches you concepts as you build.
|
|
- **Ask about failure modes.** "What breaks if X goes down?" is a great follow-up to every setup step.
|
|
- **Verify before moving on.** Each step has a verification — do it before asking for the next step.
|
|
- **Keep the conversation going.** If something fails, paste the error. Claude remembers what it configured and can fix it.
|
|
- **Ask "why not X."** "Why not just use HTTPS on my router instead of Cloudflare Tunnel?" gets you the trade-off analysis that sticks in memory.
|