| name | heliosproxy-install |
| description | Install HeliosProxy from crates.io or build from source. Pick feature flags. Verify with `--version`. Use when the user says "install heliosproxy", "set up the proxy", "cargo install heliosdb-proxy", or hits a "command not found" on `heliosdb-proxy`. |
| allowed-tools | Bash(cargo *), Bash(rustc *), Bash(heliosdb-proxy *), Bash(which *), Read |
| related | ["heliosproxy-overview","heliosproxy-start","heliosproxy-config"] |
Install HeliosProxy
Two paths: install the published binary from crates.io, or clone
the repo and cargo build for development. Default features are
minimal; opt in to feature flags explicitly.
When to use
- Fresh machine: no
heliosdb-proxy on $PATH
- Need a specific build (TLS, plugins, edge proxy, etc.) compiled in
- Reproducing an issue from a specific version
- Working on the proxy itself (developer install)
🔵 Read-only on the system; reversible (cargo uninstall heliosdb-proxy)
Surfaces
| Surface | When to use |
|---|
cargo install heliosdb-proxy | Production / operator install — pulls from crates.io |
cargo install --git github.com/HeliosDatabase/HeliosDB-Proxy | Pre-release / unreleased commit |
git clone … && cargo build --release | Developer install with --features matrix |
ghcr.io/heliosdatabase/hdb-heliosdb-proxy:0.6.1 | Container deploy (Docker/K8s) |
Recipes
Recipe 1: Install latest from crates.io (default features)
cargo install heliosdb-proxy
heliosdb-proxy --version
Default features: pool-modes only. For more, see Recipe 3.
Requires Rust 1.75+ (MSRV). Check with rustc --version. If older,
install Rust via rustup first.
Recipe 2: Install a specific version
cargo install heliosdb-proxy --version 0.4.1
Or pin in Cargo.toml as a library dep:
[dependencies]
heliosdb-proxy = "0.4.1"
Recipe 3: Install with all features
cargo install heliosdb-proxy --features all-features
all-features turns on every proxy feature (HA-TR, plugins, anomaly,
edge, multi-tenancy, etc.). Topology providers are exclusive — pass
exactly one of --features postgres-topology or
--features heliosdb-topology separately:
cargo install heliosdb-proxy --features "all-features postgres-topology"
See _index/feature-matrix.md for
which feature unlocks which skill.
Recipe 4: Developer install from source
git clone git@github.com:HeliosDatabase/HeliosDB-Proxy.git
cd HDB-HeliosDB-Proxy
cargo build --release --features all-features
./target/release/heliosdb-proxy --version
For a faster compile during iteration, drop --release:
cargo build --features wasm-plugins,ha-tr,anomaly-detection
./target/debug/heliosdb-proxy --version
Recipe 5: Docker image
docker pull ghcr.io/heliosdatabase/hdb-heliosdb-proxy:0.6.1
docker run --rm ghcr.io/heliosdatabase/hdb-heliosdb-proxy:0.6.1 --version
The image is published by .github/workflows/docker.yml on every
tag push. For a custom-features image, git clone and build locally:
docker build -t my-heliosproxy:dev -f docker/Dockerfile .
Recipe 6: Verify the install end-to-end
heliosdb-proxy --help
heliosdb-proxy --version
which heliosdb-proxy
ls $(dirname $(which heliosdb-proxy))
Pitfalls
error: failed to compile heliosdb-proxy v0.4.1, intermediate artifacts can be found at … — usually MSRV. Confirm
rustc --version is ≥ 1.75. Install via rustup default stable.linker 'cc' not found — install build-essential
(apt install build-essential / xcode-select --install).error: failed to download / network errors during install —
check ~/.cargo/config.toml for proxy / mirror; if behind a
firewall, use cargo install --offline against a vendored copy.--features wasm-plugins adds ~3 MB compiled (wasmtime
cranelift JIT). Default off so minimal installs stay tiny. Add
it only if you'll load WASM plugins.postgres-topology and heliosdb-topology are mutually
exclusive. cargo won't error if you enable both at build
time, but at runtime the topology provider that wins is undefined.
Pick one.- AGPL → Apache-2.0 in v0.4.0+. If you cloned an old branch or
pinned a pre-0.4.0 release, the LICENSE file differs.
See also
