Waylume Server

About

Waylume Server is a self-managing WireGuard VPN node that operates as part of the Waylume VPN infrastructure. Each server instance automatically registers with Supabase, manages WireGuard peer configurations, and responds to connection requests through Supabase Edge Functions. The server is designed for autonomous operation with minimal maintenance requirements.

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Flutter Client │───▶│ Supabase Edge   │───▶│ Waylume Server  │
│      App        │    │   Functions     │    │     Node        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   PostgreSQL    │    │   WireGuard     │
                       │    Database     │    │   Interface     │
                       └─────────────────┘    └─────────────────┘

Client Flow:

1. Flutter app requests available servers via vpn-nodes-list edge function
2. User selects server and requests connection via connection-request edge function
3. Edge function calls Waylume Server API to create WireGuard peer
4. Server responds with peer configuration through Supabase
5. Client receives WireGuard config and establishes VPN connection

Role in Waylume Ecosystem

Server Registration & Discovery

• Automatic Registration: Servers register themselves in the waylume_servers table on startup
• Heartbeat Monitoring: Continuous health reporting to maintain server availability status
• Geolocation Integration: Provides location data for client server selection interface
• Load Distribution: Multiple servers can be deployed for geographic distribution and load balancing

Integration with Supabase Edge Functions

The server's REST API is exclusively accessed through Supabase Edge Functions:

• connection-request: Calls POST /api/peers to create new VPN peers
• Session Management: Works with vpn_sessions table for connection tracking
• Configuration Delivery: Peer configs are delivered through Supabase to clients

WireGuard Management

• Interface Initialization: Automatically configures wg0 interface on startup
• Dynamic Peer Creation: Creates peers with unique keys and IP assignments
• Traffic Control: Implements speed limiting and data caps per peer
• Peer Isolation: Enforces security rules to prevent peer-to-peer communication
• Cleanup Operations: Removes peers and associated configurations on disconnect

Features

Self-Managing Operations

• Zero-Touch Deployment: Fully automated setup with Docker
• Health Monitoring: Built-in health checks and status reporting
• Automatic Recovery: Handles WireGuard interface failures and restarts
• Resource Management: Efficient peer lifecycle management

Security & Traffic Control

• Peer Isolation: iptables rules prevent peer-to-peer communication
• Bandwidth Control: HTB-based speed limiting per peer
• Data Quotas: iptables quota enforcement for usage limits
• IP Management: Automatic IP assignment from managed subnets

API Endpoints (Internal Use Only)

⚠️ Important: These endpoints are for internal server management through Supabase Edge Functions only. They are not designed for direct client access and lack authentication for security reasons.

POST /api/peers

Creates a new WireGuard peer with generated keys and IP assignment.

• Called by: connection-request edge function
• Purpose: Establish new VPN connection for authenticated user

POST /api/peers/delete

Removes a WireGuard peer and cleans up configuration.

• Called by: Session cleanup processes
• Purpose: Terminate VPN connections and free resources

POST /api/peers/speed-limit

Applies bandwidth limitations to specific peers.

• Called by: Subscription management functions
• Purpose: Enforce plan-based speed limits

POST /api/peers/data-cap

Sets data usage quotas for peers.

• Called by: Usage monitoring systems
• Purpose: Enforce plan-based data allowances

Prerequisites

• Docker and Docker Compose
• WireGuard kernel module support
• Supabase project with proper database schema
• Network capabilities for WireGuard interface management

Environment Variables

Create a .env file with the following variables:

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key

# Server Configuration  
SERVER_ID=unique_server_identifier
EXTERNAL_PORT=3000

# Load Balancing Configuration
MAX_CAPACITY=1000

# Optional: Geographic Information
SERVER_COUNTRY=United Kingdom
SERVER_CITY=London
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)

1. Clone the repository
2. Create your .env file with required Supabase credentials
3. Deploy the server:

docker-compose up -d

The server will:

• Initialize WireGuard interface (wg0)
• Register with your Supabase backend
• Begin heartbeat monitoring
• Start accepting API requests on port 3000

Verification

Check that the server registered successfully:

-- In your Supabase SQL editor
SELECT * FROM waylume_servers WHERE id = 'your_server_id';

Network Configuration

• WireGuard Interface: wg0 on 10.0.0.1/24
• Peer IP Range: 10.0.0.2 - 10.255.255.254
• WireGuard Port: 51820/udp
• API Port: 3000/tcp (internal access only)

Production Deployment

Security Considerations

• Deploy behind a firewall with port 3000 restricted to Supabase Edge Functions
• Use private networks when possible for API communication
• Implement network segmentation for additional security
• Monitor logs for unusual API access patterns

Scaling Strategy

• Deploy multiple servers across different geographic regions
• Use unique SERVER_ID values for each instance
• Monitor server load through Supabase analytics
• Implement auto-scaling based on connection demand

Monitoring & Maintenance

• Server health is automatically reported to Supabase
• Monitor waylume_servers table for server availability
• Check Docker logs for operational issues
• WireGuard interface status is self-managed

Development

Project Structure

lib/
├── config/          # Supabase configuration and credentials
├── core/            # Utility functions and helpers
├── services/        # Core services (server, heartbeat, wireguard)
├── web/             # HTTP routes and API handlers
├── wireguard/       # WireGuard-specific functionality
└── main.dart        # Application entry point and server initialization

Testing Server Integration

You can test the integration by triggering a connection request through your Supabase Edge Functions:

# Test server listing
curl -X GET https://your-project.supabase.co/functions/v1/vpn-nodes-list

# Test connection request (requires authentication)
curl -X POST https://your-project.supabase.co/functions/v1/connection-request \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server_id": "your_server_id"}'

Troubleshooting

Common Issues

Server not appearing in node list:

• Check Supabase credentials in .env
• Verify server registered in waylume_servers table
• Ensure heartbeat process is running

WireGuard interface issues:

• Verify WireGuard kernel module is loaded: lsmod | grep wireguard
• Check Docker has NET_ADMIN capability
• Ensure /dev/net/tun is accessible

API connectivity problems:

• Verify port 3000 is accessible from Supabase Edge Functions
• Check firewall rules and network configuration
• Review Docker logs for startup errors

Logging

The server provides comprehensive logging including:

• Supabase registration and heartbeat status
• WireGuard interface management
• API request processing
• Peer lifecycle events
• Error conditions and recovery attempts

Monitor logs with:

docker-compose logs -f waylume-server