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
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".
Note
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.
Tip
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 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 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.
Tip
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.
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 book, we will be focusing on Apache Karaf 2.3.x with notes upon the 3.0.x release series.
Tip
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 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-<version>.zip
The following command is used in Unix:
tar –zxf apache-karaf-<version>.tar.gz
After extraction, the following folder structure will be present:
The
LICENSE,NOTICE,README, andRELEASE-NOTESfiles are plain text artifacts contained in each Karaf distribution. TheRELEASE-NOTESfiles are of particular interest, as upon each major and minor release of Karaf, this file is updated with a list of changes.The
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.The
datafolder is home to Karaf's logfiles, bundle cache, and various other persistent data.The
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.The
instancesfolder will be created when you use Karaf child instances. It stores the child instance folders and files.The
deployfolder is monitored for hot deployment of artifacts into the running container. In Chapter 5, Deploying Applications, we will explore this feature in depth.The
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.
The
libfolder contains the core libraries required for Karaf to boot upon a JVM.The
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 bin directory:
On Windows, use the following command:
bin\karaf.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:
[email protected]> shutdown –f
The inclusion of the –f or –-force flag to the shutdown command instructs Karaf to skip asking for confirmation of container shutdown.
