Skip to main content

Getting Started

This guide covers installation, building from source, and running edgeProxy locally.

Prerequisites​

Required​

Optional​

  • Docker & Docker Compose - For containerized deployment
GeoIP Included

The MaxMind GeoLite2 database is embedded in the binary - no external download required.

Installation​

From Source​

# Clone repository
git clone https://github.com/andrebassi/edgeproxy.git
cd edgeproxy

# Build release binary
task build:release

# Verify installation
./target/release/edge-proxy --help

Using Docker​

# Build Docker image
task docker:build

# Start multi-region environment
task docker:up

Project Structure​

edgeProxy uses Hexagonal Architecture (Ports & Adapters):

Project Structure

First Run​

1. Initialize Routing Database​

# Create database with sample backends
task db:init

This creates routing.db with the following schema:

CREATE TABLE backends (
    id TEXT PRIMARY KEY,
    app TEXT,
    region TEXT,          -- "sa", "us", "eu"
    wg_ip TEXT,           -- Backend IP (WireGuard)
    port INTEGER,
    healthy INTEGER,      -- 0 or 1
    weight INTEGER,       -- Relative weight
    soft_limit INTEGER,   -- Comfortable connections
    hard_limit INTEGER,   -- Maximum connections
    deleted INTEGER DEFAULT 0
);

2. Start edgeProxy​

# Run with default configuration (region=sa, port=8080)
task run:dev

# Or with custom settings
EDGEPROXY_REGION=us EDGEPROXY_LISTEN_ADDR=0.0.0.0:9000 task run:dev

3. Test Connection​

# Connect to proxy
echo "Hello" | nc localhost 8080

# Expected output (if backend is running):
# Backend: sa-node-1 | Region: sa | Your IP: 127.0.0.1:xxxxx
# [sa-node-1] Echo: Hello

Running Tests​

Unit Tests​

# Run all tests (485 tests)
task test:all

# Run with coverage
task test:coverage

Local Multi-Region Simulation​

# Terminal 1: Start mock backends
task local:env

# Terminal 2: Start proxy
task run:sa

# Terminal 3: Run tests
task local:test

Docker Tests​

# Full Docker test suite
task docker:build
task docker:up
task docker:test

# Cleanup
task docker:down

Available Tasks​

Run task --list to see all available tasks. Main categories:

Build​

TaskDescription
task build:releaseBuild release binary
task build:linuxCross-compile for Linux AMD64
task build:allBuild for all platforms

Run​

TaskDescription
task run:devRun with default config
task run:saRun as SA POP
task run:usRun as US POP
task run:euRun as EU POP

Test​

TaskDescription
task test:allRun all unit tests
task test:coverageRun with coverage report

Database​

TaskDescription
task db:initInitialize routing.db
task db:resetReset to initial state

Docker​

TaskDescription
task docker:buildBuild Docker images
task docker:upStart Docker environment
task docker:downStop Docker environment
task docker:testRun Docker test suite

Documentation​

TaskDescription
task docs:serveBuild and serve docs (EN + PT-BR)
task docs:devDev mode (EN only, hot reload)

Next Steps​