Apache BifroMQ Documentation

The base-rpc-grpc-inproc package provides a specialized gRPC client channel implementation called InProcTransport.

This implementation is designed for scenarios where the RPC client and the RPC server reside within the same process. By using InProcTransport instead of standard network-based gRPC transport, you can achieve significantly higher efficiency for in-process communication by bypassing the network stack.

BifroMQ supports two distinct cluster deployment modes depending on your scale and workload requirements:

1. Standard Cluster: Suitable for small to medium production environments. It consists of several fully functional standalone nodes working together as a single logical MQTT broker instance to ensure high availability. While you can scale concurrent MQTT connections by adding nodes, some messaging workloads are not horizontally scalable in this mode.

2. Independent Workload Cluster: Designed for large-scale, multi-tenant serverless clusters. In this mode, the cluster is composed of specialized sub-clusters, each optimized for a specific 'independent type' of workload. These sub-clusters work together to form a single logical MQTT broker instance.

After extracting the apache-bifromq-<VERSION>.tar.gz file, you can manage the server using the scripts in the bin directory.

Directory Structure:

• bin/: Execution scripts
• conf/: Configuration files (e.g., standalone.yml)
• lib/: Libraries
• plugins/: Plugin directory

Commands:

• Start the server (background): ./standalone.sh start
• Stop the server: ./standalone.sh stop

By default, persistent data is stored in the data directory.

Prerequisites

• JDK 17+
• Maven 3.5.0+
• (Optional) OpenSSL (required for native TLS; otherwise falls back to JDK implementation)

Build Steps

1. Clone the repository:

   git clone https://github.com/apache/bifromq bifromq
   cd bifromq

2. Build the project using the Maven wrapper:

   ./mvnw -v
   ./mvnw -U clean verify -DskipTests -Pbuild-release

Build outputs (including .tar.gz archives and sha512 checksums) are located in /target/output.

Use the BifroMQ Plugin Archetype to bootstrap a new plugin project with the required Maven structure and dependencies.

Prerequisites:

• Java JDK 17 or higher
• Maven 3.6.3 or higher

Usage: Run the mvn archetype:generate command, replacing the placeholders with your specific project details. You must provide a pluginName (the main class name) and a pluginContextName (the context class name).

mvn archetype:generate \
    -DarchetypeGroupId=org.apache.bifromq \
    -DarchetypeArtifactId=bifromq-plugin-archetype \
    -DarchetypeVersion=${bifromqVersion} \
    -DgroupId=com.yourcompany.newproject \
    -DartifactId=your-plugin-name \
    -Dversion=1.0.0-SNAPSHOT \
    -DpluginName=YourPluginClassName \
    -DpluginContextName=YourPluginContextClassName \
    -DbifromqVersion=BifroMQVersion \
    -DinteractiveMode=false

By default, BifroMQ bundles netty-tcnative-classes and falls back to JDK TLS if system OpenSSL is missing. To build with specific native TLS implementations, use the following Maven commands:

With system OpenSSL (requires OpenSSL installed on the host):

mvn -Pbuild-release -Pwith-tcnative -Dtcnative.classifier=<your_platform_classifier> clean verify -DskipTests

Example classifiers: linux-x86_64, linux-aarch_64, osx-aarch_64, osx-x86_64, windows-x86_64.

With BoringSSL static bundle:

mvn -Pbuild-release -Pwith-boringssl-static -Dtcnative.classifier=<your_platform_classifier> clean verify -DskipTests

# Example for Linux x86_64 with OpenSSL
mvn -Pbuild-release -Pwith-tcnative -Dtcnative.classifier=linux-x86_64 clean verify -DskipTests

For development and testing, you can build a multi-node cluster on a single host using Docker Compose.

Directory Structure

|- docker-compose.yml
|- node1
|- node2
|- node3

Node Configuration

Each node directory must contain a configuration file (e.g., standalone.yml). The clusterConfig section must be unique to the node's identity and include the seedEndpoints for all nodes in the cluster:

clusterConfig:
  env: "Test"
  host: bifromq-node1 # Change this to bifromq-node2 for node2, etc.
  port: 8899
  seedEndpoints: "bifromq-node1:8899,bifromq-node2:8899,bifromq-node3:8899"

Launching the Cluster

Once your docker-compose.yml and node configurations are prepared, run:

docker compose up -d

You can run a single Apache BifroMQ instance using Docker. It is highly recommended to specify memory limits to prevent the Docker process from being terminated by the host's Out-of-Memory (OOM) Killer.

Use the following command structure, substituting <MEM_LIMIT> (e.g., 2G) and <MEM_LIMIT_IN_BYTES> (e.g., 2147483648) with your desired allocation.

docker run -d -m <MEM_LIMIT> -e MEM_LIMIT='<MEM_LIMIT_IN_BYTES>' --name bifromq -p 1883:1883 apache/bifromq:${TAG}

Use the provided helper script to build a Docker image from the generated .tar.gz archive found in target/output.

Standard build:

./release/docker-build.sh target/output/apache-bifromq-<version>.tar.gz

With custom tag or architecture:

./release/docker-build.sh -t apache-bifromq:<version> target/output/apache-bifromq-<version>.tar.gz
./release/docker-build.sh -a arm64 target/output/apache-bifromq-<version>.tar.gz

To package your plugin into a distributable ZIP file, run the standard Maven package command from the project root.

Steps:

1. Build the project: mvn clean package.
2. Locate the output: The plugin ZIP file will be generated in the target directory.
3. Install: Copy the ZIP file into the BifroMQ plugin folder.
4. Verify: Check the BifroMQ management console or system logs to ensure the plugin loaded correctly.