jasonwitty
6e48c095ab
- Multi-architecture Docker image (ARM64 + AMD64) - Kubernetes manifests for 3-replica deployment - Traefik ingress configuration - NGINX Proxy Manager integration - ConfigMap-based configuration - Automated build and deployment scripts - Session monitoring tools
476 lines
11 KiB
Markdown
476 lines
11 KiB
Markdown
# 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 |