Skip to main content
Build HiveMQ Community Edition from source to access the latest features, contribute to development, or customize the build process.

​
Prerequisites

Java 21 is required to build and test HiveMQ, even though Java 11 is sufficient to run it.

​
Required Tools

  • Java Development Kit (JDK) 21: Download from Eclipse Temurin
  • Git: For cloning the repository
  • Gradle: Included via Gradle Wrapper (gradlew)
Verify your Java installation: 
java -version
Expected output: 
openjdk version "21.0.x" 2024-xx-xx

​
Clone the Repository

Clone the HiveMQ Community Edition repository from GitHub: 
git clone https://github.com/hivemq/hivemq-community-edition.git
cd hivemq-community-edition

​
Build Targets

HiveMQ uses Gradle as its build system. The project includes several build targets for different outputs.

​
Build the Binary Package

Create a distributable ZIP package: 
./gradlew hivemqZip
Output: build/distributions/hivemq-ce-<version>.zip This creates a complete HiveMQ distribution including:
  • Executable JAR (hivemq.jar)
  • Startup scripts (run.sh, run.bat)
  • Configuration files
  • Directory structure
  • Software Bill of Materials (SBOM)

​
Extract and Run

After building, extract and run HiveMQ: 
cd build/distributions
unzip hivemq-ce-*.zip
cd hivemq-ce-*/
./bin/run.sh

​
Build the Docker Image

Build a local Docker image: 
./gradlew loadOciImage
Output: Docker image hivemq/hivemq-ce:snapshot Run the locally built image: 
docker run --name hivemq-ce -d -p 1883:1883 hivemq/hivemq-ce:snapshot

​
Other Build Tasks

​
Compile Sources

Compile the Java sources without creating a distribution: 
./gradlew compileJava
HiveMQ compiles to Java 11 bytecode for runtime compatibility, even though the build requires Java 21.

​
Build JAR File

Create the HiveMQ JAR: 
./gradlew shadowJar
Output: build/libs/hivemq-community-edition-<version>-all.jar The shadow JAR includes all dependencies merged into a single executable JAR.

​
Run Tests

Execute the test suite: 
./gradlew test
Test requirements:
  • Minimum heap: 128m
  • Maximum heap: 2048m
  • Special JVM flags for module access
View test results at build/reports/tests/test/index.html

​
Generate Javadoc

Generate API documentation: 
./gradlew javadoc
Output: build/docs/javadoc/

​
Code Quality Checks

Run code formatting and quality checks: 
# Check code formatting
./gradlew spotlessCheck

# Apply code formatting
./gradlew spotlessApply

# Run forbidden API checks
./gradlew forbiddenApisMain

# Generate code coverage report
./gradlew test jacocoTestReport
Coverage report: build/reports/jacoco/test/html/index.html

​
Build Configuration

​
Project Information

  • Group: com.hivemq
  • Artifact ID: hivemq-community-edition
  • License: Apache 2.0
  • Main Class: com.hivemq.HiveMQServer

​
Java Toolchain

The build uses a sophisticated toolchain setup: 
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)  // Build requires Java 21
    }
}

tasks.compileJava {
    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(11)  // Compile to Java 11 bytecode
    }
}

​
Key Dependencies

  • Netty (buffer, codec, handler, transport)
  • High-performance async I/O framework
  • RocksDB: High-performance embedded database
  • Xodus: Transactional schema-less embedded database
  • Bouncy Castle (provider, PKIX)
  • Cryptography and TLS support
  • SLF4J API
  • Logback Classic
  • JUL to SLF4J bridge
  • Dropwizard Metrics (core, JMX, Logback)
  • OSHI (system and hardware information)
  • Google Guice
  • JSR-330 (javax.inject)

​
Gradle Wrapper

The project includes Gradle Wrapper for consistent builds: 
# Linux/macOS
./gradlew <task>

# Windows
gradlew.bat <task>
Always use the Gradle Wrapper (./gradlew) instead of a system-installed Gradle to ensure version compatibility.

​
Common Build Tasks

# Clean build artifacts
./gradlew clean

# Full build with tests
./gradlew build

# Build without tests
./gradlew assemble

# List all available tasks
./gradlew tasks

# View task dependencies
./gradlew tasks --all

​
Continuous Integration

The project uses GitHub Actions for CI/CD. See .github/workflows/check.yml for the complete workflow.

​
Publishing

​
Maven Publications

Two artifacts are published:
  1. Distribution: hivemq-community-edition (ZIP package)
  2. Embedded: hivemq-community-edition-embedded (JAR for embedded use)
# Publish to local Maven repository
./gradlew publishToMavenLocal

​
Signing

Artifacts are signed with PGP: 
# Disable signing (development)
./gradlew publish -PsigningDisabled=true

​
Development Workflow

1

Clone and checkout a branch

git clone https://github.com/hivemq/hivemq-community-edition.git
cd hivemq-community-edition
git checkout -b feature/my-feature
2

Make your changes

Edit source files in src/main/java/
3

Format code

./gradlew spotlessApply
4

Run tests

./gradlew test
5

Build and verify

./gradlew hivemqZip
6

Commit and push

git add .
git commit -m "Description of changes"
git push origin feature/my-feature

​
Troubleshooting

​
Build Fails with Java Version Error

Problem: Unsupported class file major version Solution: Ensure you’re using Java 21 for building: 
export JAVA_HOME=/path/to/java-21
./gradlew clean build

​
Out of Memory During Build

Problem: OutOfMemoryError during compilation or tests Solution: Increase Gradle JVM memory: 
export GRADLE_OPTS="-Xmx4g"
./gradlew build
Or add to gradle.properties: 
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m

​
Test Failures

Problem: Specific tests fail on your system Solution: Use test inclusion/exclusion files: 
# Create exclusions.txt with test patterns to exclude
echo "**/FailingTest.class" > exclusions.txt
./gradlew test

​
Next Steps

Contributing

Read the contribution guidelines

Binary Deployment

Deploy the built package

Extension Development

Develop custom extensions

Testing

Write and run tests

Build docs developers (and LLMs) love

Get started for freeTalk to us