Branding the Apache Karaf console

Apache Karaf is used as the runtime environment for production application platforms. In such deployments, it is common to have Karaf sporting a custom branding.

The Karaf community has made rebranding the runtime a simple task. Let's make our own for this book.

Getting ready

The ingredients of this recipe include the Apache Karaf distribution kit, access to JDK, Maven, and a source code editor. The sample code for this recipe is available at https://github.com/jgoodyear/ApacheKarafCookbook/tree/master/chapter1/chapter1-recipe3.

How to do it…

1. The first step is generating a Maven-based project structure. For this recipe, we need to only create the bare of Maven POM files, set its packaging to bundle, and include a build section.
2. The next step is adding a resource directive to our POM file's build section. In our POM file, we add a resource directive to our build section, as shown in the following code:

   <resource>
     <directory>
       ${project.basedir}/src/main/resources
     </directory>
     <filtering>true</filtering>
     <includes>
       <include>**/*</include>
     </includes>
   </resource>

   We add a resource directive to our build section to instruct Maven to process the contents of our resources folder, filter any wildcards, and include the result in the generated bundle.

3. Next, we configure the Maven Bundle Plugin as shown in the following code:

   <configuration>
     <instructions>
       <Bundle-SymbolicName>
         ${project.artifactId}
       </Bundle-SymbolicName>
       <Import-Package>*</Import-Package>
       <Private-Package>!*</Private-Package>
       <Export-Package>
         org.apache.karaf.branding
       </Export-Package>
       <Spring-Context>
         *;publish-context:=false
       </Spring-Context>
     </instructions>
   </configuration>

   We configured the Maven Bundle Plugin to export Bundle-SymbolicName as the artifactId and set the Export-Package option to org.apache.karaf.branding. The symbolic name as the project's artifactId variable is a common convention among Karaf bundle developers. We export the Karaf branding package so that the Karaf runtime will identify the bundle as containing the custom branding.

4. The next step is creating our custom branding resource file. Returning to our project, we'll create a branding.properties file in the src/main/resource/org/apache/karaf/branding directory. This .properties file will contain ASCII and Jansi text characters, organized to produce your custom look. Using Maven resource filtering, you can use variable substitutions in the ${variable} format, as shown in the following code:

   ##
   welcome = \
   \u001B[33m\u001B[0m\n\
   \u001B[33m      _       ___  ____    ______  \u001B[0m\n\
   \u001B[33m     / \\    |_  ||_  _|  .' ___  | \u001B[0m\n\
   \u001B[33m    / _ \\     | |_/ /   / .'   \\_| \u001B[0m\n\
   \u001B[33m   / ___ \\    |  __'.   | |        \u001B[0m\n\
   \u001B[33m _/ /   \\ \\_ _| |  \\  \\_ \\ '.___.'\\ \u001B[0m\n\
   \u001B[33m|____| |____||____||____| '.____ .' \u001B[0m\n\
   \u001B[33m                                   \u001B[0m\n\
   \u001B[33m       Apache Karaf Cookbook       \u001B[0m\n\
   \u001B[33m Packt Publishing - http://www.packtpub.com\u001B[0m\n\
   \u001B[33m       (version ${project.version})\u001B[0m\n\
   \u001B[33m\u001B[0m\n\
   \u001B[33mHit '\u001B[1m<tab>\u001B[0m' for a list of available commands\u001B[0m\n\
   \u001B[33mand '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\u001B[0m\n\
   \u001B[33mHit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown\u001B[0m\n\
   \u001B[33m\u001B[0m\n\

   In the preceding code, we use a combination of ASCII characters and Jansi text markup in the branding.properties file to produce simple text effects in Karaf, as shown in the following screenshot:

   
5. The final step is building and deploying our custom branding. We build our branding via the Maven invocation mvn install. After we build our branding bundle, we place a copy inside Karaf's KARAF_HOME/lib folder and then start the container. Upon the first boot, you will see our custom branding displayed.

How it works…

At the first boot, Apache Karaf will check for any bundle in its lib folder and will export the org.apache.karaf.branding package. Upon detection of this resource, it will access the branding.properties file content and display it as part of the runtime startup routine.

There's more…

The Apache Karaf community maintains a web console that may also be branded to reflect your organization's branding. See https://karaf.apache.org/index/subprojects/webconsole.html for more details.