socktop-webterm/kubernetes/SETUP-GUIDE.md

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:

# On k3s server node, get the kubeconfig
sudo cat /etc/rancher/k3s/k3s.yaml

Copy this content to your local machine:

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

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

# 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

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

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:

   ssh ubuntu@192.168.1.101  # replace with your node IP
   

2. Create the k3s config directory:

   sudo mkdir -p /etc/rancher/k3s
   

3. Create the registries.yaml file:

   sudo nano /etc/rancher/k3s/registries.yaml
   

4. Paste this content:

   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:

   # On server nodes
   sudo systemctl restart k3s
   
   # On agent/worker nodes
   sudo systemctl restart k3s-agent
   

7. Verify the service is running:

   sudo systemctl status k3s        # on server
   sudo systemctl status k3s-agent  # on agents
   

8. Test image pull:

   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

# 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

# Test registry access from node
curl http://192.168.1.208:3002/v2/

# Should return {} or a Docker registry response

Problem: Permission denied

# 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

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:

# 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

# 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):

   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):

   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:

# 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

kubectl config get-contexts

Switch Context

kubectl config use-context <context-name>

View Current Context

kubectl config current-context

Set Default Namespace

kubectl config set-context --current --namespace=socktop

View Cluster Info

kubectl cluster-info

Node Configuration Quick Reference

Check k3s Service Status

# On server node
sudo systemctl status k3s

# On agent/worker node
sudo systemctl status k3s-agent

View k3s Logs

sudo journalctl -u k3s -f         # server
sudo journalctl -u k3s-agent -f   # agent

Verify Registry Config

sudo cat /etc/rancher/k3s/registries.yaml

Test Image Pull

sudo k3s crictl pull 192.168.1.208:3002/jason/socktop-webterm:0.2.0

List Images on Node

sudo k3s crictl images | grep socktop

Helpful kubectl Commands

# 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