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:

```bash
# 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)

```bash
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

```bash
./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

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

```bash
# 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:**
   ```nginx
   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

```bash
# 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
```bash
kubectl describe pods -l app=socktop-webterm
kubectl logs -l app=socktop-webterm --tail=50
```

### ImagePullBackOff
```bash
# 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
```bash
# 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

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

```bash
# 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!