socktop-webterm/kubernetes/CHECKLIST.md

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:

  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:

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

cd kubernetes
./deploy.sh

Option 2: Manual

cd kubernetes
kubectl apply -f .

Option 3: Kustomize

cd kubernetes
kubectl apply -k .

Post-Deployment Verification

After deployment, verify:

# 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