Knot.x Starter Kit

Starter Kit is a template project that simplifies Knot.x project setup. It allows you to customize the Knot.x distribution with your own modules and configuration entries.

Starter Kit artifacts (see the build/distributions folder) are:

• a ZIP file when ./gradlew build-stack or ./gradlew build
• a custom Docker image when ./gradlew build-docker

How to build & run

To start a new Knot.x project simply download the chosen ZIP version from https://github.com/Knotx/knotx-starter-kit/tags or use the development one (from the master branch). Follow Development process instructions when use the development version.

Then unzip Starter Kit and run:

Build ZIP distribution

$> ./gradlew build-stack

to:

• build all your custom Knot.x modules
• download Knot.x Stack artifact, add all required dependencies (including your custom modules and its transitive dependencies), override configs with /knotx/config
• build the custom ZIP artifact

Then, go to the build/distributions directory, unzip the ZIP artifact, start Knot.x:

chmod +x bin/knotx
bin/knotx run-knotx

and validate urls:

• localhost:8092/api/v1/example
• localhost:8092/api/v2/example

Build & validate Docker image

$> ./gradlew build-docker

to:

• build all your custom Knot.x modules
• prepare your custom Docker image with all required dependencies (including your custom modules and its transitive dependencies) and configs
• validate your Docker image with system tests

Then, start Docker container:

docker run -p8092:8092 knotx/knotx-starter-kit

and validate urls:

• localhost:8092/api/v1/example
• localhost:8092/api/v2/example

Knot.x version and depencendies

Knot.x Starter Kit requires Knot.x to run. The version of Knot.x currently ised is defined in the gradle.properties as knotxVersion. If you want to upgrade to the newer version of Knot.x this is the only place you need to change in the future.

Especially important dependency is the distribution plugin which is applied in the pluginManagement in settings.gradle.

Knot.x as a sub-module of the bigger project

When you use Knot.x Starter Kit template as a module of a bigger Gradle project, the application of Knot.x gradle plugins from settings.gradle will not work. Instead of the pluginManagement in the settings.gradle add following section at the top of main build.gradle.kts:

buildscript {
  repositories {
    jcenter()
    mavenLocal() // only if you need a SNAPSHOT version of Knot.x
  }
  
  dependencies.classpath("io.knotx:knotx-gradle-plugins:${project.property("knotxVersion")}")
}

apply (plugin = "io.knotx.distribution")

What does it contain

Custom modules

• API Handler that contains example implementation of a Handler
• Healthcheck that holds example implementation of a Vert.x Healthcheck
• Action that contains example implementation of a Knot.x Action

All modules are built into JAR files and copied to the KNOTX_HOME/lib folder in the project Docker image. Also all transitive dependencies are automatically downloaded and added to the Docker image.

Configuration

You can also override the default Knot.x configuration with your custom settings. All files from the /conf directory are copied to KNOTX_HOME/conf. So you can easily modify the Knot.x configuration, reconfigure the logger or update an Open API specification.

If you want to add a dependency that is not connected with any custom module such as Knot.x Dashboard you can add this entry in /build.gradle.kts:

dependencies {
    subprojects.forEach { "dist"(project(":${it.name}")) }
    "dist"("io.knotx:knotx-dashboard:${project.version}")
}

Dockerfile

Dockerfile is defined in the docker folder and extends the Base Knot.x Docker image.

How to debug

ZIP distribution

Simply uncomment # JVM_DEBUG line in the bin/knotx starting script.

Docker debugging

Edit Dockerfile in docker folder by adding

RUN sed -i 's/# JVM_DEBUG=/JVM_DEBUG=/g' /usr/local/knotx/bin/knotx

Start Docker container with additional port

docker run -p8092:8092 -p18092:18092 knotx/knotx-starter-kit

Startup debugging - use this when debugging start() methods

In addition to above edit Dockerfile by adding

RUN sed -i 's/suspend=n/suspend=y/g' /usr/local/knotx/bin/knotx

Comment out health-check section from Dockerfile

#HEALTHCHECK --interval=5s --timeout=2s --retries=12 \
#  CMD curl --silent --fail localhost:8092/healthcheck || exit 1

IMPORTANT ! - Make sure that CMD [ "knotx", "run-knotx" ] is a last command in Dockerfile