Skip to content

Commit

Permalink
docs: rewrite get started #42
Browse files Browse the repository at this point in the history
  • Loading branch information
@tadayosi
tadayosi committed Dec 6, 2023
1 parent 2a5fbbe commit 1e28b11
Show file tree
Hide file tree
Showing 2 changed files with 123 additions and 143 deletions.
262 changes: 120 additions & 142 deletions modules/ROOT/pages/get-started.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,186 @@
= Get Started

Hawtio consists of 2 parts: an AngularJS application and a Java backend, which proxies the communication between the frontend and https://jolokia.org/[Jolokia] endpoints. The frontend has access to all JMX attributes and operations available in Java applications running locally and remotely.
There are several options to start using Hawtio console:

Ways to run it:

- <<Running an executable JAR>>
- <<Running from CLI (JBang)>>
- <<Running a Quarkus app>>
- <<Running a Spring Boot app>>
- <<Deploying on a Servlet container>>
- <<Deploying on an application server>>
- <<Deploying on Apache Karaf>>
- <<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 xref:configuration.adoc[].

== Running an executable JAR

You can startup Hawtio on your machine using the hawtio-app executable JAR.
== Running from CLI (JBang)

https://repo1.maven.org/maven2/io/hawt/hawtio-app/3.0-M6/hawtio-app-3.0-M6.jar[Download hawtio-app.jar,window=_blank]
You can install and run Hawtio from CLI using https://www.jbang.dev/[JBang]. If you don't have JBang locally yet, first install it following:
https://www.jbang.dev/download/

Once you have downloaded it, just run this from the command line:
Now you can install the latest Hawtio on your machine using the `jbang` command:

[source,console]
----
java -jar hawtio-app-x.y.z.jar
$ jbang app install hawtio@hawtio/hawtio
----

Note: If you launch Hawtio with Java 9+, add the specified modules to avoid errors on startup and allow attaching to other Java processes:
It installs `hawtio` command. You can launch a Hawtio instance with the following command:

[source,console]
----
java --add-modules jdk.attach,java.xml.bind -jar hawtio-app-x.y.z.jar
$ hawtio
----

The console should show you which URL to open, which by default is `http://localhost:8080/hawtio`.
The command will automatically open the console at http://0.0.0.0:8080/hawtio/.

To set a different port number, run:
To change the port number, run:

[source,console]
----
java -jar hawtio-app-x.y.z.jar --port 8090
$ hawtio --port 8090
----

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

[source,console]
----
$ hawtio --help
Usage: hawtio [-hjoV] [-c=<contextPath>] [-d=<plugins>] [-e=<extraClassPath>]
[-H=<host>] [-k=<keyStore>] [-l=<warLocation>] [-p=<port>]
[-s=<keyStorePass>] [-w=<war>]
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.
-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.
----

== Running a Quarkus app

IMPORTANT: The supported Quarkus versions are 2.x for Hawtio v3. The upcoming Hawtio v4 will support Quarkus 3.x.

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`:
+
[source,xml]
----
<dependency>
<groupId>io.hawt</groupId>
<artifactId>hawtio-quarkus</artifactId>
<version>3.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>
----

To see the full list of configuration options, run:
Now you should be able to run Hawtio with your Quarkus application in development mode as follows:

[source,console]
----
java -jar hawtio-app-x.y.z.jar --help
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.

https://github.com/hawtio/hawtio/tree/hawtio-3.0.0-RC1/examples/quarkus[Quarkus example,window=_blank]


== Running a Spring Boot app

Attaching the Hawtio console to your Spring Boot app is simple.
IMPORTANT: The supported Spring Boot versions are 2.x for Hawtio v3. The upcoming Hawtio v4 will support Spring Boot 3.x.

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

=== Set up

. Add `io.hawt:hawtio-springboot` to the dependencies in `pom.xml`:
1. Add `io.hawt:hawtio-springboot` and the supporting Camel Spring Boot starters to the dependencies in `pom.xml`:
+
[source,xml]
----
<dependency>
<groupId>io.hawt</groupId>
<artifactId>hawtio-springboot</artifactId>
<version>x.y.z</version>
<version>3.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 line in `application.properties`:
2. Enable the Hawtio and Jolokia endpoints by adding the following lines to `application.properties`:
+
[source,java]
----
management.endpoints.web.exposure.include=hawtio,jolokia
spring.jmx.enabled=true
management.endpoints.web.exposure.include = hawtio,jolokia
spring.jmx.enabled = true
----

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

[source,console]
----
mvn spring-boot:run
----

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

=== Configuring Hawtio path

If you'd prefer to not have the `/actuator` base path, then you can customize the Spring Boot management base path with the `management.endpoints.web.base-path` property:
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:

[source,java]
----
management.endpoints.web.base-path=/
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:

[source,java]
----
management.endpoints.web.path-mapping.hawtio=hawtio/console
management.endpoints.web.path-mapping.hawtio = hawtio/console
----

=== Example

There is a working Spring Boot example that shows Hawtio monitoring a sample web application which exposes information about Apache Camel routes, metrics, etc.
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.

https://github.com/hawtio/hawtio/tree/master/examples/springboot"[Hawtio Spring Boot example,window=_blank]

Expand All @@ -111,140 +192,37 @@ If you use Tomcat or Jetty, you can deploy the Hawtio WAR file.

https://github.com/hawtio/hawtio/releases/latest[Download hawtio-default.war,window=_blank]

Please read the [configuration guide](../configuration/) to see how to configure the console, in particular security.

== Deploying on an application server

If you don't use the WildFly application server, use one of the options from the <<Deploying on an application server>> section to download Hawtio.

If you do use WildFly, download https://github.com/hawtio/hawtio/releases/latest[hawtio-wildfly.war,window=_blank].

To enable security, you'll need to set up configuration like this:

[source,xml]
----
<extensions>
...
</extensions>
<system-properties>
<property name="hawtio.authenticationEnabled" value="true" />
<property name="hawtio.realm" value="jboss-web-policy" />
<property name="hawtio.role" value="admin" />
</system-properties>
----

If you experience problems with security, you'll need to disable security in Hawtio. For WildFly, you can set the `hawtio.authenticationEnabled` system property in `standalone/configuration/standalone.xml`:

[source,xml]
----
<extensions>
...
</extensions>
<system-properties>
<property name="hawtio.authenticationEnabled" value="false" />
</system-properties>
----

== Deploying on Apache Karaf

Hawtio provides the following features for Apache Karaf:

////
<div class="table-responsive">
<table class="table table-striped table-condensed table-hover">
<thead>
<tr>
<th>Feature</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>hawtio-core</td>
<td>Installs the core Hawtio war file with minimal extensions</td>
</tr>
<tr>
<td>hawtio-rbac</td>
<td>Installs the Hawtio RBAC enabler bundles</td>
</tr>
<tr>
<td>hawtio-log</td>
<td>Installs the Hawtio logging backend MBeans</td>
</tr>
<tr>
<td>hawtio</td>
<td>Installs the main Hawtio web console</td>
</tr>
</table>
</div>
////

If you are using https://karaf.apache.org/[Apache Karaf] 4.x:

[source,console]
----
feature:repo-add hawtio <version>
feature:install hawtio
----

This will install all the features listed above. The Hawtio console can then be viewed at http://localhost:8181/hawtio.

Karaf versions prior to 4.x are not supported.

=== If you use an HTTP proxy

If you are behind an HTTP proxy, you'll need to enable HTTP proxy support in WildFly / Karaf to be able to download Hawtio from the central maven repository.

There are a few https://mpashworth.wordpress.com/2012/09/27/installing-apache-karaf-features-behind-a-firewall/[articles about] https://stackoverflow.com/questions/9922467/how-to-setup-a-proxy-for-apache-karaf[this] which may help. Here are the steps:

Edit the `etc/org.ops4j.pax.url.mvn.cfg` file and make sure the following line is uncommented:

[source,java]
----
org.ops4j.pax.url.mvn.proxySupport=true
----

You may also want **org.ops4j.pax.url.mvn.settings** to point to your Maven `settings.xml` file. **NOTE** use / in the path, not \.

[source,java]
----
org.ops4j.pax.url.mvn.settings=C:/Program Files/MyStuff/apache-maven-3.0.5/conf/settings.xml
----

WildFly / Karaf will then use your https://maven.apache.org/guides/mini/guide-proxies.html[Maven HTTP proxy settings] from your `~/.m2/settings.xml` to connect to the maven repositories listed in `etc/org.ops4j.pax.url.mvn.cfg` to download artifacts.
Please read xref:configuration.adoc[] to see how to configure the console, or in particular for security see xref:security.adoc[].

== Using Hawtio embedded in a Java application

If you do not use a servlet container or application server and wish to embed Hawtio inside your Java application, try the following:
You can also embed Hawtio inside your Java application instead of deploying it on a servlet container or application server.

Add the following to your `pom.xml`:
To embed Hawtio to an application, add `io.hawt:hawtio-embedded` to your `pom.xml`:

[source,xml]
----
<dependency>
<groupId>io.hawt</groupId>
<artifactId>hawtio-embedded</artifactId>
<version>${hawtio-version}</version>
<version>3.x.y</version>
</dependency>
----

Then in your application run the following code:
Then write the following code in your application:

[source,java]
----
import io.hawt.embedded.Main;
...
Main main = new Main();
main.setWar("somePathOrDirectoryContainingHawtioWar");
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).
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.).

Depending on the war you are loading, you may also need to turn off authentication before running the embedded hawtio so that it can be accessible in an unauthenticated environment:
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:

[source,java]
----
Expand Down
4 changes: 3 additions & 1 deletion modules/ROOT/pages/overview-v3.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,4 +23,6 @@ The xref:plugins.adoc[builtin plugins] are hosted in the project.

Repository:: https://github.com/hawtio/hawtio

This Java project assembles <<Hawtio React>> with the Java backend to offer https://github.com/hawtio/hawtio/releases[the distributions] you can use as the Hawtio console. The Java backend provides several API endpoints to support authentication and security on Java, and custom MBeans to enable the frontend plugins. It also implements the runtimes support so that the console can be embedded into the supported runtimes such as Quarkus and Spring Boot.
This Java project assembles <<Hawtio React>> with the Java backend to offer https://github.com/hawtio/hawtio/releases[the distributions] you can use as the Hawtio console.

The Java backend proxies the communication between the frontend and https://jolokia.org/[Jolokia] endpoints. It provides several API endpoints to support authentication and security on Java, and custom MBeans to enable the frontend plugins. It also implements the runtimes support so that the console can be embedded into the supported runtimes such as Quarkus and Spring Boot.

0 comments on commit 1e28b11

Please sign in to comment.