kenpat
fb822d5142
- Rewrote RUNBOOK.md and DEBUG-DOCUMENTATION.md in simple 5th-grade language with real-world analogies for every technical concept - Updated README.md with current service inventory and folder map - Added cloud-migration/ subdirectory (from kitestacks-cloud-migration repo) - Added autosync/ subdirectory (from kitestacks-homelab-autosync-test repo) - Added osticket/ subdirectory (from OSTicketSystem repo) - Added cloud/ placeholder for future cloud configs - Excluded binary DB/postgres files from autosync subdirectory Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
339 lines
3.6 KiB
Markdown
339 lines
3.6 KiB
Markdown
# KiteStacks Homelab Documentation v1.3
|
|
|
|
## Overview
|
|
|
|
KiteStacks Homelab is a self-hosted infrastructure platform designed around Kubernetes, GitOps, observability, AI services, digital libraries, productivity applications, and identity management.
|
|
|
|
The homelab is currently operating in a hybrid state:
|
|
|
|
* Existing applications continue running in Docker
|
|
* Kubernetes (K3s) has been deployed successfully
|
|
* Forgejo serves as the private Git platform
|
|
* GitOps repository has been established
|
|
* Migration to Kubernetes will occur incrementally
|
|
|
|
---
|
|
|
|
# Infrastructure
|
|
|
|
## Primary Server
|
|
|
|
Hostname:
|
|
|
|
```text
|
|
assassin
|
|
```
|
|
|
|
Role:
|
|
|
|
```text
|
|
Primary Homelab Server
|
|
Kubernetes Control Plane
|
|
Docker Host
|
|
GitOps Management Node
|
|
```
|
|
|
|
Operating System:
|
|
|
|
```text
|
|
Debian 13
|
|
```
|
|
|
|
---
|
|
|
|
# Kubernetes
|
|
|
|
## Distribution
|
|
|
|
```text
|
|
K3s
|
|
```
|
|
|
|
Version:
|
|
|
|
```text
|
|
v1.35.5+k3s1
|
|
```
|
|
|
|
Status:
|
|
|
|
```text
|
|
Ready
|
|
```
|
|
|
|
Verification:
|
|
|
|
```bash
|
|
kubectl get nodes
|
|
```
|
|
|
|
Expected Result:
|
|
|
|
```text
|
|
assassin Ready control-plane
|
|
```
|
|
|
|
---
|
|
|
|
## Kubernetes Components
|
|
|
|
Currently Running:
|
|
|
|
* CoreDNS
|
|
* Metrics Server
|
|
* Local Path Provisioner
|
|
* Traefik Ingress Controller
|
|
|
|
Future Components:
|
|
|
|
* FluxCD
|
|
* Longhorn
|
|
* Cert-Manager
|
|
* Cloudflare Tunnel
|
|
* Authentik
|
|
* Prometheus Operator
|
|
|
|
---
|
|
|
|
# GitOps
|
|
|
|
## Git Platform
|
|
|
|
```text
|
|
Forgejo
|
|
```
|
|
|
|
Repository:
|
|
|
|
```text
|
|
https://gitforge.kitestacks.com/kenpat/kitestacks-homelab.git
|
|
```
|
|
|
|
Visibility:
|
|
|
|
```text
|
|
Private
|
|
```
|
|
|
|
Purpose:
|
|
|
|
* Infrastructure as Code
|
|
* Kubernetes manifests
|
|
* Documentation
|
|
* Application deployment
|
|
* Disaster recovery
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```text
|
|
kitestacks-homelab
|
|
├── apps
|
|
├── clusters
|
|
│ └── assassin
|
|
├── docs
|
|
├── infrastructure
|
|
└── media
|
|
```
|
|
|
|
---
|
|
|
|
# Current Docker Applications
|
|
|
|
## Dashboard
|
|
|
|
* Homepage
|
|
|
|
## Library Services
|
|
|
|
* Kavita
|
|
|
|
## Knowledge Management
|
|
|
|
* Linkding
|
|
|
|
## Source Control
|
|
|
|
* Forgejo
|
|
|
|
## Monitoring
|
|
|
|
* Grafana
|
|
* Prometheus
|
|
|
|
---
|
|
|
|
# Planned Services
|
|
|
|
## Identity
|
|
|
|
* Authentik
|
|
|
|
## AI
|
|
|
|
* Open WebUI
|
|
* LiteLLM
|
|
|
|
## Productivity
|
|
|
|
* Plane
|
|
* OpenProject (evaluation)
|
|
|
|
## Media
|
|
|
|
* Audiobookshelf
|
|
|
|
---
|
|
|
|
# Kavita
|
|
|
|
## Library Location
|
|
|
|
```text
|
|
/home/kenpat/library/books
|
|
```
|
|
|
|
## Current Status
|
|
|
|
Running in Docker.
|
|
|
|
Future migration planned to Kubernetes.
|
|
|
|
---
|
|
|
|
# Cloudflare
|
|
|
|
## Domain
|
|
|
|
```text
|
|
kitestacks.com
|
|
```
|
|
|
|
Current usage:
|
|
|
|
* Reverse proxy
|
|
* Public application access
|
|
* DNS management
|
|
|
|
Future usage:
|
|
|
|
* Kubernetes ingress
|
|
* Cloudflare Tunnel
|
|
* Zero Trust
|
|
|
|
---
|
|
|
|
# Monitoring Strategy
|
|
|
|
Primary Monitoring:
|
|
|
|
* Grafana
|
|
|
|
Metrics Collection:
|
|
|
|
* Prometheus
|
|
|
|
Future Monitoring:
|
|
|
|
* Kubernetes cluster metrics
|
|
* Longhorn metrics
|
|
* Application metrics
|
|
* Node metrics
|
|
|
|
---
|
|
|
|
# Migration Roadmap
|
|
|
|
## Phase 1 (Completed)
|
|
|
|
* Docker Homelab
|
|
* Forgejo Deployment
|
|
* K3s Installation
|
|
* GitOps Repository Creation
|
|
|
|
## Phase 2 (Current)
|
|
|
|
* FluxCD Installation
|
|
* GitOps Bootstrap
|
|
* Longhorn Deployment
|
|
|
|
## Phase 3
|
|
|
|
* Homepage Migration
|
|
* Linkding Migration
|
|
|
|
## Phase 4
|
|
|
|
* Kavita Migration
|
|
* Forgejo Migration
|
|
|
|
## Phase 5
|
|
|
|
* Grafana Migration
|
|
* Prometheus Migration
|
|
|
|
## Phase 6
|
|
|
|
* Authentik Deployment
|
|
* Open WebUI Deployment
|
|
* LiteLLM Deployment
|
|
|
|
---
|
|
|
|
# Backup Strategy
|
|
|
|
Planned:
|
|
|
|
* Git repository backups
|
|
* Application volume backups
|
|
* Longhorn snapshots
|
|
* Off-site backups
|
|
|
|
---
|
|
|
|
# Version History
|
|
|
|
## Version 1.1
|
|
|
|
Initial Homelab Documentation
|
|
|
|
## Version 1.2
|
|
|
|
K3s Installation Milestone
|
|
|
|
## Version 1.3
|
|
|
|
Forgejo GitOps Repository Established
|
|
K3s Operational
|
|
Documentation Baseline Created
|
|
Ready for FluxCD Deployment
|
|
|
|
---
|
|
|
|
# Current Status
|
|
|
|
Homelab State:
|
|
|
|
```text
|
|
Operational
|
|
```
|
|
|
|
Kubernetes State:
|
|
|
|
```text
|
|
Ready
|
|
```
|
|
|
|
GitOps State:
|
|
|
|
```text
|
|
Repository Created
|
|
Awaiting FluxCD Integration
|
|
```
|
|
|
|
Next Milestone:
|
|
|
|
```text
|
|
FluxCD Installation and Forgejo Integration
|
|
```
|