From 396229a9cb105fa42f945480887ab5d7a603c4af Mon Sep 17 00:00:00 2001 From: ImBenji Date: Fri, 22 Aug 2025 09:09:28 +0100 Subject: [PATCH] Add load balancing configuration and minimum system requirements documentation --- .env.example | 3 + README.md | 26 ++++++++ minimum_requirements.md | 135 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 minimum_requirements.md diff --git a/.env.example b/.env.example index 412b61f..48fd2d2 100644 --- a/.env.example +++ b/.env.example @@ -4,5 +4,8 @@ SERVER_ID=waylume-server-1 # Supabase Configuration SUPABASE_KEY=your_supabase_service_role_key_here +# Load Balancing Configuration +MAX_CAPACITY=200 + # Docker Port Configuration (optional) # EXTERNAL_PORT=3000 \ No newline at end of file diff --git a/README.md b/README.md index 63afdd0..90c4bbd 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,9 @@ SUPABASE_KEY=your_supabase_anon_key SERVER_ID=unique_server_identifier EXTERNAL_PORT=3000 +# Load Balancing Configuration +MAX_CAPACITY=1000 + # Optional: Geographic Information SERVER_COUNTRY=United Kingdom SERVER_CITY=London @@ -113,6 +116,29 @@ SERVER_COORDS_LAT=51.5074 SERVER_COORDS_LON=-0.1278 ``` +## Configuration Details + +### Load Balancing + +**MAX_CAPACITY** (integer, default: 1000) +- Soft capacity limit for the server +- When reached, the load balancer will prioritize other servers +- Does not prevent new connections, just influences routing decisions +- Range: 1-32,767 (int2) +- Used by the Supabase Edge Function `connection-request` for optimal server selection + +### Server Registration + +**SERVER_ID** (string, required) +- Unique identifier for the server in the Waylume network +- Used for rolling codes authentication and session tracking +- Should be URL-safe (alphanumeric with hyphens/underscores) + +**Geographic Information** (optional but recommended) +- Enables location-based server selection for premium users +- Improves load distribution across regions +- Required for the location selection feature in the client app + ## Quick Deployment ### Using Docker Compose (Recommended) diff --git a/minimum_requirements.md b/minimum_requirements.md new file mode 100644 index 0000000..c6dd770 --- /dev/null +++ b/minimum_requirements.md @@ -0,0 +1,135 @@ +# Waylume Server - Minimum System Requirements + +## Overview + +Waylume Server is a self-managing WireGuard VPN node built in Dart that handles peer connections, traffic control, and bandwidth monitoring. The server operates as a containerized application with specific system requirements for optimal performance. + +## Minimum System Requirements + +### Operating System +- **Linux** (Ubuntu 20.04+ recommended) +- **Kernel**: 5.6+ (WireGuard kernel module support) +- **Architecture**: x86_64 or ARM64 + +### Hardware Requirements + +#### Base Configuration (Up to 100 concurrent VPN sessions) +- **CPU**: 2 vCPU cores (2.4 GHz minimum) +- **RAM**: 2 GB +- **Storage**: 10 GB SSD +- **Network**: 100 Mbps bandwidth + +#### Standard Configuration (Up to 500 concurrent VPN sessions) +- **CPU**: 4 vCPU cores (2.4 GHz minimum) +- **RAM**: 4 GB +- **Storage**: 20 GB SSD +- **Network**: 500 Mbps bandwidth + +#### High-Performance Configuration (Up to 1000 concurrent VPN sessions) +- **CPU**: 8 vCPU cores (3.0 GHz minimum) +- **RAM**: 8 GB +- **Storage**: 40 GB SSD +- **Network**: 1 Gbps bandwidth + +## Performance Estimates per VPN Session + +### Memory Usage +- **Per active session**: ~2-4 MB RAM +- **Base server overhead**: ~512 MB RAM +- **Example**: 1000 active sessions ≈ 4.5 GB total RAM usage + +### CPU Usage +- **Per session (idle)**: ~0.1% CPU +- **Per session (active traffic)**: ~0.5-1% CPU +- **Traffic control overhead**: ~0.2% CPU per session with speed limits +- **Example**: 1000 active sessions ≈ 10-15% CPU usage under load + +### Network Performance +- **Theoretical limit**: Dependent on host network interface and bandwidth +- **Practical throughput**: ~80-90% of available bandwidth per direction +- **Latency overhead**: <5ms additional latency through WireGuard + +### Storage Requirements +- **Log files**: ~1-5 MB per day per 100 sessions +- **Configuration overhead**: <1 MB +- **WireGuard state**: Minimal (<10 KB per peer) + +## Required System Capabilities + +### Kernel Modules +- **WireGuard**: Kernel module or userspace implementation +- **netfilter/iptables**: For traffic control and firewall rules +- **tc (Traffic Control)**: HTB queueing disciplines for bandwidth limiting + +### Network Configuration +- **NET_ADMIN capability**: Required for interface management +- **Access to /dev/net/tun**: For VPN tunnel creation +- **Forwarding enabled**: IP forwarding must be enabled +- **NAT/Masquerading**: For outbound traffic routing + +### Docker Requirements +- **Docker Engine**: 20.10+ +- **Docker Compose**: 2.0+ +- **Privileged containers**: NET_ADMIN and device access + +## Resource Scaling Guidelines + +### Linear Scaling Factors +- **RAM**: +2-4 MB per additional session +- **CPU**: +0.1-0.5% per additional session +- **Storage**: +10 KB per peer configuration + +### Non-Linear Factors +- **iptables rules**: Performance degrades with >1000 rules +- **Traffic control**: HTB performance impacts at scale +- **Supabase API calls**: Rate limiting considerations + +## External Dependencies + +### Network Connectivity +- **Supabase API**: HTTPS access to Supabase Edge Functions +- **DNS Resolution**: Required for external connectivity +- **NTP**: Time synchronization for rolling code authentication + +### Storage I/O +- **Configuration writes**: Minimal, mostly at startup +- **Log rotation**: Recommended for long-running deployments +- **No persistent state**: Server is stateless by design + +## Recommended Production Setup + +### Infrastructure +- **Cloud Provider**: AWS, Google Cloud, or Azure +- **Instance Type**: Compute-optimized instances preferred +- **Load Balancer**: Not required (direct peer connections) +- **Monitoring**: Docker logs and Supabase metrics + +### Network Configuration +- **Firewall Rules**: + - Port 3000/tcp (API - restrict to Supabase Edge Functions) + - Port 51820/udp (WireGuard - public) +- **IP Ranges**: 10.0.0.0/8 reserved for VPN clients +- **BGP/Routing**: Static routing sufficient + +### Security Considerations +- **API Security**: Port 3000 should only accept connections from Supabase +- **Container Security**: Run with minimal required privileges +- **Network Isolation**: Consider VPC/network segmentation +- **Updates**: Regular container image updates recommended + +## Performance Optimization Tips + +1. **Use SSD storage** for faster container startup +2. **Enable CPU scaling** if running on cloud platforms +3. **Monitor iptables rule count** - consider optimization at scale +4. **Use dedicated network interfaces** for high-throughput scenarios +5. **Implement log rotation** to prevent disk space issues +6. **Monitor Supabase quotas** for API rate limiting + +## Limitations and Considerations + +- **Maximum peers**: Theoretical limit ~16M (IPv4 address space) +- **Practical limit**: ~1000-2000 concurrent sessions per server +- **iptables performance**: Degrades with large rule sets +- **Memory growth**: Linear with session count +- **Supabase dependency**: Requires external connectivity for management \ No newline at end of file