socktop-webterm/kubernetes/DEPLOYMENT-STEPS.md

Next Steps - Ready to Run After Registry Setup

Step 1: Verify All Nodes Have the Image

Once all nodes finish pulling, verify:

# Check each node has the image cached
ssh pi@192.168.1.101 'sudo k3s crictl images | grep socktop'
ssh pi@192.168.1.102 'sudo k3s crictl images | grep socktop'
ssh pi@192.168.1.104 'sudo k3s crictl images | grep socktop'

# Should show:
# 192.168.1.208:3002/jason/socktop-webterm  0.2.0  <image-id>  <size>  <time>

Step 2: Setup kubectl (if not done yet)

cd kubernetes
./setup-kubectl.sh
# Enter: 192.168.1.101 (your k3s server IP)
# Choose: Option 2 (save as separate file)

# Export for current session
export KUBECONFIG=~/.kube/config-k3s

# Test connection
kubectl get nodes

Expected output:

NAME            STATUS   ROLES                  AGE   VERSION
rpi-master      Ready    control-plane,master   30d   v1.28.x+k3s1
rpi-worker-1    Ready    <none>                 30d   v1.28.x+k3s1
rpi-worker-2    Ready    <none>                 30d   v1.28.x+k3s1
rpi-worker-3    Ready    <none>                 30d   v1.28.x+k3s1

Step 3: Deploy to k3s

./deploy.sh

Script will ask:

• Namespace: Press Enter for default or type custom name
• TLS certificates: Skip if you don't have Pi certificates yet

Expected output:

=== Socktop WebTerm - Kubernetes Deployment Script ===

✓ Connected to Kubernetes cluster
Current context: default

Enter namespace to deploy to (default: default): 
Target namespace: default

Applying ConfigMap...
✓ ConfigMap applied

Applying Secret...
✓ Secret applied

Applying Deployment...
✓ Deployment applied

Applying Service...
✓ Service applied

Applying Ingress...
✓ Ingress applied

=== Deployment Complete! ===

Waiting for pods to be ready...
(This may take a minute while images are pulled)

✓ All pods are ready!

Pods:
NAME                              READY   STATUS    RESTARTS   AGE
socktop-webterm-xxxxxxxxxx-xxxxx  1/1     Running   0          30s
socktop-webterm-xxxxxxxxxx-xxxxx  1/1     Running   0          30s
socktop-webterm-xxxxxxxxxx-xxxxx  1/1     Running   0          30s

Step 4: Verify Deployment

# Check pods are running
kubectl get pods -l app=socktop-webterm -o wide

# Check which nodes they're on
kubectl get pods -l app=socktop-webterm -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,STATUS:.status.phase

# Check service
kubectl get svc socktop-webterm

# Check ingress
kubectl get ingress socktop-webterm

# View logs
kubectl logs -l app=socktop-webterm --tail=20

Step 5: Test Internal Access

From any k3s node:

# Test HTTP access
curl -I http://localhost:8080 -H "Host: socktop.io"

# Should return HTTP 200 OK

Step 6: Configure NGINX Proxy Manager

See NGINX-PROXY-MANAGER.md for full details.

Quick setup:

1. Log into NGINX Proxy Manager (http://your-proxy-manager:81)

2. Add Proxy Host → socktop.io

   • Domain Names: socktop.io
   • Scheme: http
   • Forward Hostname/IP: 192.168.1.101 (any k3s node)
   • Forward Port: 8080
   • ✅ Websockets Support: ON
   • Block Common Exploits: ON

   SSL Tab:

   • SSL Certificate: Select/create Let's Encrypt cert
   • Force SSL: ON
   • HTTP/2 Support: ON

   Advanced Tab:

   proxy_read_timeout 3600s;
   proxy_send_timeout 3600s;
   proxy_connect_timeout 60s;
   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";
   proxy_set_header Host $host;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_buffering off;
   

3. Repeat for www.socktop.io and origin.socktop.io

Step 7: Test External Access

# Test from external network or your local machine
curl -I https://socktop.io

# Should return HTTP 200 OK with SSL

Open browser:

• https://socktop.io
• Should see the webterm interface
• Check browser console (F12) → Network tab
• Look for WebSocket connection with status "101 Switching Protocols"

Step 8: Test Terminal Functionality

In the browser:

1. Select "local" profile (containerized agent on port 3001)
2. Terminal should connect and show prompt
3. Try running commands: ls, pwd, uname -a
4. Test with Pi profiles if you have TLS certs configured

Troubleshooting Quick Reference

Pods not starting

kubectl describe pods -l app=socktop-webterm
kubectl logs -l app=socktop-webterm --tail=50

ImagePullBackOff

# Check if image is on the node
kubectl get pods -l app=socktop-webterm -o wide
# Note which node
ssh pi@<node-ip> 'sudo k3s crictl images | grep socktop'

502 Bad Gateway

# Check pods are running
kubectl get pods -l app=socktop-webterm

# Check service endpoints
kubectl get endpoints socktop-webterm

# Test from k3s node
ssh pi@192.168.1.101 'curl http://localhost:8080 -H "Host: socktop.io"'

WebSocket not connecting

• Check NGINX Proxy Manager has WebSocket Support enabled
• Check Advanced config includes upgrade headers
• Check browser console for specific errors

Useful Commands

# Watch pod status
kubectl get pods -l app=socktop-webterm -w

# Stream logs from all pods
kubectl logs -l app=socktop-webterm -f

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

# Scale down
kubectl scale deployment socktop-webterm --replicas=2

# Restart deployment (e.g., after config change)
kubectl rollout restart deployment socktop-webterm

# View rollout status
kubectl rollout status deployment socktop-webterm

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

# Delete deployment
kubectl delete -f .

Performance Testing

Once running:

# Check resource usage
kubectl top pods -l app=socktop-webterm

# Check pod distribution across nodes
kubectl get pods -l app=socktop-webterm -o wide

# Watch metrics
watch -n 2 'kubectl top pods -l app=socktop-webterm'

Success Indicators

✅ 3 pods in Running state ✅ Service has 3 endpoints ✅ Ingress created successfully ✅ Can curl http://localhost:8080 from k3s node ✅ NGINX Proxy Manager forwards traffic ✅ Can access https://socktop.io in browser ✅ WebSocket connects (check browser console) ✅ Terminal sessions work ✅ Can switch between profiles

Next Steps After Deployment

1. Monitor performance under load
2. Test failover (kill a pod, see if traffic continues)
3. Test session affinity (refresh page, stay on same pod)
4. Configure monitoring/alerting (optional)
5. Set up backup strategy for configs (optional)
6. Document your NGINX Proxy Manager config

All Done! 🎉

Your Socktop WebTerm should now be:

• Running on 3 pods
• Distributed across k3s nodes
• Accessible via https://socktop.io
• Load balanced by Traefik
• SSL terminated at NGINX Proxy Manager
• Ready for production use!