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

kubectl get nodes -o wide

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

Step 2: Verify Traefik is Running

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

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

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

Should return the webterm HTML page.

Test 2: Check HTTPS via Proxy

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:

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

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

# 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

# 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! 🎉