Uploading a 50 GB database dump or raw media folder to Google Drive or Dropbox just to ship it to a machine sitting across the room is an architectural crime. You pay the tax twice: first in upstream bandwidth to an intermediary storage bucket, then in downstream latency while the recipient pulls it down. The open-source Filesync project bypasses this intermediate storage model entirely. It establishes direct, browser-to-browser WebRTC pipes with zero client installations, zero identity providers, and zero persistent bytes on the server.
The elegance of pure peer-to-peer (P2P) transfers inside browser sandboxes often hides brutal systems challenges: NAT traversal failure modes, WebRTC signaling complexity, and catastrophic browser memory leaks. Here is how Filesync navigates those realities under the hood.
The Control Plane vs. Data Plane Split
WebRTC operates on a strict separation of concerns: signaling and transport. Filesync structures its stack around this exact boundary.
+-------------------------------------------------------------+
| Signaling Phase |
| [Browser A] <--- WebSocket (/ws) ---> [Signaling Server] |
| | (SDP Offer/Answer) | |
| +---------- (ICE Candidates) ------------+ |
+-------------------------------------------------------------+
|
Connection Established
|
+-------------------------------------------------------------+
| Data Phase |
| [Browser A] <====== Encrypted WebRTC DataChannel ========> |
| [Browser B] |
| |
| (Fallback via coturn STUN/TURN if Symmetric NAT blocks P2P)|
+-------------------------------------------------------------+
The server acts solely as a lightweight WebSocket broker exposed on the /ws path. When a sender creates a room or generates a QR code, the server routes Session Description Protocol (SDP) offer/answer payloads and Interactive Connectivity Establishment (ICE) candidate coordinates between endpoints.
Once this initial handshake finishes, the signaling server entirely drops out of the data path. File streams pass directly between peer browsers over an encrypted data channel. The server never inspects, caches, or writes a single byte of your payload to disk.
For edge cases where both endpoints sit behind symmetric NAT or hyper-restrictive enterprise firewalls, direct P2P socket binding fails. In these scenarios, the stack gracefully drops back to a STUN/TURN relay driven by coturn.
The RAM Trap: Why Plain HTTP Will Crash Your Browser Tab
Transporting gigabytes over an encrypted pipe is only half the engineering challenge. The second half happens locally: what does the receiving browser do with incoming stream chunks?
If you deploy Filesync improperly over unencrypted HTTP, your browser tab will likely crash on large files. The browser cannot access modern streaming disk APIs over unencrypted origins, which triggers an aggressive memory penalty.
| Save Method | Supported Browsers | Protocol Requirement | RAM Impact |
|---|---|---|---|
| File System Access API | Desktop Chromium (Chrome, Edge, Brave) | HTTPS / Localhost | Near zero; bytes stream straight to disk |
| Service Worker | All modern browsers | HTTPS / Localhost | Very low; streamed to Downloads folder |
| Blob | All browsers | Plain HTTP | High; buffers entire file in RAM |
When constrained to plain HTTP, the browser relies on the Blob fallback mechanism. It buffers incoming binary chunks entirely in heap memory until the transfer reaches 100%, and only then presents the file to the OS. Send a 5 GB file over HTTP, and the tab will attempt to allocate 5 GB of RAM, turning any transfer over 500 MB into an instant out-of-memory crash.
Serving the application over HTTPS unlocks the File System Access API and Service Worker pipelines. Chromium-based browsers write chunks straight to persistent disk blocks as they arrive from the network. Non-Chromium modern browsers leverage Service Worker background pipelines to route bytes straight to the OS Downloads directory. The heap usage curve stays virtually flat regardless of whether you transfer 50 MB or 50 GB.
Production Deployment and Ingress Setup
Deploying Filesync requires provisioning the application along with coturn for TURN credential generation and Caddy for automated TLS termination.
1. Cryptographic Key Generation
The coturn authentication engine requires a static shared secret to sign and validate short-lived TURN credentials. Generate a 32-byte cryptographically secure key:
bashpython3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
Store this token string securely.
2. Local Testing Configuration (HTTP)
For isolated LAN testing where streaming storage constraints are not an issue, configure deploy/docker-compose.yml with your secret key:
yaml- --static-auth-secret=YOUR_SECRET_STRING - SECRET_KEY=YOUR_SECRET_STRING
Bring the local stack online:
bashdocker compose up -d
3. Hardened Production Configuration (HTTPS)
For public edge deployments, run the stack behind Caddy using deploy/docker-compose-ssl.yml and deploy/Caddyfile. Caddy automates Let's Encrypt certificate retrieval and updates, ensuring browsers immediately grant access to streaming filesystem APIs.
Update your Caddyfile definition:
textfilesync.yourdomain.com { reverse_proxy filesync:80 }
Spin up the production topology:
bashdocker compose -f docker-compose-ssl.yml up -d
Network Firewall and Port Topology
WebRTC deployments break when infrastructure engineers forget auxiliary UDP ranges. You must open both signaling ports and the dynamic TURN relay pool across your VPS security groups and firewalls.
| Port | Protocol | Purpose |
|---|---|---|
| 80 / 443 | TCP | Web UI & WebSocket Signaling |
| 3478 | TCP & UDP | STUN/TURN Initial Handshake |
| 50000-50100 | UDP | TURN Relay Data Channel (fallback when direct P2P fails) |
Pay close attention to the UDP 50000-50100 range. Roughly 5% to 10% of real-world internet connections cannot complete direct peer-to-peer hole punching due to carrier-grade NAT (CGNAT) or strict routing policies. This dedicated UDP relay allocation serves as the fallback transport layer, guaranteeing the transfer completes without dropping the session when direct P2P paths are impossible.