Skip to main content

​
Install UltraBalancer

curl -LO https://github.com/bas3line/ultrabalancer/releases/latest/download/ultrabalancer-linux-x86_64
chmod +x ultrabalancer-linux-x86_64
sudo mv ultrabalancer-linux-x86_64 /usr/local/bin/ultrabalancer
See the Installation Guide for detailed instructions for your platform.

​
Start Test Backends

Let’s create some test backend servers to load balance across: 
#!/usr/bin/env python3
import http.server
import socketserver
import sys

PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8001

class Handler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/plain')
        self.end_headers()
        response = f"Backend server on port {PORT}\n"
        self.wfile.write(response.encode())

    def log_message(self, format, *args):
        print(f"[Backend {PORT}] {format % args}")

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print(f"Backend server running on port {PORT}")
    httpd.serve_forever()
Start three backend servers: 
# Terminal 1
python3 test_backend.py 8001

# Terminal 2
python3 test_backend.py 8002

# Terminal 3
python3 test_backend.py 8003

​
Start UltraBalancer

Now start the load balancer: 
ultrabalancer start round-robin \
  127.0.0.1:8001 \
  127.0.0.1:8002 \
  127.0.0.1:8003 \
  -p 8080
You should see output like: 
UltraBalancer starting...
Algorithm: Round Robin
Backends: 3
   - 127.0.0.1:8001 (weight: 100)
   - 127.0.0.1:8002 (weight: 100)
   - 127.0.0.1:8003 (weight: 100)
Health checks: enabled (every 5s, max 3 failures)
Listening on: 0.0.0.0:8080
Ready to accept connections

​
Test Load Balancing

# Send requests and see load balancing in action
for i in {1..10}; do
  curl http://localhost:8080
  sleep 0.5
done
You should see responses cycling through your backends: 
Backend server on port 8001
Backend server on port 8002
Backend server on port 8003
Backend server on port 8001
Backend server on port 8002
...

​
Monitor Health and Metrics

curl http://localhost:8080/health | jq
Health Response: 
{
  "status": "ok",
  "healthy_backends": "3/3",
  "uptime_seconds": 120
}
Metrics Response: 
{
  "total_requests": 10,
  "successful_requests": 10,
  "failed_requests": 0,
  "avg_response_time_ms": 2.3,
  "p50_response_time_ms": 2.1,
  "p95_response_time_ms": 3.5,
  "p99_response_time_ms": 4.2,
  "uptime_seconds": 120,
  "requests_per_second": 0.08
}

​
Test Health Checking

Kill one of the backend servers and watch automatic failover: 
# Kill backend on port 8002
pkill -f "8002"

# Check health status
curl http://localhost:8080/health | jq

# Continue sending requests - they'll only go to healthy backends
for i in {1..10}; do curl http://localhost:8080; sleep 0.5; done
Health response will show: 
{
  "status": "degraded",
  "healthy_backends": "2/3",
  "uptime_seconds": 180
}

​
Complete Quickstart Script

Save this as quickstart.sh:
quickstart.sh
#!/bin/bash

echo "UltraBalancer Quickstart"
echo ""

# Check if ultrabalancer is installed
if ! command -v ultrabalancer &> /dev/null; then
    echo "ultrabalancer not found. Installing..."
    curl -LO https://github.com/bas3line/ultrabalancer/releases/latest/download/ultrabalancer-linux-x86_64
    chmod +x ultrabalancer-linux-x86_64
    sudo mv ultrabalancer-linux-x86_64 /usr/local/bin/ultrabalancer
fi

# Start backend servers
echo "Starting backend servers..."

python3 -c "
import http.server
import socketserver
import sys
PORT = int(sys.argv[1])
Handler = http.server.SimpleHTTPRequestHandler
with socketserver.TCPServer(('', PORT), Handler) as httpd:
    print(f'Backend running on {PORT}')
    httpd.serve_forever()
" 8001 &
PID1=$!

python3 -c "
import http.server
import socketserver
import sys
PORT = int(sys.argv[1])
Handler = http.server.SimpleHTTPRequestHandler
with socketserver.TCPServer(('', PORT), Handler) as httpd:
    print(f'Backend running on {PORT}')
    httpd.serve_forever()
" 8002 &
PID2=$!

python3 -c "
import http.server
import socketserver
import sys
PORT = int(sys.argv[1])
Handler = http.server.SimpleHTTPRequestHandler
with socketserver.TCPServer(('', PORT), Handler) as httpd:
    print(f'Backend running on {PORT}')
    httpd.serve_forever()
" 8003 &
PID3=$!

sleep 2

# Start UltraBalancer
echo ""
echo "Starting UltraBalancer..."
ultrabalancer start round-robin 127.0.0.1:8001 127.0.0.1:8002 127.0.0.1:8003 -p 8080 &
ULTRA_PID=$!

sleep 2

# Test
echo ""
echo "Testing load balancer..."
for i in {1..5}; do
    curl -s http://localhost:8080
done

echo ""
echo "Health status:"
curl -s http://localhost:8080/health | jq

# Cleanup function
cleanup() {
    echo ""
    echo "Cleaning up..."
    kill $PID1 $PID2 $PID3 $ULTRA_PID 2>/dev/null
    exit
}

trap cleanup SIGINT SIGTERM

echo ""
echo "Quickstart complete!"
echo "Load balancer running on http://localhost:8080"
echo "Metrics: http://localhost:8080/metrics"
echo "Health: http://localhost:8080/health"
echo ""
echo "Press Ctrl+C to stop all services"

wait
Run it: 
chmod +x quickstart.sh
./quickstart.sh

​
Next Steps

Configuration

Learn about all configuration options

Algorithms

Deep dive into load balancing algorithms

Deploy to Production

Production deployment guides

Load Testing

Benchmark and test your setup

​
Common Commands

# Round Robin (default)
ultrabalancer start round-robin backend1:8080 backend2:8080

# Least Connections
ultrabalancer start least-connections backend1:8080 backend2:8080

# IP Hash (session persistence)
ultrabalancer start ip-hash backend1:8080 backend2:8080

# Weighted Round Robin
ultrabalancer start weighted backend1:8080 backend2:8080 -w 200 -w 100

# Random
ultrabalancer start random backend1:8080 backend2:8080

# Custom listen port
ultrabalancer start round-robin backend1:8080 -p 80

# Custom health check interval (10 seconds)
ultrabalancer start round-robin backend1:8080 --health-check-interval 10000

# Disable health checks
ultrabalancer start round-robin backend1:8080 --no-health-check

# Set max failures before marking backend down
ultrabalancer start round-robin backend1:8080 --health-check-fails 5

# Generate example config
ultrabalancer example > config.yaml

# Start with config file
ultrabalancer -c config.yaml

# Start with TOML config
ultrabalancer -c config.toml

# Validate config without starting
ultrabalancer validate -f config.yaml