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

cd kubernetes
./deploy.sh

The script handles everything automatically!

Manual Deployment

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:

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

# 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

kubectl top pods -l app=socktop-webterm

View Pod Distribution

kubectl get pods -l app=socktop-webterm -o wide

Check Events

kubectl get events --sort-by='.lastTimestamp' | grep socktop

Test Pi Connectivity

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

kubectl logs -l app=socktop-webterm --tail=100

Describe Resources

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

kubectl scale deployment socktop-webterm --replicas=5

Resource Adjustment

Edit 03-deployment.yaml resources section, then:

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! 🎉