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