2.7 KiB
| sidebar_position | sidebar_label |
|---|---|
| 5 | Native (pip/uv) |
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.
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
sudo apt install haproxy
sudo dnf install haproxy
brew install haproxy
Installation
Recommended: uv tool (system-wide, isolated)
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
:::note 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
[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
:::tip 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
- CLI Reference — all flags and environment variables
- ACME / Let's Encrypt — automatic certificate issuing
- Plugins — extend functionality