socktop-webterm/kubernetes/INDEX.md

# Socktop WebTerm - Kubernetes Deployment Guide

Complete Kubernetes deployment manifests and tools for running Socktop WebTerm on your k3s cluster.

## 📁 Files Overview

### Core Manifests (Deploy in Order)
1. **`01-configmap.yaml`** - Configuration files (profiles.json, alacritty.toml, theme)
2. **`02-secret.yaml`** - TLS certificates for Raspberry Pi nodes (placeholder)
3. **`03-deployment.yaml`** - Main deployment with 3 replicas, host networking
4. **`04-service.yaml`** - Service with session affinity for terminal connections
5. **`05-ingress.yaml`** - Ingress with TLS, WebSocket support, and multiple domains

### Deployment Tools
- **`deploy.sh`** - Automated deployment script (recommended)
- **`kustomization.yaml`** - Kustomize configuration for advanced deployments

### Documentation
- **`INDEX.md`** - This file - overview and quick navigation
- **`QUICKSTART.md`** - Get running in 5 minutes
- **`README.md`** - Comprehensive deployment guide
- **`CHECKLIST.md`** - Pre-deployment checklist

## 🚀 Quick Start

### Fastest Way to Deploy

```bash
cd kubernetes
./deploy.sh
```

The script handles everything automatically!

### Manual Deployment

```bash
kubectl apply -f 01-configmap.yaml
kubectl apply -f 02-secret.yaml
kubectl apply -f 03-deployment.yaml
kubectl apply -f 04-service.yaml
kubectl apply -f 05-ingress.yaml
```

Or all at once:
```bash
kubectl apply -f .
```

## 📋 Prerequisites

Before deploying, ensure you have:

- ✅ k3s cluster running (3+ nodes recommended)
- ✅ kubectl configured
- ✅ Traefik Ingress Controller (default with k3s)
- ✅ External NGINX Proxy Manager for SSL termination
- ✅ DNS records pointing to external IP (socktop.io, www.socktop.io, origin.socktop.io)
- ✅ Insecure registry configured for `192.168.1.208:3002`
- ✅ Proxy hosts configured in NGINX Proxy Manager to forward to k3s on port 8080

**See `CHECKLIST.md` for complete pre-deployment verification.**

## 🔧 Configuration Overview

### Deployment Specs
- **Replicas**: 3 (adjust in `03-deployment.yaml`)
- **Image**: `192.168.1.208:3002/jason/socktop-webterm:0.2.0`
- **Networking**: Host network mode (for accessing Pi nodes on port 8443)
- **Resources**: 500m-2000m CPU, 256Mi-1Gi RAM per pod
- **Health Checks**: HTTP liveness and readiness probes

### Exposed Services
- **Port 8082**: WebTerm HTTP interface
- **Port 3001**: Containerized socktop-agent

### Ingress Configuration
- **Ingress Controller**: Traefik (default with k3s)
- **Domains**: socktop.io, www.socktop.io, origin.socktop.io
- **TLS**: Terminated at external NGINX Proxy Manager (not in cluster)
- **WebSocket**: Supported by default in Traefik
- **Session Affinity**: Configured in Service (ClientIP)

### ConfigMap Contents
- `profiles.json` - Connection profiles for local and 4 Pi nodes
- `alacritty.toml` - Terminal emulator configuration
- `catppuccin-frappe.toml` - Color scheme

## 📚 Documentation Guide

### Start Here
1. **`CHECKLIST.md`** - Verify all prerequisites are met
2. **`QUICKSTART.md`** - Deploy in 5 minutes
3. **`README.md`** - Deep dive into configuration and troubleshooting

### Common Tasks

**First Time Deployment**
→ Read `CHECKLIST.md` then run `./deploy.sh`

**Quick Deploy**
→ See `QUICKSTART.md`

**Troubleshooting**
→ See `QUICKSTART.md` (common issues) or `README.md` (comprehensive guide)

**Update Configuration**
→ Edit ConfigMap: `kubectl edit configmap socktop-webterm-config`
→ Restart: `kubectl rollout restart deployment socktop-webterm`

**Update Image Version**
→ `kubectl set image deployment/socktop-webterm webterm=192.168.1.208:3002/jason/socktop-webterm:NEW_VERSION`

**Scale Replicas**
→ `kubectl scale deployment socktop-webterm --replicas=5`

## 🛠️ Common Commands

```bash
# Check deployment status
kubectl get pods -l app=socktop-webterm

# View logs
kubectl logs -l app=socktop-webterm -f

# Check ingress
kubectl get ingress socktop-webterm

# Check certificate status
kubectl get certificate socktop-webterm-tls

# Describe deployment
kubectl describe deployment socktop-webterm

# Scale up
kubectl scale deployment socktop-webterm --replicas=5

# Update image
kubectl set image deployment/socktop-webterm webterm=192.168.1.208:3002/jason/socktop-webterm:0.3.0

# Restart deployment
kubectl rollout restart deployment socktop-webterm

# Delete everything
kubectl delete -f .
```

## 🌐 Access URLs

After deployment and configuring NGINX Proxy Manager, access your terminal at:
- https://socktop.io (SSL terminated at NGINX Proxy Manager)
- https://www.socktop.io
- https://origin.socktop.io

Traffic flow: **Internet → NGINX Proxy Manager (port 8080) → k3s Traefik (HTTP) → Service → Pods**

## ⚙️ Architecture Highlights

### Host Networking
- Uses `hostNetwork: true` to directly access Pi nodes on port 8443
- Each pod binds to host network interface
- Containerized agent runs on port 3001 (not 3000) to avoid conflicts

### High Availability
- 3 replicas for redundancy
- k3s spreads pods across available nodes
- Session affinity keeps users on same pod
- If a pod fails, traffic routes to healthy pods

### WebSocket Support
- Ingress configured for WebSocket upgrades
- Long connection timeouts (3600s)
- Proper headers for terminal connections

### Security
- Non-root user inside container
- Read-only certificate mounts
- Security context with dropped capabilities
- TLS for external access
- Rate limiting enabled

## 🔍 Monitoring & Debugging

### Check Resource Usage
```bash
kubectl top pods -l app=socktop-webterm
```

### View Pod Distribution
```bash
kubectl get pods -l app=socktop-webterm -o wide
```

### Check Events
```bash
kubectl get events --sort-by='.lastTimestamp' | grep socktop
```

### Test Pi Connectivity
```bash
kubectl exec -it deployment/socktop-webterm -- curl -k https://192.168.1.101:8443/health
```

## 📦 What's Included

```
kubernetes/
├── 01-configmap.yaml        # Configuration files
├── 02-secret.yaml           # TLS certificates (placeholder)
├── 03-deployment.yaml       # Main deployment (3 replicas)
├── 04-service.yaml          # Service with session affinity
├── 05-ingress.yaml          # Ingress with TLS and WebSocket
├── deploy.sh                # Automated deployment script
├── kustomization.yaml       # Kustomize configuration
├── CHECKLIST.md             # Pre-deployment checklist
├── QUICKSTART.md            # 5-minute quick start
├── README.md                # Comprehensive guide
└── INDEX.md                 # This file
```

## 🚨 Important Notes

1. **Insecure Registry**: You MUST configure `/etc/rancher/k3s/registries.yaml` on all k3s nodes to allow pulling from `192.168.1.208:3002`

2. **DNS Configuration**: Ensure socktop.io domains point to your external NGINX Proxy Manager IP, not cluster IP

3. **External Proxy**: Configure NGINX Proxy Manager to forward traffic to k3s nodes on port 8080 with WebSocket support enabled

4. **SSL Termination**: SSL/TLS is handled by NGINX Proxy Manager, not in the k8s cluster

5. **TLS Certificates**: The `02-secret.yaml` is a placeholder for Pi node certificates. Use `deploy.sh` or manually create the secret

6. **Host Network**: Using `hostNetwork: true` reduces isolation but is required to reach Pi nodes

7. **Session Affinity**: Crucial for maintaining terminal connections - don't disable!

## 🆘 Need Help?

### Quick Fixes
See **`QUICKSTART.md`** for common issues and solutions

### Detailed Troubleshooting
See **`README.md`** for comprehensive troubleshooting guide

### Verify Prerequisites
Run through **`CHECKLIST.md`** to ensure everything is configured

### Check Logs
```bash
kubectl logs -l app=socktop-webterm --tail=100
```

### Describe Resources
```bash
kubectl describe deployment socktop-webterm
kubectl describe pods -l app=socktop-webterm
```

## 📈 Performance & Scaling

### Default Configuration
- 3 replicas
- 500m CPU request, 2000m limit per pod
- 256Mi RAM request, 1Gi limit per pod

### Scaling Up
```bash
kubectl scale deployment socktop-webterm --replicas=5
```

### Resource Adjustment
Edit `03-deployment.yaml` resources section, then:
```bash
kubectl apply -f 03-deployment.yaml
```

## 🔐 Security Considerations

- Run as non-root user inside container
- Drop unnecessary capabilities
- Use secrets for sensitive data (certificates)
- Enable TLS for external access
- Implement rate limiting
- Consider adding authentication layer (OAuth2 Proxy)
- Use network policies to restrict pod-to-pod traffic

## ✅ Success Indicators

Deployment is successful when:
- All 3 pods show `Running` status
- Service has endpoints: `kubectl get endpoints socktop-webterm`
- Ingress has an address: `kubectl get ingress socktop-webterm`
- Certificate shows `Ready=True`: `kubectl get certificate socktop-webterm-tls`
- Can access https://socktop.io in browser
- Terminal sessions work correctly

## 📝 Version Information

- **Application Version**: 0.2.0
- **Container Image**: 192.168.1.208:3002/jason/socktop-webterm:0.2.0
- **Kubernetes API Version**: apps/v1, networking.k8s.io/v1
- **Ingress Controller**: Traefik (default with k3s)
- **SSL Termination**: External NGINX Proxy Manager

---

**Ready to deploy?** Start with `CHECKLIST.md` → `./deploy.sh` → Profit! 🎉