Home Docs Getting Started

Getting Started

Install, configure, and run Soli Proxy in under a minute

Installation

Soli Proxy can be installed easily using the install.sh script, which downloads pre-built binaries for your platform. The script supports Linux and macOS on x86_64 and arm64 architectures.

terminal

# Quick install to ~/.local/bin
curl -sSL https://raw.githubusercontent.com/solisoft/soli-proxy/main/install.sh | sh

# Or run the script locally
chmod +x install.sh && ./install.sh

# For system-wide installation (requires sudo)
./install.sh --system

Platform support

The install.sh script automatically detects your OS (Linux, macOS) and architecture (x86_64, arm64). Add ~/.local/bin to your PATH if needed.

Alternatively, you can build Soli Proxy from source. You need a working Rust toolchain (rustc 1.75+). Clone the repository and compile the release binary.

terminal

# Clone the repository
git clone https://github.com/solisoft/soli-proxy.git
cd soli-proxy

# Build the release binary
cargo build --release

# The binary is at soli-proxy

To enable Lua 5.4 scripting, the runtime is embedded by default and allows per-route script hooks.

terminal

# Build with Lua scripting support
cargo build --release

Routing Configuration

Routes are defined in proxy.conf. Each line maps a pattern to a backend using the -> operator. Soli Proxy supports domain-based routing, path-based routing, WebSocket targets, and a default fallback.

proxy.conf

# Domain-based routing
app.example.com  ->  http://localhost:3000/
api.example.com  ->  http://localhost:8080/

# Path-based routing (matched in order)
/api/*    ->  http://localhost:8888/
/ws       ->  ws://localhost:8888/

# Default fallback (catches everything else)
default   ->  http://localhost:8080/

Routing order matters

Domain rules are matched first by hostname. Path rules are matched in the order they appear. The default rule is the catch-all fallback when no other rule matches. Use ws:// for WebSocket backends.

config.toml Overview

Server behavior is controlled by config.toml in the project root. It contains sections for the HTTP server, TLS, admin API, logging, circuit breakers, and more. Here are the most important sections to get started.

config.toml

# --- Server ---
[server]
bind       = "0.0.0.0:80"
https_port = 443

# --- TLS ---
[tls]
mode      = "auto"       # "auto" for self-signed, "letsencrypt" for prod
cache_dir = "./certs"

# --- Let's Encrypt (production) ---
[letsencrypt]
staging      = false
email        = "[email protected]"
terms_agreed = true

# --- Admin API ---
[admin]
enabled       = true
bind          = "0.0.0.0:9090"
api_key       = "your-secret-key"
# username      = "admin"
# password_hash = "$2b$..."

# --- Apps ---
[apps]
# default_user  = "www-data"
# default_group = "www-data"

# --- Circuit Breaker ---
[circuit_breaker]
failure_threshold    = 5
recovery_timeout_secs = 30
success_threshold    = 2
failure_status_codes = [502, 503, 504]

# --- Lua Scripting (optional) ---
[scripting]
enabled        = false
scripts_dir    = "./scripts/lua"
hook_timeout_ms = 10

Development

Set tls.mode = "auto" to use self-signed certificates. The proxy generates them automatically on first run.

Production

Set tls.mode = "letsencrypt" and configure the [letsencrypt] section with your email for automatic ACME certificates.

CLI Usage

The soli-proxy binary accepts flags for daemon mode, dev mode, and a custom configuration path. By default it reads ./proxy.conf from the current directory.

terminal

# Run in foreground (reads ./proxy.conf)
soli-proxy

# Run as daemon (background, writes PID file)
soli-proxy -d
soli-proxy --daemon

# Dev mode (apps started with --dev flag)
soli-proxy --dev

# Custom config path
soli-proxy /etc/soli-proxy/proxy.conf

# Combine flags
soli-proxy -d --dev /etc/soli-proxy/proxy.conf

Flag	Description
`-d`, `--daemon`	Run as a background daemon. Forks the process and writes a PID file.
`--dev`	Enable dev mode. Apps in `sites/` are started with the `--dev` flag.
`<path>`	Custom path to `proxy.conf`. Defaults to `./proxy.conf` in the working directory.

Hot Reload with SIGUSR1

You can reload the routing configuration at runtime without restarting the server. Send the SIGUSR1 signal to the running process and Soli Proxy will re-read proxy.conf and apply changes immediately.

terminal

# Reload config without restart
kill -SIGUSR1 $(cat run/soli-proxy.pid)

# Or if you know the PID
kill -USR1 12345

Zero downtime

Config reloads are atomic. Existing connections continue on the old routing table while new connections use the updated rules. You can also reload via the Admin API if you prefer an HTTP interface.

Apps