How Networking Works

Understanding how network traffic flows between a user’s browser, your reverse proxy, and the Spokes server is crucial for troubleshooting deployment issues.

Spokes uses a hybrid networking model: standard web traffic is routed conventionally, while real-time voice and video establish direct peer-to-server connections that intentionally bypass your reverse proxy.

The Two Phases of a Connection

When a user connects to your Spokes server and joins a voice channel, the connection occurs in two distinct phases.

Phase 1: Signaling (Web & WebSockets)

When you first open Spokes, your browser makes standard HTTP requests to your configured Server Public URL (e.g., https://spokes.yourdomain.com).

1. Routing: This traffic hits your reverse proxy (e.g., Cloudflare Tunnel or Nginx Proxy Manager).
2. Upgrade: The proxy forwards the request to the Spokes server’s Web UI port (internal port 8080) and upgrades the connection to a WebSocket.
3. Signaling: LiveKit and the browser use this WebSocket to exchange text-based instructions. No audio or video is transmitted yet. They are simply negotiating how to send the media.

Because this phase relies on standard HTTP/WebSockets, it is fully protected by your reverse proxy’s SSL, WAF, and DDoS mitigation.

Phase 2: Media (Direct UDP)

During the Signaling phase, the browser and the embedded LiveKit engine must determine how to exchange the heavy media traffic (UDP packets). This process is handled via WebRTC ICE (Interactive Connectivity Establishment) negotiation.

1. IP Discovery: The embedded LiveKit server automatically figures out your router’s true Public IP address. It does this quietly in the background by pinging a public STUN server (like Google’s).
2. The Handshake: LiveKit sends an instruction over the secure WebSocket to the browser: “Send your UDP media traffic directly to my router’s Public IP on port 50000.”
3. Direct Connection: The browser receives this instruction and starts firing UDP packets directly to that raw IP address, completely bypassing spokes.yourdomain.com and your reverse proxy.

Why You Need Port Forwarding

This direct media connection is why Step 5: Firewalls & Routers is absolutely critical, even if you are using a secure Cloudflare Tunnel for your Web UI.

When the client’s browser sends UDP media packets directly to your Public IP, those packets hit your hardware router. If you have correctly configured your port forwarding rules, the router intercepts the traffic on ports 50000-50499 and forwards it straight to your Spokes Docker container.

If these ports are closed, or if they are not mapped 1-to-1 (e.g., your router forwards port 50000 to container port 50005), the WebRTC connection will fail, and users will be stuck on “Connecting…” indefinitely.

The Advantages of this Architecture

This hybrid approach provides the best of both worlds:

1. Security: Your Web UI, APIs, and WebSockets are hidden behind your reverse proxy. Automated bots and script kiddies scanning the internet for vulnerable web servers (ports 80/443) will only see your proxy provider, not your home IP.
2. Performance: Real-time voice and video are extremely sensitive to latency. By establishing a direct UDP connection, the media traffic takes the fastest possible route over the internet, avoiding the overhead and potential bottlenecks of passing through proxy servers.