socktop-webterm/kubernetes/NGINX-PROXY-MANAGER.md

# NGINX Proxy Manager Configuration for Socktop WebTerm

This guide explains how to configure your external NGINX Proxy Manager to route traffic to your k3s Socktop WebTerm deployment.

## Overview

Since your ISP restricts incoming ports, you're using an external NGINX Proxy Manager to:
- Terminate SSL/TLS connections
- Route traffic on port 8080 to your k3s cluster
- Handle WebSocket upgrades for terminal connections

## Architecture

```
Internet (HTTPS:443)
    ↓
External NGINX Proxy Manager
    ↓ (SSL Termination)
k3s Traefik Ingress (HTTP:8080)
    ↓
Socktop WebTerm Service
    ↓
Pods (3 replicas)
```

## Prerequisites

- [ ] NGINX Proxy Manager installed and accessible
- [ ] SSL certificates ready (Let's Encrypt or custom)
- [ ] k3s cluster deployed with Socktop WebTerm
- [ ] Know your k3s node IP addresses
- [ ] DNS records pointing to your external NGINX Proxy Manager

## Configuration Steps

### Step 1: Get Your k3s Node IP

Find the IP address of any k3s node (Traefik runs on all nodes with k3s):

```bash
kubectl get nodes -o wide
```

Note any node's INTERNAL-IP (e.g., `192.168.1.101`).

### Step 2: Verify Traefik is Running

```bash
kubectl get svc -n kube-system traefik
```

You should see Traefik listening on port 80.

### Step 3: Create Proxy Host for socktop.io

In NGINX Proxy Manager web UI:

1. **Go to**: Proxy Hosts → Add Proxy Host

2. **Details Tab**:
   - **Domain Names**: `socktop.io`
   - **Scheme**: `http` (NOT https - SSL terminates at proxy)
   - **Forward Hostname / IP**: `192.168.1.101` (your k3s node IP)
   - **Forward Port**: `8080`
   - **Cache Assets**: ☐ (unchecked)
   - **Block Common Exploits**: ☑ (checked)
   - **Websockets Support**: ☑ (IMPORTANT - check this!)
   - **Access List**: None (or your preference)

3. **SSL Tab**:
   - **SSL Certificate**: Select or create new Let's Encrypt certificate
   - **Force SSL**: ☑ (checked)
   - **HTTP/2 Support**: ☑ (checked)
   - **HSTS Enabled**: ☑ (optional but recommended)
   - **HSTS Subdomains**: ☐ (unless you want this)

4. **Advanced Tab** (optional but recommended):
   ```nginx
   # Increase timeouts for long-running terminal connections
   proxy_read_timeout 3600s;
   proxy_send_timeout 3600s;
   proxy_connect_timeout 60s;
   
   # WebSocket upgrade headers (should be set automatically, but just in case)
   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";
   
   # Pass through real client IP
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   ```

5. Click **Save**

### Step 4: Create Proxy Host for www.socktop.io

Repeat Step 3 with:
- **Domain Names**: `www.socktop.io`
- All other settings identical

### Step 5: Create Proxy Host for origin.socktop.io

Repeat Step 3 with:
- **Domain Names**: `origin.socktop.io`
- All other settings identical

## Verify Configuration

### Test 1: Check HTTP Forward

From your local machine:

```bash
curl http://<k3s-node-ip>:8080 -H "Host: socktop.io"
```

Should return the webterm HTML page.

### Test 2: Check HTTPS via Proxy

```bash
curl -I https://socktop.io
```

Should return `200 OK` with SSL certificate.

### Test 3: Check WebSocket Support

In your browser's developer console (F12), check the Network tab when connecting to the terminal. You should see:
- WebSocket connection established
- Status: `101 Switching Protocols`

## Troubleshooting

### 502 Bad Gateway

**Cause**: NGINX Proxy Manager can't reach k3s

**Fix**:
- Verify k3s node IP is correct
- Check port 8080 is accessible: `curl http://<node-ip>:8080`
- Ensure firewall allows traffic from proxy to k3s
- Check Traefik is running: `kubectl get pods -n kube-system | grep traefik`

### SSL Certificate Error

**Cause**: SSL certificate not properly configured

**Fix**:
- Verify DNS points to NGINX Proxy Manager IP
- Wait for Let's Encrypt validation (can take a few minutes)
- Check NGINX Proxy Manager logs for certificate errors

### WebSocket Connection Fails

**Cause**: WebSocket support not enabled or timeouts too short

**Fix**:
- Enable "Websockets Support" checkbox in proxy host
- Add custom nginx configuration with longer timeouts (see Step 3, Advanced tab)
- Check browser console for specific WebSocket errors

### Terminal Disconnects After 60 Seconds

**Cause**: Default proxy timeouts are too short

**Fix**: Add to Advanced tab in proxy host:
```nginx
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
```

### Can Access HTTP but not HTTPS

**Cause**: DNS records still point to old IP or wrong IP

**Fix**:
- Verify DNS with: `nslookup socktop.io`
- Should return your external NGINX Proxy Manager IP
- Wait for DNS propagation (up to 24 hours, usually minutes)

## Load Balancing (Optional)

If you want to load balance across multiple k3s nodes:

### Option 1: Use Multiple Upstream Servers in Advanced Config

```nginx
# Add to Advanced tab
upstream k3s_backend {
    server 192.168.1.101:8080;
    server 192.168.1.102:8080;
    server 192.168.1.104:8080;
}

# Then change proxy_pass to use upstream
proxy_pass http://k3s_backend;
```

### Option 2: Use k3s LoadBalancer Service

Change the Service type in `04-service.yaml` to `LoadBalancer` and use the assigned external IP.

## Security Best Practices

1. **Enable Force SSL**: Always redirect HTTP to HTTPS
2. **Enable HSTS**: Tells browsers to always use HTTPS
3. **Enable Block Common Exploits**: Provides basic protection
4. **Add Access List**: Restrict by IP if possible
5. **Use Strong SSL**: Enable HTTP/2, disable old TLS versions
6. **Keep Timeouts Reasonable**: 3600s (1 hour) for terminal sessions

## Example Complete Advanced Configuration

For best results, use this in the Advanced tab:

```nginx
# Timeouts for long-running connections
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_connect_timeout 60s;
keepalive_timeout 3600s;

# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# Pass through client information
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

# Buffering (disable for WebSockets)
proxy_buffering off;

# Security headers
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;
```

## Testing Checklist

After configuration, verify:

- [ ] Can access https://socktop.io and see login/terminal page
- [ ] Can access https://www.socktop.io (same result)
- [ ] Can access https://origin.socktop.io (same result)
- [ ] SSL certificate shows as valid (no browser warnings)
- [ ] Terminal connections work and stay connected
- [ ] WebSocket shows as connected in browser dev tools
- [ ] Can switch between different profiles
- [ ] Terminal sessions survive page refresh (with session affinity)

## Monitoring

### Check NGINX Proxy Manager Logs

In NGINX Proxy Manager UI:
- Go to proxy host → Click on host → View logs

### Check k3s Side

```bash
# Check ingress
kubectl get ingress socktop-webterm

# Check service endpoints
kubectl get endpoints socktop-webterm

# Check pod logs
kubectl logs -l app=socktop-webterm -f
```

## Common Traffic Flow Issues

| Symptom | Likely Cause | Check |
|---------|--------------|-------|
| 404 Not Found | Traefik routing issue | `kubectl describe ingress socktop-webterm` |
| 502 Bad Gateway | Can't reach k3s | Firewall, k3s node IP, port 8080 |
| 503 Service Unavailable | Pods not ready | `kubectl get pods -l app=socktop-webterm` |
| SSL Error | Certificate issue | NGINX Proxy Manager SSL tab |
| WebSocket fails | WS not enabled | Enable WebSocket support checkbox |

## Summary

Your complete setup should be:

1. **DNS**: socktop.io → Your external IP (NGINX Proxy Manager)
2. **NGINX Proxy Manager**: 
   - Listens on 443 (HTTPS)
   - Terminates SSL
   - Forwards to k3s-node:8080 (HTTP)
   - WebSocket support enabled
3. **k3s Traefik**: 
   - Receives HTTP on port 8080
   - Routes to socktop-webterm service
4. **Service**: 
   - Routes to healthy pods
   - Session affinity enabled
5. **Pods**: 
   - 3 replicas running webterm
   - Host network for Pi access

All working? You should now have a secure, load-balanced terminal interface! 🎉