Skip to main content

Get Started

This guide starts a single YedMQ node from source.

caution

YedMQ is under active development and is not yet recommended for production workloads.

Prerequisites​

  • Rust 1.75 or newer
  • protoc
  • OpenSSL development headers (libssl-dev on Ubuntu/Debian)
  • Optional: mosquitto_pub and mosquitto_sub for quick verification

On Ubuntu/Debian, you can install the common system dependencies with:

sudo apt-get update
sudo apt-get install -y protobuf-compiler pkg-config libssl-dev

On Windows, install these build dependencies before running cargo build:

  • protoc
  • LLVM/Clang

Some native dependencies in this workspace rely on Clang being discoverable during the build. In PowerShell, a typical setup looks like:

$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
$env:PATH = "$env:LIBCLANG_PATH;$env:PATH"

If your protoc.exe directory is not already on PATH, add it before building.

1. Clone and build​

git clone https://github.com/designershao/YedMQ.git
cd YedMQ
cargo build --release -p yedmq

2. Create a local config file​

cp yedmq.toml.example yedmq.toml

Review the listener, API auth, cluster, and plugin settings before starting the broker.

The shipped example file is intentionally locked down:

  • MQTT client access is deny-by-default unless an auth or ACL plugin approves the request
  • the management API binds to 127.0.0.1
  • no management API users are created automatically

For a local smoke test without any auth plugin, temporarily change this block:

[plugin]
default_authorize_result = true
default_authenticate_result = true

Use that fallback only on a local machine. For shared or production environments, keep the defaults locked down and install a real authentication or ACL plugin instead. The repository also ships a bundled acl_file example plugin under example_plugins/acl_file.

3. Start the broker​

RUST_LOG=info ./target/release/yedmq

YedMQ loads ./yedmq.toml from the current working directory, so run the binary from the project root unless you wrap startup with your own config-loading logic.

4. Verify MQTT connectivity​

Run this step after enabling the temporary local fallback above or after installing an auth plugin.

Open one terminal:

mosquitto_sub -h 127.0.0.1 -p 1883 -t test/topic

Open another terminal:

mosquitto_pub -h 127.0.0.1 -p 1883 -t test/topic -m "hello yedmq"

5. Verify the management API​

The example config does not create any REST API users by default. Add at least one user first:

[listener.api.auth]
users = [{ username = "admin", password = "replace_me" }]

Then call the API:

curl -u admin:replace_me http://127.0.0.1:3456/api/v1/system_info

Next steps​