docs: document the available configuration with hawtconfig.json

Fix #49
hawtio · Oct 24, 2024 · 4c0bded · 4c0bded
1 parent 9ef5a86
commit 4c0bded
Showing 1 changed file with 359 additions and 5 deletions.
diff --git a/modules/ROOT/pages/configuration.adoc b/modules/ROOT/pages/configuration.adoc
@@ -1,8 +1,15 @@
 = Configuration
 
+Hawtio consists of two main components: the server runtime and client console. The server runtime is the Java backend that runs on the server side, and the client console is the JavaScript frontend that is deployed and runs on the browser.
+
+Therefore, two types of configuration are provided for Hawtio:
+
+1. <<Configuration properties>> - The server runtime configuration
+2. <<_hawtconfig_json,hawtconfig.json>> - The client console configuration
+
 == Configuration properties
 
-Hawtio and its plugins can configure their behaviours through System properties.
+The Hawtio server runtime and its plugins can configure their behaviours through System properties.
 
 The following table lists the configuration properties for the Hawtio core system and various plugins.
 
@@ -13,19 +20,19 @@ NOTE: For the configuration properties related to security and authentication, r
 |===
 |System property |Default |Description
 
-|hawtio.disableProxy
+|`hawtio.disableProxy`
 |`false`
 |With this property set to `true`, `ProxyServlet` (`/hawtio/proxy/*`) can be disabled. This makes Connect plugin unavailable, which means Hawtio can no longer connect to remote JVMs, but sometimes users might want to do so because of security if Connect plugin is not used.
 
-|hawtio.localAddressProbing
+|`hawtio.localAddressProbing`
 |`true`
 |Whether local address probing for proxy allowlist is enabled or not upon startup. Set this property to `false` to disable it.
 
-|hawtio.proxyAllowlist
+|`hawtio.proxyAllowlist`
 |`localhost, 127.0.0.1`
 |Comma-separated allowlist for target hosts that Connect plugin can connect to via `ProxyServlet`. All hosts that are not listed in this allowlist are denied to connect for security reasons. This option can be set to `*` to allow all hosts. Prefixing an element of the list with `"r:"` allows to define a regexp (example: `localhost,r:myserver[0-9]+.mydomain.com`)
 
-|hawtio.redirect.scheme
+|`hawtio.redirect.scheme`
 |-
 |The scheme of the redirect URL to login page when authentication is required.
 
@@ -80,3 +87,350 @@ To activate the Hawtio RBAC restrictor, configure the Jolokia parameter `restric
 ----
 jolokia.restrictorClass = io.hawt.system.RBACRestrictor
 ----
+
+== hawtconfig.json
+
+`hawtconfig.json` is the entrypoint JSON file for configuring the frontend console of Hawtio. It can be used to customise the various parts of the console: the branding, styles and basic UI parts such as the login page and about modal, as well as the console-specific behaviours of some of the Hawtio plugins.
+
+Here is an example file of `hawtconfig.json`:
+
+[source,json]
+.Example `hawtconfig.json`
+----
+{
+  "branding": {
+    "appName": "Hawtio Management Console",
+    "showAppName": false,
+    "appLogoUrl": "hawtio-logo.svg",
+    "companyLogoUrl": "hawtio-logo.svg",
+    "css": "",
+    "favicon": "favicon.ico"
+  },
+  "login": {
+    "description": "Login page for Hawtio Management Console.",
+    "links": [
+      { "url": "#terms", "text": "Terms of Use" },
+      { "url": "#help", "text": "Help" },
+      { "url": "#privacy", "text": "Privacy Policy" }
+    ]
+  },
+  "about": {
+    "title": "Hawtio Management Console",
+    "description": "A Hawtio reimplementation based on TypeScript + React.",
+    "imgSrc": "hawtio-logo.svg",
+    "productInfo": [
+      { "name": "ABC", "value": "1.2.3" },
+      { "name": "XYZ", "value": "7.8.9" }
+    ],
+    "copyright": "© Hawtio project"
+  },
+  "disabledRoutes": [
+    "/disabled"
+  ]
+}
+----
+
+=== Configuration options in `hawtconfig.json`
+
+At the top level of `hawtconfig.json`, the following options are currently provided:
+
+[cols="2,5"]
+.Top-level configuration options
+|===
+|Option |Description
+
+|`branding` |The branding options for the console.
+|`login` |The login page configuration.
+|`about` |The about modal configuration.
+|`disabledRoutes` |The list of plugins that should be hidden from the console.
+|`jmx` |The JMX plugin configuration.
+|`online` |The Hawtio Online configuration.
+
+|===
+
+==== Branding
+
+The `branding` configuration provides the options to customise the console's branding, such as the application name, logos, styles and favicon.
+
+[cols="2,1,5"]
+.Branding configuration options
+|===
+|Option |Default |Description
+
+|`appName` |`Hawtio Management Console` |Customise the application name of the console. The name is used in the browser title header and optionally in the header of the console page.
+|`showAppName` |`false` |Show the application name in the header of the console page.
+|`appLogoUrl` |`img/hawtio-logo.svg` |Use the URL to substitute the application logo.
+|`companyLogoUrl` |`img/hawtio-logo.svg` |Use the URL to substitute the company logo.
+|`css` | |Provide the custom CSS to apply to the console.
+|`favicon` | |Use the URL to substitute the favicon.
+
+|===
+
+Here is how the `branding` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "branding": {
+    "appName": "Hawtio Management Console",
+    "showAppName": false,
+    "appLogoUrl": "hawtio-logo.svg",
+    "companyLogoUrl": "hawtio-logo.svg",
+    "css": "",
+    "favicon": "favicon.ico"
+  }
+----
+
+==== Login
+
+The `login` configuration provides the options to customise the information displayed in the Hawtio login page.
+
+[cols="2,1,5"]
+.Login configuration options
+|===
+|Option |Default |Description
+
+|`description` | |Set the text displayed in the login page.
+|`links` | `[]` |Provide the links at the bottom of the login page. The value should be an array of objects with `url` and `text` properties.
+
+|===
+
+Here is how the `login` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "login": {
+    "description": "Login page for Hawtio Management Console.",
+    "links": [
+      { "url": "#terms", "text": "Terms of Use" },
+      { "url": "#help", "text": "Help" },
+      { "url": "#privacy", "text": "Privacy Policy" }
+    ]
+  }
+----
+
+==== About
+
+The `about` configuration provides the options to customise the information displayed in the Hawtio About modal.
+
+[cols="2,1,5"]
+.About configuration options
+|===
+|Option |Default |Description
+
+|`title` |`Hawtio Management Console` |Customise the title of the About modal.
+|`description` | |Provide the description text to the About modal.
+|`imgSrc` |`img/hawtio-logo.svg` |Use the URL to substitute the logo image in the About modal.
+|`productInfo` | `[]` |Provide the information of names and versions about the additional components used in the console. The value should be an array of objects with `name` and `value` properties.
+|`copyright` | |Set the copyright information in the About modal.
+
+|===
+
+Here is how the `about` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "about": {
+    "title": "Hawtio Management Console",
+    "description": "A Hawtio reimplementation based on TypeScript + React.",
+    "imgSrc": "hawtio-logo.svg",
+    "productInfo": [
+      { "name": "ABC", "value": "1.2.3" },
+      { "name": "XYZ", "value": "7.8.9" }
+    ],
+    "copyright": "© Hawtio project"
+  }
+----
+
+==== Disabled routes
+
+The `disabledRoutes` configuration provides the option to hide the plugins from the console.
+
+The value of the option should be an array of strings that represent the paths of the plugins that should be hidden.
+
+Here is how the `disabledRoutes` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "disabledRoutes": [
+    "/disabled"
+  ]
+----
+
+==== JMX plugin
+
+The https://github.com/hawtio/hawtio-next/tree/main/packages/hawtio/src/plugins/jmx[JMX] plugin is customisable via the `jmx` configuration in `hawtconfig.json`.
+
+TIP: By default Hawtio loads all MBeans into the workspace via the JMX plugin. Sometimes your custom Hawtio console might want to load only a portion of MBeans to reduce the load on the application. The `jmx` configuration provides an option to limit the MBeans to be loaded into the workspace.
+
+[cols="2,1,5"]
+.JMX plugin configuration options
+|===
+|Option |Default |Description
+
+|`workspace` |
+a|Specify the list of MBean domains and object names that should be loaded to the JMX plugin workspace.
+This option can either disable workspace completely by setting `false`, or specify an array of MBean paths in the form of:
+----
+<domain>/<prop1>=<value1>,<prop2>=<value2>,...
+----
+to fine-tune which MBeans to load into workspace.
+
+WARNING: Disabling workspace should also deactivate all the plugins that depend on MBeans provided by workspace.
+
+|===
+
+Here is how the `jmx` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "jmx": {
+    "workspace": [
+      "hawtio",
+      "java.lang/type=Memory",
+      "org.apache.camel",
+      "no.such.domain"
+    ]
+  }
+----
+
+==== Hawtio Online
+
+The frontend aspects of https://github.com/hawtio/hawtio-online[Hawtio Online] can be configured via the `online` configuration in `hawtconfig.json`.
+
+[cols="2,1,5"]
+.Hawtio Online configuration options
+|===
+|Option |Default |Description
+
+|`projectSelector` | |Set the selector used to watch for projects.
+It is only applicable when the `Hawtio` deployment type is equal to `cluster`.
+By default, all the projects the logged in user has access to are watched.
+The string representation of the selector must be provided, as mandated by the `--selector`, or `-l`, options from the `kubectl get` command.
+See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
+
+|`consoleLink` | |Configure the OpenShift Web console link.
+A link is added to the application menu when the `Hawtio` deployment is equal to `cluster`.
+Otherwise, a link is added to the Hawtio project dashboard.
+The value should be an object with the following properties: `text`, `section`, and `imageRelativePath`.
+
+|===
+
+[cols="2,1,5"]
+.ConsoleLink configuration options
+|===
+|Option |Default |Description
+
+|`text` | |Set the text display for the link.
+|`section` | |Set the section of the application menu in which the link should appear. It is only applicable when the Hawtio deployment type is equal to `cluster`.
+|`imageRelativePath` | |Set the path, relative to the Hawtio status URL, for the icon used in front of the link in the application menu. It is only applicable when the `Hawtio` deployment type is equal to `cluster`. The image should be square and will be shown at 24x24 pixels.
+
+|===
+
+Here is how the `online` configuration looks in `hawtconfig.json`:
+
+[source,json]
+.`hawtconfig.json`
+----
+  "online": {
+    "projectSelector": "myproject",
+    "consoleLink": {
+        "text": "Hawtio Management Console",
+        "section": "Hawtio",
+        "imageRelativePath": "/online/img/favicon.ico"
+    }
+  }
+----
+
+=== Deploying `hawtconfig.json`
+
+==== Quarkus
+
+For a Quarkus application, the `hawtconfig.json` file, as well as the other companion static resources such as CSS files and images, should be placed under `META-INF/resources/hawtio` in the `src/main/resources` directory of the project.
+
+You can find an example Quarkus project at:
+
+- https://github.com/hawtio/hawtio/tree/4.x/examples/quarkus
+
+==== Spring Boot
+
+For a Spring Boot application, the `hawtconfig.json` file, as well as the other companion static resources such as CSS files and images, should be placed under `hawtio-static` in the `src/main/resources` directory of the project.
+
+You can find an example Spring Boot project at:
+
+- https://github.com/hawtio/hawtio/tree/4.x/examples/springboot-authentication
+
+=== Customising from plugins
+
+While plugins cannot directly provide the `hawtconfig.json` file itself for the console, they can customise the configuration after the file is loaded from the main console application.
+
+The `@hawtio/react` NPM package provides the `configManager` API. You can use this API in the plugin's `index.ts` to customise the configuration of `hawtconfig.json` during the loading of the plugin.
+
+Here is an example of how you can customise the `hawtconfig.json` configuration from a plugin:
+
+[source,typescript]
+----
+import { HawtioPlugin, configManager } from '@hawtio/react'
+...
+
+/**
+ * The entry function of your plugin.
+ */
+export const plugin: HawtioPlugin = () => {
+  ...
+}
+
+// Register the custom plugin version to Hawtio
+// See package.json "replace-version" script for how to replace the version placeholder with a real version
+configManager.addProductInfo('Hawtio Sample Plugin', '__PACKAGE_VERSION_PLACEHOLDER__')
+
+/*
+ * This example also demonstrates how branding and styles can be customised from a WAR plugin.
+ *
+ * The Plugin API `configManager` provides `configure(configurer: (config: Hawtconfig) => void)` method
+ * and you can customise the `Hawtconfig` by invoking it from the plugin's `index.ts`.
+ */
+configManager.configure(config => {
+  // Branding & styles
+  config.branding = {
+    appName: 'Hawtio Sample WAR Plugin',
+    showAppName: true,
+    appLogoUrl: '/sample-plugin/branding/Logo-RedHat-A-Reverse-RGB.png',
+    css: '/sample-plugin/branding/app.css',
+    favicon: '/sample-plugin/branding/favicon.ico',
+  }
+  // Login page
+  config.login = {
+    description: 'Login page for Hawtio Sample WAR Plugin application.',
+    links: [
+      { url: '#terms', text: 'Terms of use' },
+      { url: '#help', text: 'Help' },
+      { url: '#privacy', text: 'Privacy policy' },
+    ],
+  }
+  // About modal
+  if (!config.about) {
+    config.about = {}
+  }
+  config.about.title = 'Hawtio Sample WAR Plugin'
+  config.about.description = 'About page for Hawtio Sample WAR Plugin application.'
+  config.about.imgSrc = '/sample-plugin/branding/Logo-RedHat-A-Reverse-RGB.png'
+  if (!config.about.productInfo) {
+    config.about.productInfo = []
+  }
+  config.about.productInfo.push(
+    { name: 'Hawtio Sample Plugin - simple-plugin', value: '1.0.0' },
+    { name: 'Hawtio Sample Plugin - custom-tree', value: '1.0.0' },
+  )
+  // If you want to disable specific plugins, you can specify the paths to disable them.
+  //config.disabledRoutes = ['/simple-plugin']
+})
+----
+
+You can find an example WAR plugin project at:
+
+- https://github.com/hawtio/hawtio-sample-war-plugin-ts