- generally file cleanup and organize. - remove incorrect prompt text.
This commit is contained in:
@@ -1,216 +0,0 @@
|
||||
# Pre-Deployment Checklist for Socktop WebTerm on k3s
|
||||
|
||||
Use this checklist to ensure your k3s cluster is properly configured before deploying Socktop WebTerm.
|
||||
|
||||
## Infrastructure Requirements
|
||||
|
||||
### k3s Cluster
|
||||
- [ ] k3s cluster is installed and running
|
||||
- [ ] At least 3 nodes available (for spreading 3 replicas)
|
||||
- [ ] `kubectl` is installed and configured
|
||||
- [ ] Can run `kubectl get nodes` successfully
|
||||
- [ ] Traefik ingress controller is running (default with k3s)
|
||||
- [ ] Nodes have sufficient resources:
|
||||
- [ ] 1.5+ CPU cores available per node
|
||||
- [ ] 768+ MB RAM available per node
|
||||
|
||||
### Network Access
|
||||
- [ ] k3s nodes can reach Raspberry Pi nodes on port 8443
|
||||
- [ ] 192.168.1.101:8443 (rpi-master)
|
||||
- [ ] 192.168.1.102:8443 (rpi-worker-1)
|
||||
- [ ] 192.168.1.103:8443 (rpi-worker-2)
|
||||
- [ ] 192.168.1.104:8443 (rpi-worker-3)
|
||||
- [ ] Test with: `curl -k https://192.168.1.101:8443/health`
|
||||
|
||||
### DNS Configuration
|
||||
- [ ] DNS records point to your external NGINX Proxy Manager IP:
|
||||
- [ ] socktop.io → external IP
|
||||
- [ ] www.socktop.io → external IP
|
||||
- [ ] origin.socktop.io → external IP
|
||||
- [ ] DNS propagation is complete (test with `nslookup socktop.io`)
|
||||
|
||||
## Required k3s Components
|
||||
|
||||
### Traefik Ingress Controller
|
||||
- [ ] Traefik is running (comes default with k3s)
|
||||
- [ ] Check with: `kubectl get pods -n kube-system | grep traefik`
|
||||
- [ ] Traefik is accessible on port 80 (HTTP)
|
||||
|
||||
### External NGINX Proxy Manager
|
||||
- [ ] External NGINX Proxy Manager is configured
|
||||
- [ ] SSL certificates are set up in Proxy Manager
|
||||
- [ ] Proxy hosts configured for:
|
||||
- [ ] socktop.io → k3s-node-ip:8080
|
||||
- [ ] www.socktop.io → k3s-node-ip:8080
|
||||
- [ ] origin.socktop.io → k3s-node-ip:8080
|
||||
- [ ] WebSocket support enabled in proxy hosts
|
||||
- [ ] SSL termination happens at NGINX Proxy Manager
|
||||
|
||||
## Docker Registry Access
|
||||
|
||||
### Gitea Registry Configuration
|
||||
- [ ] Gitea registry is accessible at 192.168.1.208:3002
|
||||
- [ ] Test with: `curl http://192.168.1.208:3002/v2/`
|
||||
- [ ] Image exists: `192.168.1.208:3002/jason/socktop-webterm:0.2.0`
|
||||
|
||||
### Insecure Registry Configuration (REQUIRED)
|
||||
Since Gitea uses HTTP, you MUST configure k3s to allow insecure registries.
|
||||
|
||||
**On EACH k3s node** (both server and agents):
|
||||
|
||||
- [ ] Created `/etc/rancher/k3s/registries.yaml` with:
|
||||
```yaml
|
||||
mirrors:
|
||||
"192.168.1.208:3002":
|
||||
endpoint:
|
||||
- "http://192.168.1.208:3002"
|
||||
configs:
|
||||
"192.168.1.208:3002":
|
||||
tls:
|
||||
insecure_skip_verify: true
|
||||
```
|
||||
- [ ] Restarted k3s services:
|
||||
- [ ] Server: `sudo systemctl restart k3s`
|
||||
- [ ] Agents: `sudo systemctl restart k3s-agent`
|
||||
- [ ] Test image pull: `docker pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0`
|
||||
|
||||
## TLS Certificates (Optional but Recommended)
|
||||
|
||||
### Raspberry Pi TLS Certificates
|
||||
If you want to connect to Pi nodes via TLS:
|
||||
|
||||
- [ ] Have TLS CA certificates for each Pi node:
|
||||
- [ ] rpi-master.pem
|
||||
- [ ] rpi-worker-1.pem
|
||||
- [ ] rpi-worker-2.pem
|
||||
- [ ] rpi-worker-3.pem
|
||||
- [ ] Certificate files are accessible on your local machine
|
||||
- [ ] Know the full path to each certificate file
|
||||
|
||||
**Note:** If you don't have these yet, the deployment will still work, but you won't be able to connect to Pi nodes via TLS WebSocket.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### profiles.json
|
||||
- [ ] Reviewed `kubernetes/01-configmap.yaml`
|
||||
- [ ] Updated Raspberry Pi IP addresses if different
|
||||
- [ ] Updated port numbers if different
|
||||
- [ ] Updated certificate paths if different
|
||||
|
||||
### alacritty.toml
|
||||
- [ ] Reviewed terminal configuration in `kubernetes/01-configmap.yaml`
|
||||
- [ ] Adjusted font size/family if desired
|
||||
- [ ] Adjusted transparency/blur settings if desired
|
||||
|
||||
## Deployment Files Ready
|
||||
|
||||
- [ ] All manifest files are present:
|
||||
- [ ] `01-configmap.yaml`
|
||||
- [ ] `02-secret.yaml`
|
||||
- [ ] `03-deployment.yaml`
|
||||
- [ ] `04-service.yaml`
|
||||
- [ ] `05-ingress.yaml`
|
||||
- [ ] `deploy.sh` script is executable: `chmod +x deploy.sh`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- [ ] Understand that `hostNetwork: true` reduces pod isolation
|
||||
- [ ] Cluster network is trusted (not exposed to public internet directly)
|
||||
- [ ] TLS certificates will be stored as Kubernetes secrets
|
||||
- [ ] Consider implementing authentication (OAuth2 Proxy, etc.)
|
||||
- [ ] Rate limiting is configured in ingress (100 rps by default)
|
||||
|
||||
## Resource Planning
|
||||
|
||||
With 3 replicas, total resource requirements:
|
||||
- **CPU**: 1.5 cores requested, 6 cores limit
|
||||
- **Memory**: 768 MB requested, 3 GB limit
|
||||
|
||||
- [ ] Your cluster has sufficient resources
|
||||
- [ ] Check with: `kubectl describe nodes`
|
||||
|
||||
## Backup Plan
|
||||
|
||||
- [ ] Know how to view logs: `kubectl logs -l app=socktop-webterm`
|
||||
- [ ] Know how to delete deployment: `kubectl delete -f kubernetes/`
|
||||
- [ ] Have access to Docker logs on k3s nodes if needed
|
||||
|
||||
## Pre-Deployment Test Commands
|
||||
|
||||
Run these commands to verify everything is ready:
|
||||
|
||||
```bash
|
||||
# Check cluster access
|
||||
kubectl cluster-info
|
||||
|
||||
# Check nodes
|
||||
kubectl get nodes
|
||||
|
||||
# Check Traefik ingress controller
|
||||
kubectl get pods -n kube-system | grep traefik
|
||||
|
||||
# Check Traefik service
|
||||
kubectl get svc -n kube-system traefik
|
||||
|
||||
# Test registry access from a node
|
||||
ssh <your-k3s-node>
|
||||
docker pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0
|
||||
|
||||
# Test network access to Pi nodes
|
||||
curl -k https://192.168.1.101:8443/health
|
||||
```
|
||||
|
||||
## Ready to Deploy?
|
||||
|
||||
If all items above are checked ✓, you're ready to deploy!
|
||||
|
||||
### Choose your deployment method:
|
||||
|
||||
**Option 1: Automated (Recommended)**
|
||||
```bash
|
||||
cd kubernetes
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
**Option 2: Manual**
|
||||
```bash
|
||||
cd kubernetes
|
||||
kubectl apply -f .
|
||||
```
|
||||
|
||||
**Option 3: Kustomize**
|
||||
```bash
|
||||
cd kubernetes
|
||||
kubectl apply -k .
|
||||
```
|
||||
|
||||
## Post-Deployment Verification
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
```bash
|
||||
# Check pods are running
|
||||
kubectl get pods -l app=socktop-webterm
|
||||
|
||||
# Check service is created
|
||||
kubectl get svc socktop-webterm
|
||||
|
||||
# Check ingress is configured
|
||||
kubectl get ingress socktop-webterm
|
||||
|
||||
# View logs
|
||||
kubectl logs -l app=socktop-webterm -f
|
||||
```
|
||||
|
||||
Configure your external NGINX Proxy Manager to forward traffic, then access:
|
||||
- https://socktop.io (SSL terminated at NGINX Proxy Manager)
|
||||
- https://www.socktop.io
|
||||
- https://origin.socktop.io
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If something goes wrong, see:
|
||||
- `QUICKSTART.md` - Common issues and quick fixes
|
||||
- `README.md` - Detailed troubleshooting guide
|
||||
- Pod logs: `kubectl logs -l app=socktop-webterm`
|
||||
- Pod events: `kubectl describe pods -l app=socktop-webterm`
|
||||
@@ -1,287 +0,0 @@
|
||||
# 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!
|
||||
@@ -1,307 +0,0 @@
|
||||
# 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! 🎉
|
||||
@@ -1,215 +0,0 @@
|
||||
# Setting Up kubectl for k3s
|
||||
|
||||
Since your kubectl config is empty, you need to configure it to connect to your k3s cluster.
|
||||
|
||||
## Quick Setup (Automated)
|
||||
|
||||
```bash
|
||||
cd kubernetes
|
||||
./setup-kubectl.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Ask for your k3s server IP
|
||||
2. Retrieve the kubeconfig from the server via SSH
|
||||
3. Modify it to use the correct server IP
|
||||
4. Save it to your local machine
|
||||
5. Test the connection
|
||||
|
||||
### Example Run:
|
||||
|
||||
```bash
|
||||
$ ./setup-kubectl.sh
|
||||
|
||||
Enter k3s server IP address: 192.168.1.101
|
||||
Enter SSH username for k3s server (default: ubuntu): ubuntu
|
||||
|
||||
Fetching kubeconfig from k3s server...
|
||||
✓ Retrieved kubeconfig from server
|
||||
|
||||
Choose how to save the kubeconfig:
|
||||
1) Replace ~/.kube/config
|
||||
2) Save as ~/.kube/config-k3s (separate file, safer)
|
||||
3) Merge with existing ~/.kube/config
|
||||
|
||||
Enter choice (1/2/3, default: 2): 2
|
||||
|
||||
✓ Saved to ~/.kube/config-k3s
|
||||
|
||||
To use this config, run:
|
||||
export KUBECONFIG=~/.kube/config-k3s
|
||||
```
|
||||
|
||||
## Manual Setup
|
||||
|
||||
If you prefer to do it manually:
|
||||
|
||||
### Step 1: Get kubeconfig from k3s server
|
||||
|
||||
```bash
|
||||
# SSH to your k3s server node
|
||||
ssh ubuntu@192.168.1.101 # use your server IP
|
||||
|
||||
# View the kubeconfig
|
||||
sudo cat /etc/rancher/k3s/k3s.yaml
|
||||
```
|
||||
|
||||
### Step 2: Copy to your local machine
|
||||
|
||||
```bash
|
||||
# On your local machine
|
||||
mkdir -p ~/.kube
|
||||
|
||||
# Copy the config (replace 192.168.1.101 with your k3s server IP)
|
||||
scp ubuntu@192.168.1.101:/tmp/k3s-config.yaml ~/.kube/config-k3s
|
||||
|
||||
# Or manually copy the content
|
||||
nano ~/.kube/config-k3s
|
||||
# Paste the content from previous step
|
||||
```
|
||||
|
||||
### Step 3: Modify server IP
|
||||
|
||||
Edit the file and change the server IP from `127.0.0.1` to your actual k3s server IP:
|
||||
|
||||
```bash
|
||||
nano ~/.kube/config-k3s
|
||||
```
|
||||
|
||||
Change:
|
||||
```yaml
|
||||
server: https://127.0.0.1:6443
|
||||
```
|
||||
|
||||
To:
|
||||
```yaml
|
||||
server: https://192.168.1.101:6443 # use your actual IP
|
||||
```
|
||||
|
||||
### Step 4: Set KUBECONFIG
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=~/.kube/config-k3s
|
||||
```
|
||||
|
||||
Make it permanent by adding to your shell config:
|
||||
|
||||
**For bash (~/.bashrc):**
|
||||
```bash
|
||||
echo 'export KUBECONFIG=~/.kube/config-k3s' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
**For zsh (~/.zshrc):**
|
||||
```bash
|
||||
echo 'export KUBECONFIG=~/.kube/config-k3s' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
**For fish (~/.config/fish/config.fish):**
|
||||
```fish
|
||||
echo 'set -gx KUBECONFIG ~/.kube/config-k3s' >> ~/.config/fish/config.fish
|
||||
```
|
||||
|
||||
### Step 5: Test connection
|
||||
|
||||
```bash
|
||||
kubectl get nodes
|
||||
```
|
||||
|
||||
You should see your k3s nodes listed!
|
||||
|
||||
## Verify Setup
|
||||
|
||||
After configuration, verify everything works:
|
||||
|
||||
```bash
|
||||
# Check contexts
|
||||
kubectl config get-contexts
|
||||
|
||||
# Should show something like:
|
||||
# CURRENT NAME CLUSTER AUTHINFO NAMESPACE
|
||||
# * default default default
|
||||
|
||||
# Check nodes
|
||||
kubectl get nodes
|
||||
|
||||
# Should show your k3s nodes:
|
||||
# NAME STATUS ROLES AGE VERSION
|
||||
# rpi-master Ready control-plane,master 30d v1.28.2+k3s1
|
||||
# rpi-worker-1 Ready <none> 30d v1.28.2+k3s1
|
||||
# rpi-worker-2 Ready <none> 30d v1.28.2+k3s1
|
||||
|
||||
# Check cluster info
|
||||
kubectl cluster-info
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cannot connect to k3s server
|
||||
|
||||
**Error:** `Unable to connect to the server: dial tcp 192.168.1.101:6443: i/o timeout`
|
||||
|
||||
**Fix:**
|
||||
- Verify the IP address is correct
|
||||
- Check if port 6443 is accessible: `nc -zv 192.168.1.101 6443`
|
||||
- Check firewall rules on k3s server
|
||||
- Ensure k3s is running: `ssh ubuntu@192.168.1.101 'sudo systemctl status k3s'`
|
||||
|
||||
### Permission denied
|
||||
|
||||
**Error:** `error: You must be logged in to the server (Unauthorized)`
|
||||
|
||||
**Fix:**
|
||||
- The kubeconfig may not have been copied correctly
|
||||
- Re-run the setup script or manually copy the config again
|
||||
|
||||
### Wrong server IP
|
||||
|
||||
If you need to change the server IP:
|
||||
|
||||
```bash
|
||||
nano ~/.kube/config-k3s
|
||||
# Change the server: line to the correct IP
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once kubectl is configured:
|
||||
|
||||
```bash
|
||||
# 1. Configure registry on all k3s nodes
|
||||
./setup-registry.sh
|
||||
|
||||
# 2. Deploy Socktop WebTerm
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
## Complete Workflow Example
|
||||
|
||||
```bash
|
||||
# Setup kubectl
|
||||
cd kubernetes
|
||||
./setup-kubectl.sh
|
||||
# Enter: 192.168.1.101 (your k3s server IP)
|
||||
# Choose option 2 (save as separate file)
|
||||
|
||||
# Set environment variable for current session
|
||||
export KUBECONFIG=~/.kube/config-k3s
|
||||
|
||||
# Verify connection
|
||||
kubectl get nodes
|
||||
|
||||
# Configure registry
|
||||
./setup-registry.sh
|
||||
# Enter all node IPs
|
||||
|
||||
# Deploy
|
||||
./deploy.sh
|
||||
# Choose namespace: default
|
||||
|
||||
# Check status
|
||||
kubectl get pods -l app=socktop-webterm
|
||||
|
||||
# Done!
|
||||
```
|
||||
@@ -1,311 +0,0 @@
|
||||
# NGINX Proxy Manager Configuration for Socktop WebTerm
|
||||
|
||||
This guide explains how to configure your external NGINX Proxy Manager to route traffic to your k3s Socktop WebTerm deployment.
|
||||
|
||||
## Overview
|
||||
|
||||
Since your ISP restricts incoming ports, you're using an external NGINX Proxy Manager to:
|
||||
- Terminate SSL/TLS connections
|
||||
- Route traffic on port 8080 to your k3s cluster
|
||||
- Handle WebSocket upgrades for terminal connections
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Internet (HTTPS:443)
|
||||
↓
|
||||
External NGINX Proxy Manager
|
||||
↓ (SSL Termination)
|
||||
k3s Traefik Ingress (HTTP:8080)
|
||||
↓
|
||||
Socktop WebTerm Service
|
||||
↓
|
||||
Pods (3 replicas)
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [ ] NGINX Proxy Manager installed and accessible
|
||||
- [ ] SSL certificates ready (Let's Encrypt or custom)
|
||||
- [ ] k3s cluster deployed with Socktop WebTerm
|
||||
- [ ] Know your k3s node IP addresses
|
||||
- [ ] DNS records pointing to your external NGINX Proxy Manager
|
||||
|
||||
## Configuration Steps
|
||||
|
||||
### Step 1: Get Your k3s Node IP
|
||||
|
||||
Find the IP address of any k3s node (Traefik runs on all nodes with k3s):
|
||||
|
||||
```bash
|
||||
kubectl get nodes -o wide
|
||||
```
|
||||
|
||||
Note any node's INTERNAL-IP (e.g., `192.168.1.101`).
|
||||
|
||||
### Step 2: Verify Traefik is Running
|
||||
|
||||
```bash
|
||||
kubectl get svc -n kube-system traefik
|
||||
```
|
||||
|
||||
You should see Traefik listening on port 80.
|
||||
|
||||
### Step 3: Create Proxy Host for socktop.io
|
||||
|
||||
In NGINX Proxy Manager web UI:
|
||||
|
||||
1. **Go to**: Proxy Hosts → Add Proxy Host
|
||||
|
||||
2. **Details Tab**:
|
||||
- **Domain Names**: `socktop.io`
|
||||
- **Scheme**: `http` (NOT https - SSL terminates at proxy)
|
||||
- **Forward Hostname / IP**: `192.168.1.101` (your k3s node IP)
|
||||
- **Forward Port**: `8080`
|
||||
- **Cache Assets**: ☐ (unchecked)
|
||||
- **Block Common Exploits**: ☑ (checked)
|
||||
- **Websockets Support**: ☑ (IMPORTANT - check this!)
|
||||
- **Access List**: None (or your preference)
|
||||
|
||||
3. **SSL Tab**:
|
||||
- **SSL Certificate**: Select or create new Let's Encrypt certificate
|
||||
- **Force SSL**: ☑ (checked)
|
||||
- **HTTP/2 Support**: ☑ (checked)
|
||||
- **HSTS Enabled**: ☑ (optional but recommended)
|
||||
- **HSTS Subdomains**: ☐ (unless you want this)
|
||||
|
||||
4. **Advanced Tab** (optional but recommended):
|
||||
```nginx
|
||||
# Increase timeouts for long-running terminal connections
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
proxy_connect_timeout 60s;
|
||||
|
||||
# WebSocket upgrade headers (should be set automatically, but just in case)
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# Pass through real client IP
|
||||
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;
|
||||
```
|
||||
|
||||
5. Click **Save**
|
||||
|
||||
### Step 4: Create Proxy Host for www.socktop.io
|
||||
|
||||
Repeat Step 3 with:
|
||||
- **Domain Names**: `www.socktop.io`
|
||||
- All other settings identical
|
||||
|
||||
### Step 5: Create Proxy Host for origin.socktop.io
|
||||
|
||||
Repeat Step 3 with:
|
||||
- **Domain Names**: `origin.socktop.io`
|
||||
- All other settings identical
|
||||
|
||||
## Verify Configuration
|
||||
|
||||
### Test 1: Check HTTP Forward
|
||||
|
||||
From your local machine:
|
||||
|
||||
```bash
|
||||
curl http://<k3s-node-ip>:8080 -H "Host: socktop.io"
|
||||
```
|
||||
|
||||
Should return the webterm HTML page.
|
||||
|
||||
### Test 2: Check HTTPS via Proxy
|
||||
|
||||
```bash
|
||||
curl -I https://socktop.io
|
||||
```
|
||||
|
||||
Should return `200 OK` with SSL certificate.
|
||||
|
||||
### Test 3: Check WebSocket Support
|
||||
|
||||
In your browser's developer console (F12), check the Network tab when connecting to the terminal. You should see:
|
||||
- WebSocket connection established
|
||||
- Status: `101 Switching Protocols`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 502 Bad Gateway
|
||||
|
||||
**Cause**: NGINX Proxy Manager can't reach k3s
|
||||
|
||||
**Fix**:
|
||||
- Verify k3s node IP is correct
|
||||
- Check port 8080 is accessible: `curl http://<node-ip>:8080`
|
||||
- Ensure firewall allows traffic from proxy to k3s
|
||||
- Check Traefik is running: `kubectl get pods -n kube-system | grep traefik`
|
||||
|
||||
### SSL Certificate Error
|
||||
|
||||
**Cause**: SSL certificate not properly configured
|
||||
|
||||
**Fix**:
|
||||
- Verify DNS points to NGINX Proxy Manager IP
|
||||
- Wait for Let's Encrypt validation (can take a few minutes)
|
||||
- Check NGINX Proxy Manager logs for certificate errors
|
||||
|
||||
### WebSocket Connection Fails
|
||||
|
||||
**Cause**: WebSocket support not enabled or timeouts too short
|
||||
|
||||
**Fix**:
|
||||
- Enable "Websockets Support" checkbox in proxy host
|
||||
- Add custom nginx configuration with longer timeouts (see Step 3, Advanced tab)
|
||||
- Check browser console for specific WebSocket errors
|
||||
|
||||
### Terminal Disconnects After 60 Seconds
|
||||
|
||||
**Cause**: Default proxy timeouts are too short
|
||||
|
||||
**Fix**: Add to Advanced tab in proxy host:
|
||||
```nginx
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
```
|
||||
|
||||
### Can Access HTTP but not HTTPS
|
||||
|
||||
**Cause**: DNS records still point to old IP or wrong IP
|
||||
|
||||
**Fix**:
|
||||
- Verify DNS with: `nslookup socktop.io`
|
||||
- Should return your external NGINX Proxy Manager IP
|
||||
- Wait for DNS propagation (up to 24 hours, usually minutes)
|
||||
|
||||
## Load Balancing (Optional)
|
||||
|
||||
If you want to load balance across multiple k3s nodes:
|
||||
|
||||
### Option 1: Use Multiple Upstream Servers in Advanced Config
|
||||
|
||||
```nginx
|
||||
# Add to Advanced tab
|
||||
upstream k3s_backend {
|
||||
server 192.168.1.101:8080;
|
||||
server 192.168.1.102:8080;
|
||||
server 192.168.1.104:8080;
|
||||
}
|
||||
|
||||
# Then change proxy_pass to use upstream
|
||||
proxy_pass http://k3s_backend;
|
||||
```
|
||||
|
||||
### Option 2: Use k3s LoadBalancer Service
|
||||
|
||||
Change the Service type in `04-service.yaml` to `LoadBalancer` and use the assigned external IP.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Enable Force SSL**: Always redirect HTTP to HTTPS
|
||||
2. **Enable HSTS**: Tells browsers to always use HTTPS
|
||||
3. **Enable Block Common Exploits**: Provides basic protection
|
||||
4. **Add Access List**: Restrict by IP if possible
|
||||
5. **Use Strong SSL**: Enable HTTP/2, disable old TLS versions
|
||||
6. **Keep Timeouts Reasonable**: 3600s (1 hour) for terminal sessions
|
||||
|
||||
## Example Complete Advanced Configuration
|
||||
|
||||
For best results, use this in the Advanced tab:
|
||||
|
||||
```nginx
|
||||
# Timeouts for long-running connections
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
proxy_connect_timeout 60s;
|
||||
keepalive_timeout 3600s;
|
||||
|
||||
# WebSocket support
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# Pass through client information
|
||||
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_set_header X-Forwarded-Host $host;
|
||||
proxy_set_header X-Forwarded-Port $server_port;
|
||||
|
||||
# Buffering (disable for WebSockets)
|
||||
proxy_buffering off;
|
||||
|
||||
# Security headers
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
```
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
After configuration, verify:
|
||||
|
||||
- [ ] Can access https://socktop.io and see login/terminal page
|
||||
- [ ] Can access https://www.socktop.io (same result)
|
||||
- [ ] Can access https://origin.socktop.io (same result)
|
||||
- [ ] SSL certificate shows as valid (no browser warnings)
|
||||
- [ ] Terminal connections work and stay connected
|
||||
- [ ] WebSocket shows as connected in browser dev tools
|
||||
- [ ] Can switch between different profiles
|
||||
- [ ] Terminal sessions survive page refresh (with session affinity)
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check NGINX Proxy Manager Logs
|
||||
|
||||
In NGINX Proxy Manager UI:
|
||||
- Go to proxy host → Click on host → View logs
|
||||
|
||||
### Check k3s Side
|
||||
|
||||
```bash
|
||||
# Check ingress
|
||||
kubectl get ingress socktop-webterm
|
||||
|
||||
# Check service endpoints
|
||||
kubectl get endpoints socktop-webterm
|
||||
|
||||
# Check pod logs
|
||||
kubectl logs -l app=socktop-webterm -f
|
||||
```
|
||||
|
||||
## Common Traffic Flow Issues
|
||||
|
||||
| Symptom | Likely Cause | Check |
|
||||
|---------|--------------|-------|
|
||||
| 404 Not Found | Traefik routing issue | `kubectl describe ingress socktop-webterm` |
|
||||
| 502 Bad Gateway | Can't reach k3s | Firewall, k3s node IP, port 8080 |
|
||||
| 503 Service Unavailable | Pods not ready | `kubectl get pods -l app=socktop-webterm` |
|
||||
| SSL Error | Certificate issue | NGINX Proxy Manager SSL tab |
|
||||
| WebSocket fails | WS not enabled | Enable WebSocket support checkbox |
|
||||
|
||||
## Summary
|
||||
|
||||
Your complete setup should be:
|
||||
|
||||
1. **DNS**: socktop.io → Your external IP (NGINX Proxy Manager)
|
||||
2. **NGINX Proxy Manager**:
|
||||
- Listens on 443 (HTTPS)
|
||||
- Terminates SSL
|
||||
- Forwards to k3s-node:8080 (HTTP)
|
||||
- WebSocket support enabled
|
||||
3. **k3s Traefik**:
|
||||
- Receives HTTP on port 8080
|
||||
- Routes to socktop-webterm service
|
||||
4. **Service**:
|
||||
- Routes to healthy pods
|
||||
- Session affinity enabled
|
||||
5. **Pods**:
|
||||
- 3 replicas running webterm
|
||||
- Host network for Pi access
|
||||
|
||||
All working? You should now have a secure, load-balanced terminal interface! 🎉
|
||||
@@ -1,476 +0,0 @@
|
||||
# Socktop WebTerm - Complete Setup Guide
|
||||
|
||||
This guide covers the complete setup process for deploying Socktop WebTerm to your k3s cluster.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- ✅ k3s cluster running (3+ nodes recommended)
|
||||
- ✅ kubectl installed on your local machine
|
||||
- ✅ SSH access to all k3s nodes
|
||||
- ✅ Image published to Gitea registry: `192.168.1.208:3002/jason/socktop-webterm:0.2.0`
|
||||
- ✅ External NGINX Proxy Manager configured
|
||||
|
||||
## Step-by-Step Setup
|
||||
|
||||
### Step 0: Configure kubectl Context
|
||||
|
||||
Before deploying, make sure kubectl is configured to connect to your k3s cluster.
|
||||
|
||||
#### Option A: Using your k3s kubeconfig
|
||||
|
||||
From your k3s server node:
|
||||
|
||||
```bash
|
||||
# On k3s server node, get the kubeconfig
|
||||
sudo cat /etc/rancher/k3s/k3s.yaml
|
||||
```
|
||||
|
||||
Copy this content to your local machine:
|
||||
|
||||
```bash
|
||||
# On your local machine
|
||||
mkdir -p ~/.kube
|
||||
nano ~/.kube/config-k3s
|
||||
# Paste the content and modify the server IP from 127.0.0.1 to your k3s server IP
|
||||
```
|
||||
|
||||
Example modification:
|
||||
```yaml
|
||||
# Change this:
|
||||
server: https://127.0.0.1:6443
|
||||
|
||||
# To this (use your k3s server IP):
|
||||
server: https://192.168.1.101:6443
|
||||
```
|
||||
|
||||
#### Option B: Merge with existing kubeconfig
|
||||
|
||||
If you already have a kubectl config:
|
||||
|
||||
```bash
|
||||
# Backup existing config
|
||||
cp ~/.kube/config ~/.kube/config.backup
|
||||
|
||||
# Add k3s config as a new context
|
||||
export KUBECONFIG=~/.kube/config:~/.kube/config-k3s
|
||||
kubectl config view --flatten > ~/.kube/config-merged
|
||||
mv ~/.kube/config-merged ~/.kube/config
|
||||
```
|
||||
|
||||
#### Verify Connection
|
||||
|
||||
```bash
|
||||
# List available contexts
|
||||
kubectl config get-contexts
|
||||
|
||||
# Switch to k3s context (replace with your context name)
|
||||
kubectl config use-context default
|
||||
|
||||
# Test connection
|
||||
kubectl get nodes
|
||||
|
||||
# You should see your k3s nodes listed
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
rpi-master Ready control-plane,master 30d v1.28.2+k3s1
|
||||
rpi-worker-1 Ready <none> 30d v1.28.2+k3s1
|
||||
rpi-worker-2 Ready <none> 30d v1.28.2+k3s1
|
||||
```
|
||||
|
||||
### Step 1: Configure k3s Insecure Registry
|
||||
|
||||
Your Gitea registry uses HTTP (not HTTPS), so you need to configure k3s to allow "insecure" registries.
|
||||
|
||||
#### Automated Method (Recommended)
|
||||
|
||||
Use the provided script to configure all nodes:
|
||||
|
||||
```bash
|
||||
cd kubernetes
|
||||
./setup-registry.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Ask for your k3s node IP addresses
|
||||
2. Ask for SSH username (default: ubuntu)
|
||||
3. Copy the registry config to each node
|
||||
4. Restart k3s services
|
||||
5. Test image pulling
|
||||
|
||||
#### Manual Method
|
||||
|
||||
If the script doesn't work or you prefer manual setup:
|
||||
|
||||
**For each k3s node**, do the following:
|
||||
|
||||
1. **SSH to the node:**
|
||||
```bash
|
||||
ssh ubuntu@192.168.1.101 # replace with your node IP
|
||||
```
|
||||
|
||||
2. **Create the k3s config directory:**
|
||||
```bash
|
||||
sudo mkdir -p /etc/rancher/k3s
|
||||
```
|
||||
|
||||
3. **Create the registries.yaml file:**
|
||||
```bash
|
||||
sudo nano /etc/rancher/k3s/registries.yaml
|
||||
```
|
||||
|
||||
4. **Paste this content:**
|
||||
```yaml
|
||||
mirrors:
|
||||
"192.168.1.208:3002":
|
||||
endpoint:
|
||||
- "http://192.168.1.208:3002"
|
||||
|
||||
configs:
|
||||
"192.168.1.208:3002":
|
||||
tls:
|
||||
insecure_skip_verify: true
|
||||
```
|
||||
|
||||
5. **Save and exit** (Ctrl+O, Enter, Ctrl+X)
|
||||
|
||||
6. **Restart k3s:**
|
||||
```bash
|
||||
# On server nodes
|
||||
sudo systemctl restart k3s
|
||||
|
||||
# On agent/worker nodes
|
||||
sudo systemctl restart k3s-agent
|
||||
```
|
||||
|
||||
7. **Verify the service is running:**
|
||||
```bash
|
||||
sudo systemctl status k3s # on server
|
||||
sudo systemctl status k3s-agent # on agents
|
||||
```
|
||||
|
||||
8. **Test image pull:**
|
||||
```bash
|
||||
sudo k3s crictl pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0
|
||||
```
|
||||
|
||||
**Repeat for ALL k3s nodes** (both server and agents).
|
||||
|
||||
#### Troubleshooting Registry Setup
|
||||
|
||||
**Problem: systemctl restart fails**
|
||||
```bash
|
||||
# Check logs
|
||||
sudo journalctl -u k3s -n 50 # on server
|
||||
sudo journalctl -u k3s-agent -n 50 # on agents
|
||||
|
||||
# Look for syntax errors in registries.yaml
|
||||
sudo cat /etc/rancher/k3s/registries.yaml
|
||||
```
|
||||
|
||||
**Problem: Image pull fails**
|
||||
```bash
|
||||
# Test registry access from node
|
||||
curl http://192.168.1.208:3002/v2/
|
||||
|
||||
# Should return {} or a Docker registry response
|
||||
```
|
||||
|
||||
**Problem: Permission denied**
|
||||
```bash
|
||||
# Ensure correct permissions
|
||||
sudo chmod 644 /etc/rancher/k3s/registries.yaml
|
||||
sudo chown root:root /etc/rancher/k3s/registries.yaml
|
||||
```
|
||||
|
||||
### Step 2: Deploy to k3s
|
||||
|
||||
Once all nodes are configured, deploy the application:
|
||||
|
||||
#### Using the Automated Script
|
||||
|
||||
```bash
|
||||
cd kubernetes
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Check kubectl connection
|
||||
2. Show current context
|
||||
3. Ask for target namespace (default: `default`)
|
||||
4. Create namespace if needed
|
||||
5. Optionally configure Pi TLS certificates
|
||||
6. Deploy all manifests
|
||||
7. Wait for pods to be ready
|
||||
8. Show status and helpful commands
|
||||
|
||||
#### Manual Deployment
|
||||
|
||||
If you prefer to deploy manually:
|
||||
|
||||
```bash
|
||||
# Deploy to default namespace
|
||||
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 deploy to custom namespace
|
||||
kubectl create namespace socktop
|
||||
kubectl apply -f . -n socktop
|
||||
```
|
||||
|
||||
#### Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check pods
|
||||
kubectl get pods -l app=socktop-webterm -n default
|
||||
|
||||
# Expected output (3 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
|
||||
|
||||
# Check service
|
||||
kubectl get svc socktop-webterm -n default
|
||||
|
||||
# Check ingress
|
||||
kubectl get ingress socktop-webterm -n default
|
||||
```
|
||||
|
||||
#### Common Deployment Issues
|
||||
|
||||
**Pods stuck in ImagePullBackOff:**
|
||||
- Registry not configured on all nodes
|
||||
- Go back to Step 1 and verify each node
|
||||
|
||||
**Pods stuck in Pending:**
|
||||
- Not enough resources
|
||||
- Check: `kubectl describe pods -l app=socktop-webterm -n default`
|
||||
|
||||
**Pods in CrashLoopBackOff:**
|
||||
- Check logs: `kubectl logs -l app=socktop-webterm -n default --tail=100`
|
||||
|
||||
### Step 3: Configure External NGINX Proxy Manager
|
||||
|
||||
See `NGINX-PROXY-MANAGER.md` for detailed instructions.
|
||||
|
||||
Quick summary:
|
||||
|
||||
1. **Log into NGINX Proxy Manager web UI**
|
||||
|
||||
2. **Create proxy host for socktop.io:**
|
||||
- Domain: `socktop.io`
|
||||
- Scheme: `http`
|
||||
- Forward Hostname/IP: `192.168.1.101` (any k3s node IP)
|
||||
- Forward Port: `8080`
|
||||
- ✅ Enable WebSocket Support
|
||||
- SSL: Select/create certificate
|
||||
- ✅ Force SSL
|
||||
|
||||
3. **Repeat for www.socktop.io and origin.socktop.io**
|
||||
|
||||
4. **Advanced config (optional but recommended):**
|
||||
```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";
|
||||
```
|
||||
|
||||
### Step 4: Test Access
|
||||
|
||||
1. **Test internal access (from k3s node):**
|
||||
```bash
|
||||
curl http://localhost:8080 -H "Host: socktop.io"
|
||||
```
|
||||
|
||||
2. **Test external access:**
|
||||
- Open browser to https://socktop.io
|
||||
- Should see the webterm interface
|
||||
- Check browser console (F12) for WebSocket connection
|
||||
|
||||
3. **Test terminal functionality:**
|
||||
- Select a profile (local or a Pi node)
|
||||
- Terminal should connect and be interactive
|
||||
|
||||
## Complete Example Walkthrough
|
||||
|
||||
Here's a complete example from start to finish:
|
||||
|
||||
```bash
|
||||
# 1. Configure kubectl
|
||||
export KUBECONFIG=~/.kube/config
|
||||
kubectl config use-context default
|
||||
kubectl get nodes # verify connection
|
||||
|
||||
# 2. Navigate to kubernetes directory
|
||||
cd /path/to/webterm/kubernetes
|
||||
|
||||
# 3. Configure registry on all nodes
|
||||
./setup-registry.sh
|
||||
# Enter node IPs: 192.168.1.101, 192.168.1.102, 192.168.1.104
|
||||
# Enter SSH user: ubuntu
|
||||
|
||||
# 4. Wait for script to complete (will test image pull)
|
||||
|
||||
# 5. Deploy to k3s
|
||||
./deploy.sh
|
||||
# Choose namespace: default (or create new one)
|
||||
# Skip TLS cert config if you don't have Pi certs yet
|
||||
|
||||
# 6. Wait for deployment to complete
|
||||
|
||||
# 7. Verify pods are running
|
||||
kubectl get pods -l app=socktop-webterm -n default
|
||||
|
||||
# 8. Configure NGINX Proxy Manager (see NGINX-PROXY-MANAGER.md)
|
||||
|
||||
# 9. Test access
|
||||
curl -I https://socktop.io
|
||||
|
||||
# 10. Open browser and test
|
||||
# https://socktop.io
|
||||
```
|
||||
|
||||
## Kubernetes Context Quick Reference
|
||||
|
||||
### View Available Contexts
|
||||
```bash
|
||||
kubectl config get-contexts
|
||||
```
|
||||
|
||||
### Switch Context
|
||||
```bash
|
||||
kubectl config use-context <context-name>
|
||||
```
|
||||
|
||||
### View Current Context
|
||||
```bash
|
||||
kubectl config current-context
|
||||
```
|
||||
|
||||
### Set Default Namespace
|
||||
```bash
|
||||
kubectl config set-context --current --namespace=socktop
|
||||
```
|
||||
|
||||
### View Cluster Info
|
||||
```bash
|
||||
kubectl cluster-info
|
||||
```
|
||||
|
||||
## Node Configuration Quick Reference
|
||||
|
||||
### Check k3s Service Status
|
||||
```bash
|
||||
# On server node
|
||||
sudo systemctl status k3s
|
||||
|
||||
# On agent/worker node
|
||||
sudo systemctl status k3s-agent
|
||||
```
|
||||
|
||||
### View k3s Logs
|
||||
```bash
|
||||
sudo journalctl -u k3s -f # server
|
||||
sudo journalctl -u k3s-agent -f # agent
|
||||
```
|
||||
|
||||
### Verify Registry Config
|
||||
```bash
|
||||
sudo cat /etc/rancher/k3s/registries.yaml
|
||||
```
|
||||
|
||||
### Test Image Pull
|
||||
```bash
|
||||
sudo k3s crictl pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0
|
||||
```
|
||||
|
||||
### List Images on Node
|
||||
```bash
|
||||
sudo k3s crictl images | grep socktop
|
||||
```
|
||||
|
||||
## Helpful kubectl Commands
|
||||
|
||||
```bash
|
||||
# Get all resources in namespace
|
||||
kubectl get all -n default
|
||||
|
||||
# Describe deployment
|
||||
kubectl describe deployment socktop-webterm -n default
|
||||
|
||||
# View pod logs
|
||||
kubectl logs -l app=socktop-webterm -n default -f
|
||||
|
||||
# Execute command in pod
|
||||
kubectl exec -it deployment/socktop-webterm -n default -- /bin/bash
|
||||
|
||||
# Port forward for testing
|
||||
kubectl port-forward svc/socktop-webterm 8082:8082 -n default
|
||||
# Then access http://localhost:8082
|
||||
|
||||
# Scale deployment
|
||||
kubectl scale deployment socktop-webterm --replicas=5 -n default
|
||||
|
||||
# Restart deployment
|
||||
kubectl rollout restart deployment socktop-webterm -n default
|
||||
|
||||
# View rollout status
|
||||
kubectl rollout status deployment socktop-webterm -n default
|
||||
|
||||
# Delete everything
|
||||
kubectl delete -f . -n default
|
||||
```
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
- [ ] kubectl configured and connected to k3s cluster
|
||||
- [ ] Registry config copied to ALL k3s nodes
|
||||
- [ ] k3s services restarted on all nodes
|
||||
- [ ] Image pull tested successfully on at least one node
|
||||
- [ ] Deployed to k3s using deploy.sh or manual kubectl apply
|
||||
- [ ] Pods showing as Running (3/3)
|
||||
- [ ] Service has endpoints
|
||||
- [ ] Ingress created successfully
|
||||
- [ ] NGINX Proxy Manager configured with 3 proxy hosts
|
||||
- [ ] DNS pointing to NGINX Proxy Manager
|
||||
- [ ] Can access https://socktop.io in browser
|
||||
- [ ] WebSocket connections working
|
||||
- [ ] Terminal sessions functional
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once deployed successfully:
|
||||
|
||||
1. **Monitor Performance**: `kubectl top pods -l app=socktop-webterm -n default`
|
||||
2. **Check Logs**: Look for any errors or warnings
|
||||
3. **Test Load Balancing**: Verify traffic distributes across 3 pods
|
||||
4. **Configure Monitoring**: Set up Prometheus/Grafana if desired
|
||||
5. **Add Alerts**: Configure alerts for pod failures
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check `TROUBLESHOOTING.md` (if exists) or `README.md`
|
||||
2. View pod logs: `kubectl logs -l app=socktop-webterm -n default`
|
||||
3. Describe pods: `kubectl describe pods -l app=socktop-webterm -n default`
|
||||
4. Check events: `kubectl get events -n default --sort-by='.lastTimestamp'`
|
||||
5. Verify registry config on all nodes
|
||||
6. Check NGINX Proxy Manager logs
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- `QUICKSTART.md` - Fast deployment guide
|
||||
- `README.md` - Comprehensive documentation
|
||||
- `CHECKLIST.md` - Pre-deployment verification
|
||||
- `NGINX-PROXY-MANAGER.md` - Proxy configuration guide
|
||||
- `INDEX.md` - File overview and navigation
|
||||
Reference in New Issue
Block a user