manual/src/main/asciidoc/developer-guide/branding.adoc - karaf - Git at Google

 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //      http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 //

 === Branding

 ==== Console

 You can "brand" the Apache Karaf console.

 By branding, it means that you can define your own:

 * the welcome message (motd or Message Of The Day) displayed when you start the console
 * the prompt displayed to the users

 There are 2 ways of branding the Karaf console:

 . adding a branding.properties file to etc
 . creating a branding bundle.

 ==== Adding a branding.properties file to etc

 Create a `etc/branding.properties` file similar to:

 ----
 welcome = \
 \u001B[36m        __ __                  ____      \u001B[0m\r\n\
 \u001B[36m       / //_/____ __________ _/ __/      \u001B[0m\r\n\
 \u001B[36m      / ,<  / __ `/ ___/ __ `/ /_        \u001B[0m\r\n\
 \u001B[36m     / /| |/ /_/ / /  / /_/ / __/        \u001B[0m\r\n\
 \u001B[36m    /_/ |_|\\__,_/_/   \\__,_/_/         \u001B[0m\r\n\
 \r\n\
 \u001B[1m  Apache Karaf\u001B[0m (4.0.0)\r\n\
 \r\n\
 Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
    and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
 Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown Karaf.\r\n

 prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
 ----

 Start Karaf and you will see your branded Karaf console.

 ==== Branding bundle

 At startup, Apache Karaf is looking for a bundle which exports the `org.apache.karaf.branding` package, containing
 a `branding.properties` file.

 Basically, a branding bundle is a very simple bundle, just containing a `org/apache/karaf/branding/branding.properties`
 file.

 It's easy to create such branding bundle using Apache Maven.

 The following `pom.xml` creates a branding bundle:

 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

     <modelVersion>4.0.0</modelVersion>

     <groupId>your.group.id</groupId>
     <artifactId>your.branding.artifact.id</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>bundle</packaging>
     <name>Your Branding Bundle Name</name>

     <build>
         <plugins>
             <plugin>
                 <groupId>org.apache.felix</groupId>
                 <artifactId>maven-bundle-plugin</artifactId>
                 <version>2.4.0</version>
                 <extensions>true</extensions>
                 <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>*;public-context:=false</Spring-Context>
                     </instructions>
                 </configuration>
             </plugin>
         </plugins>
     </build>

 </project>
 ----

 You can put your `branding.properties` file in the project resources (`src/main/resources/org/apache/karaf/branding/branding.properties`):

 ----
 welcome = This is my Karaf brand\r\n
 prompt = Hey ${USER}>
 ----

 For instance, the default Apache Karaf branding properties file contains:

 ----
 welcome = \
 \u001B[36m        __ __                  ____      \u001B[0m\r\n\
 \u001B[36m       / //_/____ __________ _/ __/      \u001B[0m\r\n\
 \u001B[36m      / ,<  / __ `/ ___/ __ `/ /_        \u001B[0m\r\n\
 \u001B[36m     / /| |/ /_/ / /  / /_/ / __/        \u001B[0m\r\n\
 \u001B[36m    /_/ |_|\\__,_/_/   \\__,_/_/         \u001B[0m\r\n\
 \r\n\
 \u001B[1m  Apache Karaf\u001B[0m (${project.version})\r\n\
 \r\n\
 Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
    and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
 Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n
 ----

 As you can see, the `branding.properties` contains two properties:

 * welcome is the welcome message displayed when you start Apache Karaf console.
 * prompt is the string used to display the console prompt. This string supports variables:
 ** ${USER` defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf",
 however you can override here with your own static user name.
 ** $`APPLICATION` defines the Karaf instance name.

 As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground in bold
 and \u001B[0m switch back to normal.

 Some examples of customized prompt examples follow:

 ----
 # Define a user with fancy colors
 prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m>
 ----

 ----
 # Static sober prompt
 prompt = my-user@my-karaf>
 ----

 ==== Installing the branding bundle

 Thanks to the `pom.xml`, we can use `mvn` to build the branding bundle:

 ----
 mvn install
 ----

 You just have to drop the file in the `lib` directory:

 ----
 cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar
 ----

 You can now start Apache Karaf to see your branded console.

 ==== WebConsole

 It's also possible to brand the Apache Karaf WebConsole.

 You have to create a bundle, fragment of the Apache Karaf WebConsole.

 This WebConsole branding bundle contains a `META-INF/webconsole.properties` containing branding properties:

 ----
 #
 # This file contains branding properties to overwrite the default
 # branding of the Apache Felix Web Console when deployed in an
 # Apache Karaf application.


 webconsole.brand.name = My Web Console

 webconsole.product.name = My Karaf
 webconsole.product.url = http://karaf.apache.org/
 webconsole.product.image = /res/karaf/imgs/logo.png

 webconsole.vendor.name = The Apache Software Foundation
 webconsole.vendor.url = http://www.apache.org
 webconsole.vendor.image = /res/karaf/imgs/logo.png

 webconsole.favicon = /res/karaf/imgs/favicon.ico
 webconsole.stylesheet = /res/karaf/ui/webconsole.css

 ----

 The bundle also provides the css stylesheet and images defined in this properties file.

 As for console, you can use the following `pom.xml` to create the WebConsole branding bundle:

 ----
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

     <modelVersion>4.0.0</modelVersion>

     <groupId>my.group.id</groupId>
     <artifactId>branding</artifactId>
     <packaging>bundle</packaging>

     <build>
         <plugins>
             <plugin>
                 <groupId>org.apache.felix</groupId>
                 <artifactId>maven-bundle-plugin</artifactId>
                 <version>2.4.0</version>
                 <extensions>true</extensions>
                 <configuration>
                     <instructions>
                         <Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL>
                         <Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host>
                         <Export-Package>!*</Export-Package>
                         <Import-Package>
                             javax.servlet;version=2.4,
                             javax.servlet.http;version=2.4,
                             !org.apache.felix.webconsole*,
                             org.apache.aries.blueprint,
                             org.osgi.service.blueprint.container,
                             org.osgi.service.blueprint.reflect,
                             *
                         </Import-Package>
                     </instructions>
                 </configuration>
             </plugin>
         </plugins>
     </build>

 </project>
 ----

 With the `webconsole` feature installed, you can install this bundle (using `bundle:install` or by editing the
 `etc/startup.properties`), you will see the WebConsole with your branding.
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	//

	=== Branding

	==== Console

	You can "brand" the Apache Karaf console.

	By branding, it means that you can define your own:

	* the welcome message (motd or Message Of The Day) displayed when you start the console
	* the prompt displayed to the users

	There are 2 ways of branding the Karaf console:

	. adding a branding.properties file to etc
	. creating a branding bundle.

	==== Adding a branding.properties file to etc

	Create a `etc/branding.properties` file similar to:

	----
	welcome = \
	\u001B[36m __ __ ____ \u001B[0m\r\n\
	\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
	\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\
	\u001B[36m / /\| \|/ /_/ / / / /_/ / __/ \u001B[0m\r\n\
	\u001B[36m /_/ \|_\|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\
	\r\n\
	\u001B[1m Apache Karaf\u001B[0m (4.0.0)\r\n\
	\r\n\
	Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
	and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
	Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown Karaf.\r\n

	prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
	----

	Start Karaf and you will see your branded Karaf console.

	==== Branding bundle

	At startup, Apache Karaf is looking for a bundle which exports the `org.apache.karaf.branding` package, containing
	a `branding.properties` file.

	Basically, a branding bundle is a very simple bundle, just containing a `org/apache/karaf/branding/branding.properties`
	file.

	It's easy to create such branding bundle using Apache Maven.

	The following `pom.xml` creates a branding bundle:

	----
	<?xml version="1.0" encoding="UTF-8"?>
	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<groupId>your.group.id</groupId>
	<artifactId>your.branding.artifact.id</artifactId>
	<version>1.0-SNAPSHOT</version>
	<packaging>bundle</packaging>
	<name>Your Branding Bundle Name</name>

	<build>
	<plugins>
	<plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<version>2.4.0</version>
	<extensions>true</extensions>
	<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>*;public-context:=false</Spring-Context>
	</instructions>
	</configuration>
	</plugin>
	</plugins>
	</build>

	</project>
	----

	You can put your `branding.properties` file in the project resources (`src/main/resources/org/apache/karaf/branding/branding.properties`):

	----
	welcome = This is my Karaf brand\r\n
	prompt = Hey ${USER}>
	----

	For instance, the default Apache Karaf branding properties file contains:

	----
	welcome = \
	\u001B[36m __ __ ____ \u001B[0m\r\n\
	\u001B[36m / //_/____ __________ _/ __/ \u001B[0m\r\n\
	\u001B[36m / ,< / __ `/ ___/ __ `/ /_ \u001B[0m\r\n\
	\u001B[36m / /\| \|/ /_/ / / / /_/ / __/ \u001B[0m\r\n\
	\u001B[36m /_/ \|_\|\\__,_/_/ \\__,_/_/ \u001B[0m\r\n\
	\r\n\
	\u001B[1m Apache Karaf\u001B[0m (${project.version})\r\n\
	\r\n\
	Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
	and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
	Hit '\u001B[1m<ctrl-d>\u001B[0m' or type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n
	----

	As you can see, the `branding.properties` contains two properties:

	* welcome is the welcome message displayed when you start Apache Karaf console.
	* prompt is the string used to display the console prompt. This string supports variables:
	** ${USER` defines the user name of the prompt. Caveat -- the user name is presently static and hardcoded to "karaf",
	however you can override here with your own static user name.
	** $`APPLICATION` defines the Karaf instance name.

	As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground in bold
	and \u001B[0m switch back to normal.

	Some examples of customized prompt examples follow:

	----
	# Define a user with fancy colors
	prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m>
	----

	----
	# Static sober prompt
	prompt = my-user@my-karaf>
	----

	==== Installing the branding bundle

	Thanks to the `pom.xml`, we can use `mvn` to build the branding bundle:

	----
	mvn install
	----

	You just have to drop the file in the `lib` directory:

	----
	cp branding.jar /opt/apache-karaf-4.0.0/lib/karaf-branding.jar
	----

	You can now start Apache Karaf to see your branded console.

	==== WebConsole

	It's also possible to brand the Apache Karaf WebConsole.

	You have to create a bundle, fragment of the Apache Karaf WebConsole.

	This WebConsole branding bundle contains a `META-INF/webconsole.properties` containing branding properties:

	----
	#
	# This file contains branding properties to overwrite the default
	# branding of the Apache Felix Web Console when deployed in an
	# Apache Karaf application.


	webconsole.brand.name = My Web Console

	webconsole.product.name = My Karaf
	webconsole.product.url = http://karaf.apache.org/
	webconsole.product.image = /res/karaf/imgs/logo.png

	webconsole.vendor.name = The Apache Software Foundation
	webconsole.vendor.url = http://www.apache.org
	webconsole.vendor.image = /res/karaf/imgs/logo.png

	webconsole.favicon = /res/karaf/imgs/favicon.ico
	webconsole.stylesheet = /res/karaf/ui/webconsole.css

	----

	The bundle also provides the css stylesheet and images defined in this properties file.

	As for console, you can use the following `pom.xml` to create the WebConsole branding bundle:

	----
	<?xml version="1.0" encoding="UTF-8"?>
	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<groupId>my.group.id</groupId>
	<artifactId>branding</artifactId>
	<packaging>bundle</packaging>

	<build>
	<plugins>
	<plugin>
	<groupId>org.apache.felix</groupId>
	<artifactId>maven-bundle-plugin</artifactId>
	<version>2.4.0</version>
	<extensions>true</extensions>
	<configuration>
	<instructions>
	<Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL>
	<Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host>
	<Export-Package>!*</Export-Package>
	<Import-Package>
	javax.servlet;version=2.4,
	javax.servlet.http;version=2.4,
	!org.apache.felix.webconsole*,
	org.apache.aries.blueprint,
	org.osgi.service.blueprint.container,
	org.osgi.service.blueprint.reflect,
	*
	</Import-Package>
	</instructions>
	</configuration>
	</plugin>
	</plugins>
	</build>

	</project>
	----

	With the `webconsole` feature installed, you can install this bundle (using `bundle:install` or by editing the
	`etc/startup.properties`), you will see the WebConsole with your branding.