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 start -c yedmq.toml

Running ./target/release/yedmq without a subcommand is still supported and starts the broker with the default configuration search path. Use start -c <path> when you want startup to load a specific config file.

You can validate the config before starting any listeners or plugin processes:

./target/release/yedmq config check -c yedmq.toml

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

The same credentials can be used by the built-in CLI status commands:

export YEDMQ_API_USER=admin
export YEDMQ_API_PASSWORD=replace_me

./target/release/yedmq node status
./target/release/yedmq cluster status
./target/release/yedmq broker stats

For scripts, prefer --password-stdin when you do not want the password to appear in shell history or process arguments:

printf '%s' 'replace_me' | \
  ./target/release/yedmq cluster status --user admin --password-stdin

Next steps​