Add load balancing configuration and minimum system requirements documentation

.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

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)

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