Eloq Waiter contains tools for developing and operating EloqData components outside Kubernetes.

The active cluster manager product target is EloqKV. Legacy EloqSQL, MonoSQL, Codis, and MySQL exporter deployment paths have been removed.

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/eloqdata/eloq_waiter/main/install.sh | sh

Install a specific release tag:

curl -fsSL https://raw.githubusercontent.com/eloqdata/eloq_waiter/main/install.sh | sh -s -- v1.8.1

For local development, build and install the current checkout:

scripts/install-dev.sh

This installs ${ELOQCTL_HOME:-$HOME/.eloqctl}/bin/eloqctl and links ${ELOQCTL_HOME:-$HOME/.eloqctl}/config to src/cluster_mgr/config in this repository. For upgrade compatibility, a legacy ${ELOQCTL_HOME:-$HOME/.eloqctl}/bin/cluster_mgr link is also retained.

When the installer detects an existing eloqctl state directory, it also runs eloqctl upgrade automatically to migrate local cluster metadata.

Before using eloqctl against a fresh machine, bootstrap every target host first:

curl -fsSL https://raw.githubusercontent.com/eloqdata/eloq_waiter/main/scripts/setup-host.sh | sudo bash

Then copy the control-machine public key to each target host:

ssh-copy-id -i ~/.ssh/id_rsa.pub eloq@<target-host>

The website prerequisite guide explains what the setup script configures and how to verify the machine state.

For deployment field meanings and example YAML shapes, see the EloqKV website docs: Deployment YAML Reference and Deploy High Availability Cluster with MinIO.

Launch an EloqKV cluster from a topology file:

eloqctl launch /path/to/topology.yaml

For a local single-node trial after installation, start from the bundled example:

cp "${ELOQCTL_HOME:-$HOME/.eloqctl}/config/examples/eloqctl_single_node_localhost.yaml" ./eloqkv-local-demo.yaml
eloqctl launch ./eloqkv-local-demo.yaml
eloqctl status eloqkv-local-demo --wait 60

This example targets 127.0.0.1, stores files under ${ELOQCTL_HOME:-$HOME/.eloqctl}/demo/eloqkv-local-demo, and assumes the current user can SSH to localhost with the key configured in the YAML file.

Check live status by cluster name. status does not require the YAML file; it uses the local cluster index to find the saved topology and then probes the real hosts:

eloqctl status eloqkv-cluster --wait 60

Get a client command:

CLIENT=$(eloqctl -q connect eloqkv-cluster)
eval "$CLIENT" ping

Preview and apply supported declarative changes:

eloqctl plan /path/to/topology.yaml
eloqctl apply /path/to/topology.yaml

Export the saved launch-compatible topology:

eloqctl export eloqkv-cluster --output eloqkv-cluster.yaml

Stop and remove a cluster through eloqctl:

eloqctl stop eloqkv-cluster --all --force
eloqctl remove eloqkv-cluster --force

eloqctl separates desired and observed state:

1. Desired topology is stored as YAML under ${ELOQCTL_HOME:-$HOME/.eloqctl}/clusters/<cluster>/topology.yaml and can be exported with eloqctl export.
2. SQLite stores only local operational metadata such as the cluster index, locks, operation history, and backup metadata.
3. Runtime health is always observed live from the hosts and EloqKV endpoints. SQLite task history is not treated as proof that a service is running.

Install Rust and the system build dependencies first. On Ubuntu:

sudo apt install build-essential pkg-config libssl-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build the eloqctl binary:

cargo build -p cluster_mgr --bin eloqctl
cargo build -p cluster_mgr --bin eloqctl --release

Useful local commands:

cargo fmt --all -- --check
cargo check -p cluster_mgr --bin eloqctl
scripts/install-dev.sh
scripts/test-before-push.sh
scripts/install-git-hooks.sh

The local push gate is scripts/test-before-push.sh. It performs:

1. Local dev install of eloqctl.
2. Rust formatting check.
3. cargo check -p cluster_mgr --bin eloqctl.
4. cargo clippy --all-targets --all-features -- -D warnings.

Full Docker E2E coverage runs in GitHub Actions rather than in the local pre-push script.

The gate uses the Rust nightly toolchain specified in rust-toolchain.toml. Ensure the clippy component is installed:

rustup component add clippy

Install the pre-push hook with:

scripts/install-git-hooks.sh

The Docker E2E tests keep eloqctl on the host and use Ubuntu containers only as SSH-accessible target nodes. Runtime dependencies are installed by eloqctl run-deps/launch, not baked into the test image.

1. eloqctl commands: doc/eloqctl.md
2. Declarative reconcile model: doc/declarative_reconcile.md
3. Idempotency guarantees: doc/idempotency.md
4. Backup and dump tools: doc/backup_and_dump_tools.md
5. Docker E2E tests: tests/README.md
6. Developer helper commands: doc/devtools_cmd.md