turingpi/CLAUDE.md

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

# 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

# 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

# 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