# hivemq-community-edition

**Repository Path**: expli/hivemq-community-edition

## Basic Information

- **Project Name**: hivemq-community-edition
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-06-04
- **Last Updated**: 2020-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= HiveMQ Community Edition

image:https://www.hivemq.com/img/svg/hivemq-ce.svg[HiveMQ Community,500,align="left"]

image:https://travis-ci.com/hivemq/hivemq-community-edition.svg?token=2JEoSXzFpviQH47MBPSm&branch=master["Build Status",link="https://travis-ci.com/hivemq/hivemq-community-edition"]

HiveMQ CE is a Java-based open source MQTT broker that fully supports MQTT 3.x and MQTT 5.

HiveMQ CE is the foundation of the HiveMQ enterprise-connectivity and messaging platform and implements all MQTT features.
This project is the technical core of many large MQTT deployments and is now available as open source software under the Apache 2 license.

* Web Site: https://www.hivemq.com/
* Documentation: https://github.com/hivemq/hivemq-community-edition/wiki
* Community Forum: https://community.hivemq.com/
* Contribution Guidelines: link:CONTRIBUTING.adoc[Contributing.adoc]
* License: The source files in this repository are made available under the link:LICENSE[Apache License Version 2.0].

= Features

* All MQTT 3.1, 3.1.1 and MQTT 5.0 features
* MQTT over TCP, TLS, WebSocket and Secure WebSocket transport
* Java Extension SDK for:
** Authentication
** Authorization
** Client Initializers
** MQTT Packet Interceptors
** Interacting with Publishes, Retained Messages, Clients and Subscriptions
* Running on Windows, Linux and MacOS (Linux is recommended)
* Embedded Mode

HiveMQ CE is compatible with all MQTT 3 and MQTT 5 clients, including Eclipse Paho and https://github.com/hivemq/hivemq-mqtt-client[HiveMQ MQTT Client].

= Documentation

The documentation for the HiveMQ CE can be found https://github.com/hivemq/hivemq-community-edition/wiki[here].

MQTT Resources

* https://www.hivemq.com/mqtt-essentials/[MQTT Essentials]
* https://www.hivemq.com/mqtt-5/[MQTT 5 Essentials]

= HiveMQ Community Forum

The ideal place for questions or discussions about the HiveMQ Community Edition is our brand new https://community.hivemq.com/[HiveMQ Community Forum].

= How to Use

== Quick Start

* Download the latest https://github.com/hivemq/hivemq-community-edition/releases/download/2020.2/hivemq-ce-2020.2.zip[HiveMQ CE binary package].
* Unzip the package.
* Run the run.sh (Linux/OSX) or run.bat (Windows) in the bin folder of the package.

[source,bash]
----
cd hivemq-ce-<version>
./bin/run.sh
----

You can now connect MQTT clients to `<ip address>:1883`.

[CAUTION]
If you want to connect devices on external networks to HiveMQ CE, please make sure your server is reachable from those networks and the required ports (default: 1883) are accessible through your firewall.

== Just in Time Builds

Just in time builds for current branches on this repository and for specific commits are available https://hivemq.github.io/nightly-builds/[here].

== Run with Docker

All releases as well as the current state of the `master` branch are available in the https://hub.docker.com/r/hivemq/hivemq-ce[hivemq/hivemq-ce] repository on DockerHub.
To execute this image, simply run the following command:

[source,bash]
----
docker run --name hivemq-ce -d -p 1883:1883 hivemq/hivemq-ce
----

To change the default log level you can set the environment variable `HIVEMQ_LOG_LEVEL` when running the container:

[source,bash]
----
docker run --name hivemq-ce -e HIVEMQ_LOG_LEVEL=INFO -d -p 1883:1883 hivemq/hivemq-ce
----

== Building from Source

=== Prerequisites

At least Java version 11 is required to build and run HiveMQ CE.

If you are in doubt, you can check the installed Java version by entering `java -version` on your command line.

=== Building the Binary Package

Check out the git repository and build the binary package.

[source,bash]
----
git clone https://github.com/hivemq/hivemq-community-edition.git

cd hivemq-community-edition

./gradlew clean packaging
----

The package `hivemq-ce-<version>.zip` is created in the sub-folder `build/zip/`.

=== Building the Docker Image

Check out the git repository and build the Docker image.

[source,bash]
----
git clone https://github.com/hivemq/hivemq-community-edition.git

cd hivemq-community-edition

docker/build.sh

docker run hivemq/hivemq-ce
----

The Docker image `hivemq/hivemq-ce` is created locally.

You can tag the image or use the `TARGET_IMAGE` environment variable to manipulate the image name.

=== Start

Unzip the created binary package

[source,bash]
----
cd hivemq-ce-<version>

./bin/run.sh
----

For further development instructions see the link:CONTRIBUTING.adoc[contribution guidelines].

== Embedded Mode

HiveMQ Community Edition offers an embedded mode and a programmatic API for integrating with Java/Java EE software.

=== Dependency

IMPORTANT: Until HiveMQ Community Edition 2020.3 is released embedded mode is only available from link:https://jitpack.io/#hivemq/hivemq-community-edition[jitpack.io].

==== Gradle

If you use Gradle, include the following code in your `build.gradle` file.

[source,groovy]
----
repositories {
    ...
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.hivemq.hivemq-community-edition:hivemq-community-edition-embedded:master-SNAPSHOT'
}
----

==== Maven

If you use Maven, include the following code in your `pom.xml` file.

[source,xml]
----
<project>
    ...
    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <dependencies>
    <dependency>
        <groupId>com.github.hivemq.hivemq-community-edition</groupId>
        <artifactId>hivemq-community-edition-embedded</artifactId>
        <version>master-SNAPSHOT</version>
    </dependency>
    </dependencies>
    ...
</project>
----

NOTE: You must set the compiler version to `11` or higher.

=== Usage

Entry into the embedded mode is done with the `com.hivemq.embedded.EmbeddedHiveMQBuilder`.

[source,java]
----
public class Main {

    public static void main(String[] args) {

        final EmbeddedHiveMQBuilder embeddedHiveMQBuilder = EmbeddedHiveMQBuilder.builder()
            .withConfigurationFolder(Path.of("/path/to/embedded-config-folder"))
            .withDataFolder(Path.of("/path/to/embedded-data-folder"))
            .withExtensionsFolder(Path.of("/path/to/embedded-extensions-folder"));
        ...
    }
}
----

Once built, an EmbeddedHiveMQ can be started with `start()`.

[source,java]
----
public class Main {

    public static void main(String[] args) {
        final EmbeddedHiveMQBuilder embeddedHiveMQBuilder = EmbeddedHiveMQBuilder.builder()
        ...;

        try (final EmbeddedHiveMQ hiveMQ = embeddedHiveMQBuilder.build()) {
            hiveMQ.start().join();
            ...
        } catch (final Exception ex) {
            ex.printStackTrace();
        }
    }
}
----

A running EmbeddedHiveMQ can be stopped with `stop()`.

[source,java]
----
public class Main {

    public static void main(String[] args) {

        ...

        try (final EmbeddedHiveMQ hiveMQ = embeddedHiveMQBuilder.build()) {
            ...
            hiveMQ.stop().join();
        } catch (final Exception ex) {
            ex.printStackTrace();
        }
    }
}
----

NOTE: An EmbeddedHiveMQ is a resource that is similar to a e.g. network connection and implements the `java.lang.AutoCloseable` interface.
Always use ARM (_try with resources_) or ensure a call to `close()`.

=== Exclusions

When you deploy an application that includes EmbeddedHiveMQ, it can be useful to exclude some dependencies.
One way to exclude dependencies is with the  link:https://maven.apache.org/plugins/maven-shade-plugin/[maven shade plugin].

[source,xml]
----
<project>
...
 <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.2.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <artifactSet>
                                <excludes>
                                    <!--Exclude the undesired dependencies-->
                                    <exclude>org.rocksdb:rocksdbjni</exclude>
                                    <exclude>ch.qos.logback:logback-classic</exclude>
                                </excludes>
                            </artifactSet>
                            <filters>
                                <filter>
                                    <artifact>*:*</artifact>
                                    <excludes>
                                        <exclude>META-INF/*.SF</exclude>
                                        <exclude>META-INF/*.DSA</exclude>
                                        <exclude>META-INF/*.RSA</exclude>
                                    </excludes>
                                </filter>
                            </filters>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
...
</project>
----

==== RocksDB Exclusion

To exclude the `org.rocksdb:rocksdbjni` dependency, two internal configurations must be changed before you call `start()`.

[source,java]
----
public class Main {

    public static void main(String[] args) {

        ...

        try (final EmbeddedHiveMQ hiveMQ = embeddedHiveMQBuilder.build()) {

            InternalConfigurations.PAYLOAD_PERSISTENCE_TYPE.set(PersistenceType.FILE);
            InternalConfigurations.RETAINED_MESSAGE_PERSISTENCE_TYPE.set(PersistenceType.FILE);

            hiveMQ.start().join();

            ...
        } catch (final Exception ex) {
            ex.printStackTrace();
        }
    }
}
----

= Contributing

If you want to contribute to HiveMQ CE, see the link:CONTRIBUTING.adoc[contribution guidelines].

= License

HiveMQ Community Edition is licensed under the `APACHE LICENSE, VERSION 2.0`.
A copy of the license can be found link:LICENSE[here].