Installing HiveMQ

General installation information

HiveMQ CE can be packaged into a zip file, which contains the executables, init scripts and sample configurations.

The zip contains the following directories:

Folder name	Description
bin	The folder with start scripts and binary files.
conf	The folder with the configurations.
data	Persistent client data and cluster data are located here.
log	All log files can be found here.
extensions	The folder where extensions reside.
third-party-licenses	Information about the licenses of third party libraries can be found here.

Note	Example configurations HiveMQ comes with many example configuration files in the conf/examples directory.

Installation on Unix based systems (Linux, BSD, MacOS X, Unix)

The default installation directory is /opt/hivemq and the default user to run HiveMQ is named hivemq. If you need to install HiveMQ to a custom directory or run it under a custom user please be aware of changing the $HIVEMQ_DIRECTORY and/or the HIVEMQ_USER in the $HIVEMQ_DIRECTORY/bin/start.sh script.

1. Login as root

   Some of the following commands need root privileges, please login as root or use sudo to execute the commands.

2. Check out the git repository and build the binary package.

   git clone https://github.com/hivemq/hivemq-community-edition.git
   
   cd hivemq-community-edition
   
   ./gradlew clean hivemqZip

3. Go to the folder containing the zip file

   cd build/distributions/

4. Extract the files

   unzip hivemq-ce-<version>.zip

5. Create hivemq symlink

   ln -s /opt/hivemq-ce-<version> /opt/hivemq

6. Create HiveMQ user

   useradd -d /opt/hivemq hivemq

7. Make scripts executable and change owner to hivemq user

   chown -R hivemq:hivemq /opt/hivemq-ce-<version>
   chown -R hivemq:hivemq /opt/hivemq
   cd /opt/hivemq
   chmod +x ./bin/run.sh

8. Adjust the configuration properties to your needs.

   See chapter Configuration for detailed instructions how to configure HiveMQ.

9. Install the init script (optional)

   For Debian-based linux like Debian, Ubuntu, Raspbian using init.d scripts

   cp /opt/hivemq/bin/init-script/hivemq-debian /etc/init.d/hivemq
   chmod +x /etc/init.d/hivemq

   For linux systems using systemd

   cp /opt/hivemq/bin/init-script/hivemq.service /etc/systemd/system/hivemq.service

   For all other linux systems

   cp /opt/hivemq/bin/init-script/hivemq /etc/init.d/hivemq
   chmod +x /etc/init.d/hivemq

10. Modify /etc/init.d/hivemq (optional)

    Set the HIVEMQ_HOME and the HIVEMQ_USER variable to the correct values for your system.

    By default this would be:

    HIVEMQ_HOME=/opt/hivemq

    HIVEMQ_USER=hivemq

    If you installed HiveMQ to a different directory than /opt/hivemq please point the HIVEMQ_HOME in your init script to the correct directory. Otherwise the daemon will not start correctly.

11. Start HiveMQ on boot (optional)

    For Debian-based linux like Debian, Ubuntu, Raspbian

    update-rc.d hivemq defaults

    For Debian-based linux like Debian, Ubuntu, Raspbian using systemd

    systemctl enable hivemq

    Debian > 6.0

    insserv hivemq

    CentOS or RHEL

    chkconfig hivemq on

Starting HiveMQ

The following instructions show how to start HiveMQ after the installation.

Starting manually

1. Change directory to HiveMQ directory

   cd /opt/hivemq

2. Execute startup script

   ./bin/run.sh

Starting as daemon

1. Start the daemon

   /etc/init.d/hivemq start

Verify if HiveMQ is running

Check if HiveMQ is listening to the default port for MQTT

netstat -an | grep 1883

If you’re running HiveMQ as daemon:

/etc/init.d/hivemq status

Windows systems

Manual installation

1. Clone the repository from https://github.com/hivemq/hivemq-community-edition.git and run ./gradlew clean hivemqZip

2. Extract the hivemq-ce-<version>.zip file in the build\zip folder of the repository to C:\hivemq using your favorite Zip unpack utility.

Installation as Windows Service

The steps to install HiveMQ as a Windows Service are:

1. Download the hivemq-windows-service.zip file from here

2. Unzip the hivemq-windows-service.zip file.

3. Copy the windows-service folder to your HiveMQ home folder.

4. Open the windows-service folder.

5. Double click the installService.bat file.

6. Reboot

Important

Make sure you have the permission to install a service. Therefore it might be necessary to right click the installService.bat and select Run as administrator.

Starting HiveMQ

The following instructions show how to start HiveMQ after installing:

Double click on the run.bat file.

Important

Please keep in mind that a click with the left mouse button (QuickEdit) stops the output of the command line. When you click the command line before "Started HiveMQT in xxx ms" is displayed, the HiveMQ start up is interrupted and needs to be continued via a click of the right mouse button. A click after the HiveMQ start up has no impact on the execution of HiveMQ.

Verify if HiveMQ is running

Check if HiveMQ is listening to the default port for MQTT.

Open cmd.exe and run:

netstat -an | find "1883"