Waylume Server is the backend component of the Waylume premium VPN service. It provides a REST API for WireGuard VPN management and integrates with Supabase for server registration and heartbeat monitoring. The server is designed to be easily deployed with Docker and can be spun up quickly to expand VPN infrastructure.

The server is written in Dart and uses process execution to interact with WireGuard tools. It is designed to be lightweight and efficient, making it suitable for deployment on various platforms, including cloud services and local servers.

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Apps   │───▶│    Supabase     │◄───│ Waylume Server  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   WireGuard     │
                                               └─────────────────┘

Client applications communicate through Supabase to discover available Waylume servers. Each server manages WireGuard connections via REST API and registers itself with Supabase for automatic discovery and load distribution.

Features

Core Functionality

WireGuard Interface Management: Automatic initialization and configuration of WireGuard server interface
Peer Management: Create, delete, and configure VPN peers dynamically
Traffic Control: Speed limiting and data cap enforcement per peer
Server Registration: Automatic registration with Supabase backend
Health Monitoring: Continuous heartbeat system for server availability

API Endpoints

POST /api/peers - Create new VPN peer with generated keys and configuration
DELETE /api/peers/{publicKey} - Remove VPN peer
PUT /api/peers/{publicKey}/speed-limit - Set bandwidth limits for peer
PUT /api/peers/{publicKey}/data-cap - Set data usage limits for peer
GET /api/peers/{publicKey}/config - Retrieve peer configuration (not implemented)

Security Features

Peer isolation using iptables rules (prevents peer-to-peer communication)
Traffic shaping and quota enforcement
Automatic IP address assignment within 10.0.0.0/8 range
Secure key generation for each peer

Prerequisites

Docker and Docker Compose
WireGuard kernel module support
Supabase project with waylume_servers table

Environment Variables

Create a .env file with the following variables:

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key

# Server Configuration
SERVER_ID=unique_server_identifier
EXTERNAL_PORT=3000

Quick Start

Using Docker Compose (Recommended)

Clone the repository
Create your .env file with required variables
Run the server:

docker-compose up -d

The server will be available on port 3000 (or your configured EXTERNAL_PORT).

Building from Source

Install Dart SDK (3.9.0-100.2.beta or later)
Install dependencies:

dart pub get

Compile and run:

dart compile exe lib/main.dart -o waylume_server
./waylume_server

Docker Configuration

The Docker setup includes:

WireGuard tools and kernel module support
iptables for traffic control and peer isolation
Network capabilities (NET_ADMIN) for interface management
UDP port 51820 for WireGuard traffic
TCP port 3000 for REST API

API Usage Examples

Create a new peer

curl -X POST http://localhost:3000/api/peers

Response:

{
  "success": true,
  "peer": {
    "privateKey": "...",
    "publicKey": "...",
    "ip": "10.0.0.2"
  },
  "config": "[Interface]\nPrivateKey = ...\n..."
}

Set speed limit for peer

curl -X PUT http://localhost:3000/api/peers/{publicKey}/speed-limit \
  -H "Content-Type: application/json" \
  -d '{"speedKbps": 1000}'

Set data cap for peer

curl -X PUT http://localhost:3000/api/peers/{publicKey}/data-cap \
  -H "Content-Type: application/json" \
  -d '{"dataCapMB": 1024}'

Delete a peer

curl -X DELETE http://localhost:3000/api/peers/{publicKey}

Network Architecture

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

Logging

The server provides detailed request logging including:

Client IP addresses (with proxy header support)
User agents
Request methods and paths
Timestamps

Development

The project structure:

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