This is an automated email from the ASF dual-hosted git repository.
popduke pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
The following commit(s) were added to refs/heads/master by this push:
new 85c5f84f 1. changes for first incubating release. (#29)
85c5f84f is described below
commit 85c5f84f24ce88daa5e33c7c66c7166f09da98b5
Author: Gu Jiawei <[email protected]>
AuthorDate: Tue Dec 2 13:13:24 2025 +0800
1. changes for first incubating release. (#29)
---
docs/cluster/standardcluster.md | 4 +--
docs/cluster/upgrade.md | 8 +++++
docs/installation/docker.md | 76 +++++++++++++++++++++++++++++++++++++----
3 files changed, 79 insertions(+), 9 deletions(-)
diff --git a/docs/cluster/standardcluster.md b/docs/cluster/standardcluster.md
index 820b2e41..8a90466d 100644
--- a/docs/cluster/standardcluster.md
+++ b/docs/cluster/standardcluster.md
@@ -39,14 +39,12 @@ For detailed configuration information, refer to the
BifroMQ Configuration [Docu
### Start Node
-Run following command to start standalone node:
+Run the following command to start standalone node:
```shell
./bin/standalone.sh start
```
-It's suggested to start the 'bootstrap' node first.
-
### Cluster Status Check
After running the script, the nodes will form a cluster and generate the
`AgentHost joined seedEndpoint: ${seedEndpoints}` logs on their respective
machines.
diff --git a/docs/cluster/upgrade.md b/docs/cluster/upgrade.md
index 2b8f6f66..5d22c06b 100644
--- a/docs/cluster/upgrade.md
+++ b/docs/cluster/upgrade.md
@@ -42,6 +42,14 @@ BifroMQ supports two rolling upgrade methods:
1. **In-Place Upgrade**
2. **Replace Upgrade**
+### Prerequisite
+
+Apache BifroMQ **4.0.0-incubating introduces breaking changes** and is **not
backward compatible** with earlier versions. In particular, several **plugin
interfaces have been updated**.
+If you are using any **custom plugins**, you must:
+
+1. **Update your plugin code** to use the latest interfaces, and
+2. **Rebuild** your plugins against the new version of BifroMQ before
upgrading.
+
### In-Place Upgrade
This method is suitable when the new version maintains both data compatibility
and inter-cluster RPC protocol compatibility with the existing version.
diff --git a/docs/installation/docker.md b/docs/installation/docker.md
index 0de22d83..659b692d 100644
--- a/docs/installation/docker.md
+++ b/docs/installation/docker.md
@@ -6,26 +6,26 @@ title: "Docker"
## Prerequisites
* [Docker](https://www.docker.com/) is installed.
-* You have permission to use port 1883, and the port are available. If you do
not have permission, please change to the corresponding port.
+* You have permission to use port 1883, and the port is available. If you do
not have permission, please change to the corresponding port.
## Docker Command
-Run the following command, which will run BifroMQ within a container as the
Linux user `bifromq`.
+Run the following command, which will run Apache BifroMQ within a container as
the Linux user `bifromq`.
```
-docker run -d --name bifromq -p 1883:1883 bifromq/bifromq:latest
+docker run -d --name bifromq -p 1883:1883 apache/bifromq:4.0.0-incubating
```
## Memory Constraints
-By default, upon BifroMQ process initiation, it dynamically computes the
relevant JVM parameters based on the physical memory of the hosting server.
However, when launched within a containerized environment, it introspects the
host
+By default, upon Apache BifroMQ process initiation, it dynamically computes
the relevant JVM parameters based on the physical memory of the hosting server.
However, when launched within a containerized environment, it introspects the
host
machine's physical memory, potentially causing conflicts with Docker or
container-imposed memory constraints, consequently leading to the premature
termination of the container.
To circumvent such challenges, it is advisable to proactively delimit the
container's memory consumption and convey these limitations to the container
runtime via environmental variables. During the startup of BifroMQ, priority is
given to
the calculation of JVM parameters based on the `MEM_LIMIT` environmental
variable. A specific illustration is provided below:
```
-docker run -d -m 10G -e MEM_LIMIT='10737418240' --name bifromq -p 1883:1883
bifromq/bifromq:latest
+docker run -d -m 10G -e MEM_LIMIT='10737418240' --name bifromq -p 1883:1883
apache/bifromq:4.0.0-incubating
```
***Note: The unit of MEM_LIMIT is in bytes.***
@@ -33,6 +33,70 @@ docker run -d -m 10G -e MEM_LIMIT='10737418240' --name
bifromq -p 1883:1883 bifr
Going a step further, it is possible to proactively configure the JVM heap
memory and directly transmit it to the container runtime for utilization by
BifroMQ. A specific illustration is provided below:
```
-docker run -d -m 10G -e JVM_HEAP_OPTS='-Xms2G -Xmx4G -XX:MetaspaceSize=128m
-XX:MaxMetaspaceSize=500m -XX:MaxDirectMemorySize=1G' --name bifromq -p
1883:1883 bifromq/bifromq:latest
+docker run -d -m 10G -e JVM_HEAP_OPTS='-Xms2G -Xmx4G -XX:MetaspaceSize=128m
-XX:MaxMetaspaceSize=500m -XX:MaxDirectMemorySize=1G' --name bifromq -p
1883:1883 apache/bifromq:4.0.0-incubating
+```
+
+You can build an Apache BifroMQ cluster using Docker Compose on a single host
for development and testing. Suppose you want to create a cluster with three
nodes: node1,
+node2, and node3. The directory structure should be as follows:
+```
+|- docker-compose.yml
+|- node1
+|- node2
+|- node3
+```
+Each node should have a configuration file, it is defined as follows:
+```yml
+clusterConfig:
+ env: "Test"
+ host: bifromq-node1 # Change this to bifromq-node2 for node2 and
bifromq-node3 for node3
+ port: 8899
+ seedEndpoints: "bifromq-node1:8899,bifromq-node2:8899,bifromq-node3:8899"
+```
+The `docker-compose.yml` file defines the services for the three nodes:
+```yml
+services:
+ bifromq-node1:
+ image: apache/bifromq:4.0.0-incubating
+ container_name: bifromq-node1
+ volumes:
+ - ./node1/standalone.yml:/home/bifromq/conf/standalone.yml
+ ports:
+ - "1883:1883"
+ environment:
+ - MEM_LIMIT=10737418240 # Adjust the value according to the actual host
configuration.
+ networks:
+ - bifromq-net
+
+ bifromq-node2:
+ image: apache/bifromq:4.0.0-incubating
+ container_name: bifromq-node2
+ volumes:
+ - ./node2/standalone.yml:/home/bifromq/conf/standalone.yml
+ ports:
+ - "1884:1883"
+ environment:
+ - MEM_LIMIT=2147483648
+ networks:
+ - bifromq-net
+
+ bifromq-node3:
+ image: apache/bifromq:4.0.0-incubating
+ container_name: bifromq-node3
+ volumes:
+ - ./node3/standalone.yml:/home/bifromq/conf/standalone.yml
+ ports:
+ - "1885:1883"
+ environment:
+ - MEM_LIMIT=2147483648
+ networks:
+ - bifromq-net
+
+networks:
+ bifromq-net:
+ driver: bridge
+```
+To launch the cluster, run the following command:
+```shell
+docker compose up -d
```
