# 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