Getting Started

Avalon is a high-performance reverse proxy server written in Rust, built on Cloudflare's Pingora framework. It provides automatic HTTPS, load balancing, URL rewriting, and more.

Installation

From Source

# Clone the repository
git clone https://github.com/neomody77/avalon.git
cd avalon

# Build release version
cargo build --release

# Binary is at target/release/avalon

Using Docker

docker build -t avalon .
docker run -p 80:80 -p 443:443 -v ./avalon.toml:/app/avalon.toml avalon

Minimal Configuration

Create an avalon.toml configuration file:

# Global settings
[global]
log_level = "info"

# TLS settings (optional)
[tls]
acme_enabled = false

# Server configuration
[[servers]]
name = "web"
listen = [":8080"]

# Routing rules
[[servers.routes]]
[servers.routes.match]
path = ["/"]

[servers.routes.handle]
type = "static_response"
status = 200
body = "Hello, Avalon!"

[servers.routes.handle.headers]
Content-Type = "text/plain"

Running

./target/release/avalon --config avalon.toml

Visit http://localhost:8080 to see the response.

Common Use Cases

1. Reverse Proxy

Forward requests to backend services:

[[servers]]
name = "api-proxy"
listen = [":8080"]

[[servers.routes]]
[servers.routes.match]
path = ["/api"]

[servers.routes.handle]
type = "reverse_proxy"
upstreams = ["127.0.0.1:3000"]

2. Load Balancing

[[servers.routes]]
[servers.routes.handle]
type = "reverse_proxy"
upstreams = ["127.0.0.1:3001", "127.0.0.1:3002", "127.0.0.1:3003"]
load_balancing = "round_robin"  # Options: random, least_conn, ip_hash

3. Static File Server

[[servers.routes]]
[servers.routes.match]
path = ["/static"]

[servers.routes.handle]
type = "file_server"
root = "/var/www/static"
browse = false
index = ["index.html"]

4. Automatic HTTPS (Let's Encrypt)

[tls]
email = "[email protected]"
acme_enabled = true
storage_path = "./certs"

[[servers]]
name = "https-server"
listen = [":443"]

[[servers.routes]]
[servers.routes.match]
host = ["example.com"]
path = ["/"]

[servers.routes.handle]
type = "reverse_proxy"
upstreams = ["127.0.0.1:3000"]

5. HTTP to HTTPS Redirect

[[servers]]
name = "http-redirect"
listen = [":80"]
https_redirect = true

Hot Reload

Avalon supports hot configuration reload. After modifying the config file, send a SIGHUP signal:

kill -HUP $(pidof avalon)

Next Steps