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 chapter we'll review:
The prerequisites for Apache Karaf
Obtaining Apache Karaf
Installing Apache Karaf and running it for the first time
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
MAVEN_HOME. Both of these will be added to the system
Setting up JAVA_HOME Environment Variable
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 Files\Java\jdk1.6.0_31 set MAVEN_HOME=c:\x1\apache-maven-3.0.4 set PATH=%JAVA_HOME%\bin;%MAVEN_HOME%\bin;%PATH%echo %PATH%
The script creates and sets the
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
Managing Windows System Environment Variables
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
MAVEN_HOME environment variables, respectively. These values are added to the
PATH setting, and then made available to the environment via the
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
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 book, 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.
The following command is used in Windows:
The following command is used in Unix:
tar –zxf apache-karaf-<version>.tar.gz
After extraction, the following folder structure will be present:
RELEASE-NOTESfiles are plain text artifacts contained in each Karaf distribution. The
RELEASE-NOTESfiles are of particular interest, as upon each major and minor release of Karaf, this file is updated with a list of changes.
binfolder 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. These scripts will be described in later chapters.
demosfolder 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.
deployfolder is monitored for hot deployment of artifacts into the running container. In Chapter 5, Deploying Applications, we will explore this feature in depth.
etcfolder contains the base configuration files of Karaf; it is also monitored for dynamic configuration updates to the configuration admin service in the running container. Karaf configuration details will be explored in Chapter 3, System Configuration and Tuning.
An HTML and PDF format copy of the Karaf manual is included in each kit.
systemfolder 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.
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
On Windows, use the following command:
On Unix, use the following command:
The following image shows the first boot screen:
[email protected]> shutdown –f
The inclusion of the
–-force flag to the shutdown command instructs Karaf to skip asking for confirmation of container shutdown.