karaf-2.2.x/manual/src/main/webapp/users-guide/installation.conf

h1. Installation

This chapter describes how to install Apache Karaf for both Unix and Windows platforms, including
prerequisite software and necessary download links.

h2. Pre-Installation Requirements

*Hardware:*
* 20 MB of free disk space for the Apache Karaf x.y binary distribution.

*Operating Systems:*
* Windows: Windows Vista, Windows XP SP2, Windows 2000.
* Unix: Ubuntu Linux, Powerdog Linux, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.

*Environment:*
* Java SE Development Kit 1.5.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
* The JAVA_HOME environment variable must be set to the directory where the Java runtime is installed, e.g., {{c:\Program Files\jdk.1.5.0_06}}. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables". Here, check for the variable and, if necessary, add it.

h2. Building from Sources

If you intend to build Karaf from the sources, the requirements are a bit different:

*Hardware:*
* 200 MB of free disk space for the Apache Karaf x.y source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.

*Environment:*
* Java SE Developement Kit 1.5.x or greater ([http://www.oracle.com/technetwork/java/javase/]).
* Apache Maven 2.2.1 ([http://maven.apache.org/download.html]).

h3. Building on Windows

This procedure explains how to download and install the source distribution on a Windows system. *NOTE:* Karaf requires Java 5 is compile, build and run.
# From a browser, navigate to [http://karaf.apache.org/index/community/download.html].
# Scroll down to the "Apache Karaf" section and select the desired distribution.
For a source distribution, the filename will be similar to: {{apache-karaf-x.y-src.zip}}.
# Extract Karaf from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
# {anchor:Windows Source Installation} Build Karaf using Maven 2.2.1 or greater and Java 5.
The recommended method of building Karaf is the following:
{code}
cd [karaf_install_dir]\src
{code}
 where {{\[karaf_install_dir\]}} is the directory in which Karaf was installed.
{code}
mvn
{code}
Both steps take around 10 to 15 minutes.
# Unzip the distribution using your favorite zip tool. The windows distribution is available at
{code}
[karaf_install_dir]\assembly\target\apache-karaf-x.y.zip
{code}
# Proceed to the [Starting Karaf|start-stop#Starting Karaf] chapter.

h3. Building on Unix

This procedure explains how to download and install the source distribution on a Unix system. This procedure assumes the Unix machine has a browser. Please see the previous [#Unix Binary Installation] section for ideas on how to install Karaf without a browser. *NOTE:* Karaf requires Java 5 to compile, build and run.
# From a browser, navigate to [http://karaf.apache.org/download.html].
# Scroll down to the "Apache Karaf" section and select the desired distribution.
For a source distribution, the filename will be similar to: {{apache-karaf-x.y-src.tar.gz}}.
# Extract the files from the ZIP file into a directory of your choice. For example:
{code}
gunzip apache-karaf-x.y-src.tar.gz
tar xvf apache-karaf-x.y-src.tar
{code}
Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
# Build Karaf using Maven:
The preferred method of building Karaf is the following:
{code}
cd [karaf_install_dir]/src
{code}
 where \[karaf_install_dir\] is the directory in which Karaf was installed.
{code}
mvn
{code}
# Uncompress the distribution that has just been created
{code}
cd [karaf_install_dir]/assembly/target
gunzip apache-karaf-x.y.tar.gz
tar xvf apache-karaf-x.y.tar
{code}
# Proceed to the [Starting Karaf|start-stop#Starting Karaf] chapter.

h2. Installation Procedure for Windows

This procedure explains how to download and install the binary distribution on a Windows system.
# From a browser, navigate to [http://karaf.apache.org/index/community/download.html].
# Scroll down to the "Apache Karaf" section and select the desired distribution.
For a binary distribution, the filename will be similar to: {{apache-karaf-x.y.zip}}.
# Extract the files from the ZIP file into a directory of your choice. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
# Proceed to the [Starting Karaf|start-stop#Starting Karaf] chapter.
# Optional: see [enabling Colorized Console Output On Windows|colorized-console]

{tip:title=Handy Hint}
In case you have to install Karaf into a very deep path or a path containing illegal characters for Java paths, e.g. \!, % etc., you may add a bat file to _start \-> startup_ that executes
{noformat}
subst S: "C:\your very % problematic path!\KARAF"
{noformat}
so your Karaf root directory is S: --- which works for sure and is short to type.
{tip}

h2. Installation Procedure For Unix

This procedure explains how to download and install the binary distribution on a Unix system.
# From a browser, navigate to [http://karaf.apache.org/download.html].
# Scroll down to the "Apache Karaf" section and select the desired distribution.
For a binary Unix distribution, the filename will be similar to: apache-karaf-x.y.tar.gz.
# Extract the files from the gzip file into a directory of your choice. For example:
{code}
gunzip apache-karaf-x.y.tar.gz
tar xvf apache-karaf-x.y.tar
{code}
Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
# Proceed to the [Starting Karaf|start-stop#Starting Karaf] chapter.

h2. Post-Installation steps

Thought it is not always required, it is strongly advised to set up the {{JAVA_HOME}} environment property to point to the JDK you want Karaf to use before starting it.
This property is used to locate the {{java}} executable and should be configured to point to the home directory of the Java SE 5 or 6 installation.