Before Apache Karaf can provide you with an OSGi-based container runtime, we'll have to set up our environment first. The process is quick, requiring a minimum of normal Java usage integration work.

In this article we'll review:

• The prerequisites for Apache Karaf
• Obtaining Apache Karaf
• Installing Apache Karaf and running it for the first time

Prerequisites

As a lightweight container, Apache Karaf has sparse system requirements. You will need to check that you have all of the below specifications met or exceeded:

• Operating System: Apache Karaf requires recent versions of Windows, AIX, Solaris, HP-UX, and various Linux distributions (RedHat, Suse, Ubuntu, and so on).
• Disk space: It requires at least 20 MB free disk space. You will require more free space as additional resources are provisioned into the container. As a rule of thumb, you should plan to allocate 100 to 1000 MB of disk space for logging, bundle cache, and repository.
• Memory: At least 128 MB memory is required; however, more than 2 GB is recommended.
• Java Runtime Environment (JRE): The runtime environments such as JRE 1.6 or JRE 1.7 are required. The location of the JRE should be made available via environment setting JAVA_HOME. At the time of writing, Java 1.6 is "end of life".

For our demos we'll use Apache Maven 3.0.x and Java SDK 1.7.x; these tools should be obtained for future use. However, they will not be necessary to operate the base Karaf installation. Before attempting to build demos, please set the MAVEN_HOME environment variable to point towards your Apache Maven distribution.

After verifying you have the above prerequisite hardware, operating system, JVM, and other software packages, you will have to set up your environment variables for JAVA_HOME and MAVEN_HOME. Both of these will be added to the system PATH.

Setting up JAVA_HOME Environment Variable

Apache Karaf honors the setting of JAVA_HOME in the system environment; if this is not set, it will pick up and use Java from PATH.

For users unfamiliar with setting environment variables, the following batch setup script will set up your windows environment:

@echo off REM execute setup.bat to setup environment variables. set JAVA_HOME=C:Program FilesJavajdk1.6.0_31 set MAVEN_HOME=c:x1apache-maven-3.0.4 set PATH=%JAVA_HOME%bin;%MAVEN_HOME%bin;%PATH%echo %PATH%

The script creates and sets the JAVA_HOME and MAVEN_HOME variables to point to their local installation directories, and then adds their values to the system PATH. The initial echo off directive reduces console output as the script executes; the final echo command prints the value of PATH.

Managing Windows System Environment Variables

Windows environment settings can be managed via the Systems Properties control panel. Access to these controls varies according to the Windows release.

Conversely, in a Unix-like environment, a script similar to the following one will set up your environment:

# execute setup.sh to setup environment variables. JAVA_HOME=/path/to/jdk1.6.0_31 MAVEN_HOME=/path/to/apache-maven-3.0.4 PATH=$JAVA_HOME/bin:$MAVEN_HOME/bin:$PATH export PATH JAVA_HOME MAVEN_HOME echo $PATH

The first two directives create and set the JAVA_HOME and MAVEN_HOME environment variables, respectively. These values are added to the PATH setting, and then made available to the environment via the export command.

Obtaining Apache Karaf distribution

As an Apache open source project, Apache Karaf is made available in both binary and source distributions. The binary distribution comes in a Linux-friendly, GNU-compressed archive and in Windows ZIP format. Your selection of distribution kit will affect which set of scripts are available in Karaf's bin folder. So, if you're using Windows, select the ZIP file; on Unix-like systems choose the tar.gz file.

Apache Karaf distributions may be obtained from http://karaf.apache.org/index/community/download.html. The following screenshot shows this link:

The primary download site for Apache Karaf provides a list of available mirror sites; it is advisable that you select a server nearer to your location for faster downloads. For the purposes of this article, we will be focusing on Apache Karaf 2.3.x with notes upon the 3.0.x release series.

Apache Karaf 2.3.x versus 3.0.x series

The major difference between Apache Karaf 2.3 and 3.0 lines is the core OSGi specification supported. Karaf 2.3 utilizes OSGi rev4.3, while Karaf 3.0 uses rev5.0. Karaf 3 also introduces several command name changes. There are a multitude of other internal differences between the code bases, and wherever appropriate, we'll highlight those changes that impact users throughout this text.

Installing Apache Karaf

The installation of Apache Karaf only requires you to extract the tar.gz or .zip file in your desired target folder destination.

The following command is used in Windows:

unzip apache-karaf-.zip

The following command is used in Unix:

tar –zxf apache-karaf-.tar.gz

After extraction, the following folder structure will be present:

• The LICENSE, NOTICE, README, and RELEASE-NOTES files are plain text artifacts contained in each Karaf distribution. The RELEASE-NOTES files are of particular interest, as upon each major and minor release of Karaf, this file is updated with a list of changes.
• The LICENSE, NOTICE, README, and RELEASE-NOTES files are plain text artifacts contained in each Karaf distribution. The RELEASE-NOTES files are of particular interest, as upon each major and minor release of Karaf, this file is updated with a list of changes.
• The bin folder contains the Karaf scripts for the interactive shell (Karaf), starting and stopping background Karaf service, a client for connecting to running Karaf instances, and additional utilities.
• The data folder is home to Karaf's logfiles, bundle cache, and various other persistent data.
• The demos folder contains an assortment of sample projects for Karaf. It is advisable that new users explore these examples to gain familiarity with the system. For the purposes of this book we strived to create new sample projects to augment those existing in the distribution.
• The instances folder will be created when you use Karaf child instances. It stores the child instance folders and files.
• The deploy folder is monitored for hot deployment of artifacts into the running container.
• The etc folder contains the base configuration files of Karaf; it is also monitored for dynamic configuration updates to the configuration admin service in the running container.
• An HTML and PDF format copy of the Karaf manual is included in each kit.
• The lib folder contains the core libraries required for Karaf to boot upon a JVM.
• The system folder contains a simple repository of dependencies Karaf requires for operating at runtime. This repository has each library jar saved under a Maven-style directory structure, consisting of the library Maven group ID, artifact ID, version, artifact ID-version, any classifier, and extension.

First boot!

After extracting the Apache Karaf distribution kit and setting our environment variables, we are now ready to start up the container. The container can be started by invoking the Karaf script provided in the bin directory:

On Windows, use the following command:

binkaraf.bat

On Unix, use the following command:

./bin/karaf

The following image shows the first boot screen:

Congratulations, you have successfully booted Apache Karaf! To stop the container, issue the following command in the console:

karaf@root> shutdown –f

The inclusion of the –for –-force flag to the shutdown command instructs Karaf to skip asking for confirmation of container shutdown.

Pressing Ctrl+ D will shut down Karaf when you are on the shell; however, if you are connected remotely (using SSH), this action will just log off the SSH session, it won't shut down Karaf.

Summary

We have discovered the prerequisites for installing Karaf, which distribution to obtain, how to install the container, and finally how to start it.

Resources for Article:

• Apache Felix Gogo [Article]
• WordPress 3 Security: Apache Modules [Article]
• Configuring Apache and Nginx [Article]