Home

Awesome

Build Status CodeFactor codecov Gradle Status

Knot.x Launcher

Knot.x Launcher provides a way to configure and run bare Knot.x instance. It contains:

It is used in the Knot.x Stack to deliver fully functional bootstrap project for Knot.x-based projects.

Launcher has two main classes are:

How to run

Knot.x Launcher can be used as a JAR dependency in more complex distributions (like the Knot.x Stack) or started as a standalone Vert.x instance from the ZIP distribution.

To build the Launcher distribution:

$> ./gradlew

To start Knot.x instance:

$> cd build/dist
$> chmod +x bin/start
$> bin/start run-knotx

The output should look like:

13:56:15.890 [vert.x-eventloop-thread-0] INFO io.knotx.launcher.KnotxStarterVerticle - Knot.x STARTED
13:56:15.894 [vert.x-eventloop-thread-1] INFO io.vertx.core.impl.launcher.commands.VertxIsolatedDeployer - Succeeded in deploying verticle

The run-knotx command starts Vert.x instance and deploys all configured modules. This command is registered in the io.vertx.core.Launcher class that is the main class of Vert.x executable jar. Additionally it uses concepts of configuration stores to load configuration files from different locations and with different formats.

It accepts options:

Knot.x provides the example project that contains Docker Compose configuration file to demonstrate cluster and HA capabilities.

Please note that if you want to start Launcher with cluster option you need to provide a required cluster manager dependency and configuration files in the classpath.

How to configure

The Knot.x configuration is basically split into two configuration files:

The configuration is resolved in the following steps:

Configuration stores

The bootstrap.json file is structured around:

The structure of the file defines Vert.x ConfigRetrieverOptions:

{
  "configRetrieverOptions": {
    "scanPeriod": 5000,
    "stores": [
      {
        "type": "file",
        "format": "conf",
        "config": {
          "path": "conf/application.conf"
        },
        "optional": false
      }
    ]
  }
}

In addition to the out of the box config stores and formats it's easy to provide your own custom implementation thanks to the Vert.x Config SPI.

See the Vert.x Config for details how to use and configure any type of the store.

Modules configuration

The application.conf configuration file used in Knot.x distribution supports the HOCON format. In short, the HOCON is the human optimized JSON that keeps the semantics (tree structure; set of types; encoding/escaping) from JSON, but make it more convenient as a human-editable config file format. Notable differences from JSON are comments, variables and includes.

The structure of the file is composed on the following sections:

########### Modules to start ###########
modules {
  # alias = verticle class name
  myserver = "io.knotx.server.KnotxServerVerticle"
  # Other modules to start
}

########### Modules configurations ###########
config.myserver {
  options.config {
    include required("includes/server.conf")
  }
}

## More configs below

The config section for each module is expected to have following structure: MODULE_ALIAS.options.config, where:

The config section can be defined in the form that works best for you, e.g. It can be just raw JSON, or HOCONized version of it as follows:

config {
   myserver {
      options {
         config {
            # verticle configuration
         }
      }
   }
}

Or define it in the form of path in JSON as below

config.myserver.options.config {
    # verticle configuration
}
config.myserver.options.instances=2

Consult HOCON specification to explore all possibilities.

Knot.x Stack defines its own application.conf that uses all configuration possibilities (includes, substitution etc) and provides documentation (in comments) on how to configure Knot.x instance details.

System properties

As mentioned above, you can reference any configuration object or property using ${var} syntax. Thanks to the HOCON capabilities you can also use the same notation to get the value from JVM system properties, e.g.:

java -Dmy.property=1234

And retrieve the value in the config like:

someField = ${my.property}

Additionally, if the value from system property is optional you can use ${?var} syntax to say that inject that value only if it's available. E.g. you can configure default value directly in the application.conf and customize it through system property if necessary.

someField = 1234
someField = ${?my.field.value}

Logback settings

Knot.x Launcher module contains default logback settings in the resources, to provide default logger configuration for the instances.