Quick Start Example

This example sets up Meridian to proxy HTTP traffic to two backend servers with round-robin load balancing.

1. Create the Configuration

Save as quickstart.toml:

[[listeners]]
name = "http"
address = "0.0.0.0:8181"
filter_chain = []

[[clusters]]
name = "my-backends"
lb_policy = "round_robin"
connect_timeout_ms = 5000
endpoints = [
  { address = "127.0.0.1:9001", weight = 1 },
  { address = "127.0.0.1:9002", weight = 1 },
]

[[routes]]
prefix = "/"
cluster = "my-backends"

2. Start Backend Servers

For testing, use Python’s built-in HTTP server:

# Terminal 1: backend on port 9001
mkdir -p /tmp/backend1 && echo "Backend 1" > /tmp/backend1/index.html
cd /tmp/backend1 && python3 -m http.server 9001

# Terminal 2: backend on port 9002
mkdir -p /tmp/backend2 && echo "Backend 2" > /tmp/backend2/index.html
cd /tmp/backend2 && python3 -m http.server 9002

3. Start Meridian

# Terminal 3
cargo run -p meridian-proxy -- quickstart.toml

4. Send Traffic

# Requests alternate between backends (round-robin)
curl http://localhost:8181/
# => Backend 1

curl http://localhost:8181/
# => Backend 2

curl http://localhost:8181/
# => Backend 1

5. Add TLS

To enable TLS termination, add a TLS section to the listener:

[[listeners]]
name = "https"
address = "0.0.0.0:8443"
filter_chain = []

[listeners.tls]
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"

Clients connect via HTTPS; Meridian forwards to backends over plain HTTP.

6. Add Health Checking

[[clusters]]
name = "my-backends"
lb_policy = "round_robin"
connect_timeout_ms = 5000
endpoints = [
  { address = "127.0.0.1:9001", weight = 1 },
  { address = "127.0.0.1:9002", weight = 1 },
]

[clusters.health_check]
interval_ms = 5000
timeout_ms = 2000
healthy_threshold = 2
unhealthy_threshold = 3
http_path = "/"

Meridian probes each endpoint every 5 seconds. If an endpoint fails 3 consecutive checks, it’s removed from the load balancer rotation.

Keyboard shortcuts