waylume_server/minimum_requirements.md

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