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:

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