Skip to main content

Native install (pip / uv)

EasyHAProxy can run directly on any Linux or macOS host without Docker, using the easyhaproxy Python package. HAProxy is installed on the host; EasyHAProxy manages it.

Prerequisites​

HAProxy must be installed and available in your system PATH before running easy-haproxy.

sudo apt install haproxy

Installation​

uv installs easyhaproxy into its own isolated environment and exposes the easy-haproxy binary in ~/.local/bin/.

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install easyhaproxy as a tool
uv tool install easyhaproxy

# Make sure ~/.local/bin is in PATH (one-time setup)
uv tool update-shell

Alternative: pip​

pip install easyhaproxy
Virtual environments

When installing inside a virtual environment, easy-haproxy is only available while the environment is activated. For system-wide use, prefer uv tool install.

Quick start​

Static mode (bare-metal / VM)​

mkdir -p ~/easyhaproxy/static

cat > ~/easyhaproxy/static/config.yml <<EOF
containers:
  "myapp.example.com:80":
    ip: ["127.0.0.1:3000"]
EOF

easy-haproxy --discover static

Docker mode​

easy-haproxy --discover docker

Kubernetes mode​

easy-haproxy --discover kubernetes

Running as a systemd service​

/etc/systemd/system/easy-haproxy.service
[Unit]
Description=EasyHAProxy
After=network.target

[Service]
ExecStart=/usr/local/bin/easy-haproxy --discover static --haproxy-password mysecret
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now easy-haproxy
Adjust ExecStart path

Run which easy-haproxy to get the correct binary path. If installed with uv tool, it is typically /root/.local/bin/easy-haproxy when running as root.

Full options​

Open source ByJG