Building from Source

Hono can be deployed using the pre-built Docker images available from our Docker Hub repositories. However, customizing and/or extending Hono’s functionality requires building the images from source code.

This page provides step by step instructions for getting the source code and building the Hono’s Docker images from it.

Prerequisites for building Hono

Docker

Creating Hono’s container images using the Hono build process requires a Docker daemon running either locally or on another host you have access to. Please follow the instructions on the Docker web site to install Docker on your platform.

In case the docker daemon is not running locally, the following environment variable needs to be set in order for the examples in the remainder of this page to run successfully:

export DOCKER_HOST=tcp://${host}:${port}

with ${host} and ${port} reflecting the name/IP address and port of the host where Docker is running on.

Java

Hono is written in Java and therefore requires a Java Development Kit (JDK) version 17 or newer installed on your computer. Please follow the JDK vendor’s instructions for installing Java on your operating system.

Maven

Hono’s build process is based on Apache Maven. You need Maven 3.8.1 or newer to build Hono. Please follow the installation instructions on the Maven home page.

Git

A Git client is required if you want to contribute changes/improvements to the Hono project. It is not necessary for simply building Hono locally. Please refer to the Git Downloads page for installation instructions.

Getting the Hono Source Code

Either

  • download the latest release archive and extract the archive to a local folder or
  • clone the Hono source code repository from GitHub:
    git clone https://github.com/eclipse-hono/hono.git
    
    This will create a hono folder in the current working directory and clone the whole repository into that folder.

Starting the Hono Build Process

Run the following from the source folder:

export DOCKER_HOST
# in the "hono" folder containing the source code
mvn clean install -Pbuild-docker-image,metrics-prometheus

This will build all libraries, Docker images and example code.

Tip

The first build might take several minutes because Docker will need to download all the base images that Hono is relying on. However, most of these will be cached by Docker so that subsequent builds will be running much faster.

Gathering Code Coverage Information for Unit Tests

Hono’s unit tests can be configured to gather code coverage information during execution using the JaCoCo Maven plugin. The plugin is disabled by default and can be enabled by setting the jacoco.skip maven property to false:

# in the "hono" folder containing the source code
mvn clean install -Djacoco.skip=false -Pbuild-docker-image,metrics-prometheus

The plugin will produce a target/jacoco.exec file in each module which contains the (binary) coverage data. It will also produce XML data files under target/site/jacoco in each module. Tools like SonarQube can be used to collect and properly format this data.

Using custom Image Names

The container images being created will have names based on the following pattern: ${docker.registry-name}/${docker.image.org-name}/${project.artifactId}:${project.version}.

The variables in the name are standard Maven properties. The default value for the docker.registry-name property is index.docker.io. The default value for docker.image.org-name is eclipse. The following build command creates Hono’s images using the quay.io registry and the custom repository name:

mvn clean install -Pbuild-docker-image,metrics-prometheus -Ddocker.registry-name=quay.io -Ddocker.image.org-name=custom

Building native Images

The build process supports building native Docker images using the GraalVM for some of Hono’s components. In order to do so, the build-native-image Maven profile needs to be activated:

# in the "hono" folder containing the source code
mvn clean install -Pbuild-native-image,metrics-prometheus
Info

Support for native images is an experimental feature. The build-native-image and the build-docker-image profiles are mutually exclusive. However, they can be built one after the other.

Pushing Images

The container images that are created as part of the build process can be automatically pushed to a container registry using the docker-push-image Maven profile:

mvn clean install -Pbuild-docker-image,metrics-prometheus,docker-push-image

Note that the container registry might require authentication in order to push images. The build uses the Docker Maven Plugin for creating and pushing images. Please refer to the plugin documentation for details regarding how to configure credentials for the registry.

Running the Integration Tests

The source code for Hono comes with a test suite for integration testing. To trigger these tests, change to the tests folder and execute:

# in the "hono/tests" folder containing the test suite
mvn verify -Prun-tests

The tests are executed against the Docker images of the Hono components. Because of that, it is necessary to build the respective images as described above before the execution of the tests. See the hono/tests/readme.md file for more information regarding the test suite.

IDE setup

Checkstyle

Hono uses Checkstyle to ensure its code conforms to a set of defined coding rules. Corresponding checks are done during the Hono build by means of the Maven Checkstyle plugin. In order to integrate the coding rules in the IDE, the corresponding plugin (e.g. Eclipse Checkstyle Plugin or Checkstyle-IDEA) can be configured to use the legal/src/main/resources/checkstyle/default.xml configuration file.

The checkstyle.suppressions.file Checkstyle configuration property should point to the legal/src/main/resources/checkstyle/suppressions.xml file.

Code Formatter

In the Eclipse IDE, the following files can be used to configure the Java code style formatter according to the style used in Hono:

  • eclipse/hono-code-style.xml
  • eclipse/hono-clean-up-profile.xml
  • eclipse/hono.importorder

In Intellij IDEA, the above code style and import order configuration files can be applied by means of the Adapter for Eclipse Code Formatter IDEA plugin.

Running tests

When running Hono unit tests in the IDE, the log output can be configured via the corresponding src/test/resources/application.yml file. Note that by default, color output is enabled via the quarkus.log.console.color property. To see the colored output in Eclipse, the ANSI Escape in Console plugin can be used. The output looks best when using a dark IDE theme.