Add comprehensive documentation and automated update script

- Add README.md: Complete repository overview, architecture, and usage guide - Add update.sh: Automated K3s cluster upgrade script for all nodes - Add CLAUDE.md: Claude Code integration documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-28 14:18:07 +02:00
parent 620d757f8b
commit ff3e6f723c
4 changed files with 439 additions and 0 deletions
@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This repository contains Kubernetes configuration files for a K3s homelab cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications.
+
+## Cluster Architecture
+
+### Hardware Setup
+- **turing1**: Control plane + worker (master node, IP: 192.168.222.237)
+- **turing2**: Worker node (currently SchedulingDisabled)  
+- **turing3**: Worker node (also serves as NFS server at turing3.lan)
+- **turing4**: Worker node
+- **beelink**: Additional worker node
+
+### Core Infrastructure
+- **K3s version**: v1.31.6+k3s1
+- **Storage**: NFS-backed persistent volumes from turing3.lan:/mnt/ssd
+- **Load Balancer**: MetalLB for bare metal LoadBalancer services
+- **SSL**: cert-manager with Let's Encrypt (staging/production cluster issuers)
+- **Ingress**: Nginx with LAN-only restrictions
+
+## Application Stack
+
+### Media Services
+- **Plex**: kube-plex (Kubernetes-native with dynamic transcoding pods)
+- **Jellyfin**: Alternative media server
+- **Sonarr/Radarr**: TV/Movie management (Bananaspliff charts)
+- **Prowlarr**: Indexer management (custom chart)
+- **Transmission**: BitTorrent client with OpenVPN
+- **FlareSolverr**: Captcha solver service
+
+### Other Applications
+- **Actual Budget**: Personal finance (custom chart: my-actual-server/)
+- **Home Assistant Voice LLMs**: AI voice integration (custom chart)
+- **Ollama**: Local LLM inference
+- **Prometheus**: Monitoring stack
+- **PostgreSQL**: Database backend
+
+## Common Helm Operations
+
+### Repository Management
+```bash
+# Key repositories used
+helm repo add metallb https://metallb.github.io/metallb
+helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
+helm repo add jetstack https://charts.jetstack.io
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm repo add bananaspliff https://bananaspliff.github.io/geek-charts
+helm repo add k8s-at-home https://k8s-at-home.com/charts/
+helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
+helm repo add ollama-helm https://otwld.github.io/ollama-helm/
+helm repo update
+```
+
+### Application Deployment Pattern
+```bash
+# Standard deployment with values file
+helm upgrade <release-name> <chart> -f <app>_values.yaml -i
+
+# Examples from history:
+helm upgrade actual my-actual-server -f actual_values.yaml -i  
+helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml
+helm upgrade radarr bananaspliff/radarr -f radarr_values.yaml
+helm upgrade sonarr bananaspliff/sonarr -f sonarr_values.yaml
+helm upgrade prowlarr prowlarr -f prowlarr_values.yml
+```
+
+### Development Workflow
+```bash
+# Chart development
+helm create <chart-name>
+helm lint <chart-path>
+helm template <chart> -f <values> | vim -
+
+# Values inspection
+helm show values <chart> > <app>_values.yaml
+helm get values <release-name>
+helm get manifest <release-name>
+```
+
+## File Structure Patterns
+
+- `<app>_values.yaml` - Helm values overrides for each application
+- Custom charts in subdirectories (my-actual-server/, home-assistant-voice-llms/, prowlarr/)
+- `*_persistent_volume.yml` - PV definitions for applications requiring storage
+- Infrastructure manifests: metallb.yml, ingress.yaml, cluster-issuer-*.yaml
+
+## Storage Configuration
+
+- **NFS Server**: turing3.lan serving /mnt/ssd
+- **StorageClass**: nfs-client (via nfs-subdir-external-provisioner)
+- **Access Mode**: ReadWriteMany for shared media access
+- **PVC Pattern**: Applications create their own PVCs or reference pre-existing ones
+
+## Network Setup
+
+- **Pod Network**: Cluster subnet requires allowlisting in Plex for transcoding
+- **Ingress**: LAN-only access enforced via limit_ingress_to_lan.yaml
+- **Load Balancer**: MetalLB provides external IPs for services
+- **DNS**: .lan domain for internal services
+
+## Kube-Plex Specifics
+
+The kube-plex/ directory contains a Go application that replaces the standard Plex transcoder:
+- Creates Kubernetes pods for each transcode job
+- Requires AMD64 nodes (configured via nodeSelector)
+- Mounts shared NFS volumes for media access
+- Environment variables: DATA_PVC, CONFIG_PVC, TRANSCODE_PVC, PMS_IMAGE, PMS_INTERNAL_ADDRESS