Get Started

There are several options to start using Hawtio console:

Running from CLI (JBang)
Running a Quarkus app
Running a Spring Boot app
Deploying on a Servlet container
Using Hawtio embedded in a Java application

The out of the box defaults try to do the right thing for most folks but if you want to configure things then please check out the Configuration.

Running from CLI (JBang)

You can install and run Hawtio from CLI using JBang. If you don’t have JBang locally yet, first install it following: https://www.jbang.dev/download/

Now you can install the latest Hawtio on your machine using the jbang command:

$ jbang app install hawtio@hawtio/hawtio

It installs hawtio command. You can launch a Hawtio instance with the following command:

$ hawtio

The command will automatically open the console at http://localhost:8080/hawtio/.

To change the port number, run:

$ hawtio --port 8090

For more information on the configuration options of the CLI, run:

Usage: hawtio [-hjoV] [-c=<contextPath>] [-d=<plugins>] [-e=<extraClassPath>]
              [-H=<host>] [-k=<keyStore>] [-l=<warLocation>] [-p=<port>]
              [-s=<keyStorePass>] [-w=<war>] [-n=<String=Optional>]...
Run Hawtio
  -c, --context-path=<contextPath>
                      Context path.
  -d, --plugins-dir=<plugins>
                      Directory to search for .war files to install as 3rd
                        party plugins.
  -e, --extra-class-path=<extraClassPath>
                      Extra class path.
  -h, --help          Print usage help and exit.
  -H, --host=<host>   Hostname to listen to.
  -j, --join          Join server thread.
  -k, --key-store=<keyStore>
                      JKS keyStore with the keys for https.
  -l, --war-location=<warLocation>
                      Directory to search for .war files.
  -n, --connection=<String=Optional>
                      List of settings for automated connections.
  -o, --open-url      Open the web console automatic in the web browser.
  -p, --port=<port>   Port number.
  -s, --key-store-pass=<keyStorePass>
                      Password for the JKS keyStore with the keys for https.
  -V, --version       Print Hawtio version
  -w, --war=<war>     War file or directory of the hawtio web application.

Connecting directly to a remote JVM from CLI

Starting from Hawtio 4.3.0, it is possible to connect to remote Java applications directly from the CLI (#3731). Passing a remote Jolokia endpoint URL in the form [Name]=[Jolokia URL] to the --connection or -n option will automatically attempt to connect to that endpoint when Hawtio starts.

$ hawtio --connection=myconn=http://localhost:8778/jolokia/

If you have previously connected to an endpoint URL with a name, the connection information is cached in the browser’s local storage via the Connect plugin. In that case, you can connect to that endpoint by simply specifying the same connection name without URL.

$ hawtio --connection=myconn

You can also connect to multiple JVMs at once by providing the --connection options multiple times.

$ hawtio --connection=conn1 --connection=conn2 --connection=conn3

In this case, multiple tabs open simultaneously on the browser, each showing the Hawtio console connected to a different connection.

Running a Quarkus app

You can attach the Hawtio console to your Quarkus application in a single step.

Set up

Add io.hawt:hawtio-quarkus and the supporting Camel Quarkus extensions to the dependencies in pom.xml (replace 4.x.y with the latest Hawtio release version):

<dependency>
  <groupId>io.hawt</groupId>
  <artifactId>hawtio-quarkus</artifactId>
  <version>4.x.y</version>
</dependency>

<!-- Mandatory for enabling Camel management via JMX / Hawtio -->
<dependency>
  <groupId>org.apache.camel.quarkus</groupId>
  <artifactId>camel-quarkus-management</artifactId>
</dependency>
<!-- (Optional) Required for Hawtio Camel route diagram tab -->
<dependency>
  <groupId>org.apache.camel.quarkus</groupId>
  <artifactId>camel-quarkus-jaxb</artifactId>
</dependency>

Now you should be able to run Hawtio with your Quarkus application in development mode as follows:

mvn compile quarkus:dev

Opening http://localhost:8080/hawtio should show you the Hawtio console.

Example

See the following for a working Quarkus application example.

Quarkus example

Running a Spring Boot app

You can attach the Hawtio console to your Spring Boot application in two steps.

Set up

Add io.hawt:hawtio-springboot and the supporting Camel Spring Boot starters to the dependencies in pom.xml (replace 4.x.y with the latest Hawtio release version):

<dependency>
  <groupId>io.hawt</groupId>
  <artifactId>hawtio-springboot</artifactId>
  <version>4.x.y</version>
</dependency>

<!-- Mandatory for enabling Camel management via JMX / Hawtio -->
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-management-starter</artifactId>
</dependency>
<!-- (Optional) Required for Hawtio Camel route diagram tab -->
<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-spring-boot-xml-starter</artifactId>
</dependency>

Enable the Hawtio and Jolokia endpoints by adding the following lines to application.properties:
```
spring.jmx.enabled = true
management.endpoints.web.exposure.include = hawtio,jolokia
```

Now you should be able to run Hawtio with your Spring Boot application in development mode as follows:

mvn spring-boot:run

Opening http://localhost:8080/actuator/hawtio should show you the Hawtio console.

Configuring Hawtio path

If you don’t prefer to have the /actuator base path for the Hawtio endpoint, you can customize the Spring Boot management base path with the management.endpoints.web.base-path property:

management.endpoints.web.base-path = /

You can also customize the path to the Hawtio endpoint by setting the management.endpoints.web.path-mapping.hawtio property:

management.endpoints.web.path-mapping.hawtio = hawtio/console

Example

There is a working Spring Boot example that shows how to monitor a web application which exposes information about Apache Camel routes, metrics, etc. with Hawtio.

Hawtio Spring Boot example

A good MBean for real time values and charts is java.lang/OperatingSystem. Try looking at Camel routes. Notice that as you change selections in the tree the list of tabs available changes dynamically based on the content.

Deploying on a Servlet container

If you use Apache Tomcat or Eclipse Jetty, you can deploy the Hawtio WAR file.

Download hawtio-default.war from GitHub

Please read Configuration to see how to configure the console, or in particular for security see Security.

Deploying to Apache Tomcat

Standard Apache Tomcat distribution is ready to use unpacking and Hawtio WAR application can simply be copied into $TOMCAT_HOME/webapps.

Deploying to Eclipse Jetty

Jetty distribution is available in Maven Central as org.eclipse.jetty:jetty-home Maven artifacts.

With Jetty 12, it is not possible to simply start the server after unzipping jetty-home.zip archive. The recommended way is to create a Jetty Base directory and start from there after adding necessary modules. See Jetty Quick Setup for details.

After setting up base location, it is enough to simply add http and ee10-deploy (Jetty 12) or deploy (Jetty 11) module - all required modules will be used automatically.

However we recommend to explicitly add the modules on which ee10-deploy (or deploy) module depends - all template configuration files will then be available in $JETTY_BASE/start.d/ directory.

Because Hawtio can be configured using System properties, we can make configuration easier by adding Jetty’s jvm module, so all configuration properties can be stored in $JETTY_BASE/start.d/jvm.ini.

Jetty XML deployment

It is possible to deploy Jetty XML file instead of actual WAR application, so when there’s hawtio.war located in your local filesystem, it is possible to drop this file int o $JETTY_BASE/webapps:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.ee10.webapp.WebAppContext">
  <Set name="contextPath">/hawtio</Set>
  <Set name="war">/data/tmp/hawtio-war-4.2.0.war</Set>
</Configure>

But there’s a trick here. Normally Jetty unpacks this WAR archive to a temporary folder (which may be specified with -Djava.io.tmpdir system property). But there’s no need for unpacking if there’s hawtio-war-4.2.0 directory next to hawtio-war-4.2.0.war achive.

Jetty uses org.eclipse.jetty.server.SymlinkAllowedResourceAliasChecker alias checker and if real path for the above /data/tmp/hawtio-war-4.2.0 is different (i.e., the path uses symbolic links), resources from this WAR application won’t be loaded and Hawtio application won’t work.

NOTE: This may be a problem when using such XML deployment when hawtio.war is located in Maven project, because maven-war-plugin usually keeps hawtio-war-<version> directory and hawtio-war-<version>.war archive in the same target/ location.

Using Hawtio embedded in a Java application

You can also embed Hawtio inside your Java application instead of deploying it on a servlet container or application server.

To embed Hawtio to an application, add io.hawt:hawtio-embedded to your pom.xml (replace 4.x.y with the latest Hawtio release version):

<dependency>
  <groupId>io.hawt</groupId>
  <artifactId>hawtio-embedded</artifactId>
  <version>4.x.y</version>
</dependency>

Then write the following code in your application:

import io.hawt.embedded.Main;

Main main = new Main();
main.setWar("<path-to-hawtio-war>");
main.run();

If you wish to do anything fancy it should be easy to override the Main class to find the hawtio-war.war in whatever place you wish to locate it (such as your local maven repo or download it from some server, etc.).

You may want to turn off authentication before running the embedded Hawtio so that it can be accessible out of the box without proper authentication configuration:

System.setProperty("hawtio.authenticationEnabled", "false");