turingpi/README.md

# TuringPi K3s Homelab

This repository contains Kubernetes configuration files for a K3s cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications in a homelab environment.

## 🏗️ Cluster Architecture

### Hardware Setup
- **turing1**: Control plane + worker (192.168.222.237) 
- **turing2**: Worker node
- **turing3**: Worker node (NFS server at turing3.lan)
- **turing4**: Worker node  
- **beelink**: Additional x86_64 worker node

### Infrastructure Stack
- **Kubernetes**: K3s lightweight distribution
- **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 certificates
- **Ingress**: Nginx with LAN-only access restrictions

## 🚀 Applications

### Media Services
- **Plex**: Via kube-plex (Kubernetes-native with dynamic transcoding)
- **Jellyfin**: Alternative media server
- **Sonarr/Radarr**: TV/Movie management 
- **Prowlarr**: Indexer management
- **Transmission**: BitTorrent client with OpenVPN
- **FlareSolverr**: Captcha solver service

### Other Applications  
- **Actual Budget**: Personal finance management
- **Home Assistant Voice LLMs**: AI voice integration
- **Ollama**: Local LLM inference
- **Prometheus**: Monitoring and metrics
- **PostgreSQL**: Database backend

## 📁 Repository Structure

```
├── applications/         # Argo CD Application manifests
├── resources/            # Plain Kubernetes resources (kubectl apply -f)
├── helm-values/          # Helm values for Argo-managed apps
├── non_argo_values/      # Helm values for apps managed directly with Helm
├── custom_helm_charts/   # Custom charts (actual, voice, prowlarr, lidarr)
└── cluster_setup/        # Cluster bootstrap + update scripts
```

## 🔧 Common Operations

### Application Deployment
```bash
# Deploy with Helm using values files
helm upgrade <release-name> <chart> -f <app>_values.yaml -i

# Examples:
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
```

### Infrastructure Management
```bash
# Apply Kubernetes manifests
kubectl apply -f metallb.yml
kubectl apply -f ingress.yaml

# Check cluster status
kubectl get nodes
kubectl get pods --all-namespaces
```

## 🔄 K3s Cluster Updates

### Automated Update
Run the provided script to update all nodes:
```bash
./update.sh
```


Old way: 
```bash
master: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false sh -s - --write-kubeconfig-mode 644 --disable servicelb --token torino --node-ip 192.168.222.237 --disable-cloud-controller --disable local-storage

nodes: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false K3S_URL=https://192.168.222.237:6443 K3S_TOKEN=torino sh -

````

### Manual Update Process

#### 1. Update Master Node (turing1)
```bash
ssh root@turing1  # password: turing
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false sh -s - \
  --write-kubeconfig-mode 644 \
  --disable servicelb \
  --token torino \
  --node-ip 192.168.222.237 \
  --disable-cloud-controller \
  --disable local-storage
```

#### 2. Update Worker Nodes (turing2, turing3, turing4)
```bash
ssh root@<node>  # password: turing
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false \
  K3S_URL=https://192.168.222.237:6443 \
  K3S_TOKEN=torino sh -
```

#### 3. Update Beelink Node
```bash
ssh gilgamezh@beelink.lan  # no password (SSH keys)
sudo curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false \
  K3S_URL=https://192.168.222.237:6443 \
  K3S_TOKEN=torino sh -
```

#### 4. Verify Update
```bash
kubectl get nodes  # Check all nodes show new version
kubectl get pods --all-namespaces | grep -v Running  # Check for issues
```

## 🔑 Access Information

- **Cluster Token**: `torino`
- **Master Node**: `192.168.222.237:6443`
- **SSH Access**: 
  - TuringPi nodes: `root@<hostname>` (password: `turing`)
  - Beelink: `gilgamezh@beelink.lan` (SSH keys)

## 📚 Additional Documentation

- See `CLAUDE.md` for detailed Claude Code integration guide
- Custom Helm charts include their own README files
- Check application-specific `*_values.yaml` files for configuration options

## 🛠️ Development

### Helm Chart Development
```bash
helm create <chart-name>
helm lint <chart-path>
helm template <chart> -f <values> | kubectl apply --dry-run=client -f -
```

### Storage Requirements
- NFS server must be running on turing3.lan
- Applications require ReadWriteMany access for shared media
- Persistent volumes are dynamically provisioned via nfs-subdir-external-provisioner