manual/src/main/asciidoc/user-guide/installation.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.
 //

 === Installation

 Apache Karaf is a lightweight container, that is very easy to install and administer, on both Unix and Windows platforms.

 ==== Requirements

 *Hardware:*

 * 50 MB of free disk space for the Apache Karaf binary distribution.

 *Operating Systems:*

 * Windows: Windows 8, Windows 7, Windows 2003, Windows Vista, Windows XP SP2, Windows 2000.
 * Unix: RedHat Enterprise Linux, Debian, SuSE/OpenSuSE, CentOS, Fedora, Ubuntu, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.

 *Environment:*

 * Java SE 1.8 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,

 ==== Using Apache Karaf binary distributions

 Apache Karaf is available in two distributions, both as a tar.gz and zip archives.

 The "default" distribution is a "ready to use" distribution, with pre-installed features.

 The "minimal" distribution is like the minimal distributions that you can find for most of the Unix distributions.
 Only the core layer is packaged, most of the features and bundles are downloaded from Internet at bootstrap.
 It means that Apache Karaf minimal distribution requires an Internet connection to start correctly.
 The features provided by the "minimal" distribution are exactly the same as in the "default" distribution, the difference
 is that the minimal distribution will download the features from Internet.

 ===== Installation on Windows platform

 [NOTE]
 ====
 The JAVA_HOME environment variable has to be correctly defined. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables".
 ====

 . From a browser, navigate to http://karaf.apache.org/download.html.
 . Download Apache Karaf binary distribution in the zip format: `apache-karaf-4.0.0.zip`.
 . Extract the files from the zip file into a directory of your choice (it's the `KARAF_HOME`).

 [NOTE]
 ====
 Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
 ====

 [NOTE]
 ====
 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

 ----
 subst S: "C:\your very % problematic path!\KARAF"
 ----

 so your Karaf root directory is S: --- which works for sure and is short to type.
 ====

 ===== Installation on Unix platforms

 [NOTE]
 ====
 The JAVA_HOME environment variable has to be correctly defined. Check the current value using

 ----
 echo $JAVA_HOME
 ----

 If it's not correct, fix it using:

 ----
 export JAVA_HOME=....
 ----
 ====

 . From a browser, navigate to http://karaf.apache.org/download.html.
 . Download Apache Karaf binary distribution in the tar.gz format: `apache-karaf-4.0.0.tar.gz`.
 . Extract the files from the tar.gz file into a directory of your choice (it's the `KARAF_HOME`). For example:

 ----
 tar zxvf apache-karaf-4.0.0.tar.gz
 ----

 [NOTE]
 ====
 Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
 ====

 ====== Installation on Debian GNU/linux

 There is an unofficial debian package of karaf:

 . Add the key of the unofficial debian archive containing karaf
 +
 ----
 wget -O - https://apt.bang.priv.no/apt_pub.gpg | apt-key add -
 ----
 . Open /etc/apt/sources.list in a text editor and add the following lines:
 +
 ----
 # Unofficial APT archive for apache karaf
 deb http://apt.bang.priv.no/public stable main
 ----
 . Update the APT package index and install the package
 +
 ----
 apt-get update
 apt-get install openjdk-8-jdk karaf
 ----

 The installed karaf will run as user karaf, group karaf, listening to the usual default karaf ports, be started with systemd, with KARAF_ETC in /etc/karaf and KARAF_DATA in /var/lib/karaf/data.


 [NOTE]
 ====
 When/if the link:++https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881297++[Debian Request For Package (RFP) of karaf] results in an official karaf package becoming available, the unofficial debian package will be discontinued.
 ====

 ==== 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 Apache 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 8 installation.

 By default, all Apache Karaf files are "gathered" in one directory: `KARAF_HOME`.

 You can define your own directory layout, by using some Karaf environment variables:

 * `KARAF_DATA` is the location of the data folder, where Karaf stores temporary files.
 * `KARAF_ETC` is the location of the etc folder, where Karaf stores configuration files.
 * `KARAF_BASE` is the Karaf base folder. By default `KARAF_BASE` is the same as `KARAF_HOME`.

 ==== Building from Sources

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

 *Hardware:*

 * 500 MB of free disk space for the Apache Karaf source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.

 *Environment:*

 * Java SE Development Kit 1.8 or greater (http://www.oracle.com/technetwork/java/javase/).
 * Apache Maven 3.5.0 or greater (http://maven.apache.org/download.html).

 ===== Building on Windows platform

 You can get the Apache Karaf sources from:

 * the sources distribution `apache-karaf-4.0.0-src.zip` available at http://karaf.apache.org/download.html. Extract the files in the directory of your choice.
 * by checking out the git repository:

 ----
 git clone https://github.com/apache/karaf karaf
 ----

 Use Apache Maven to build Apache Karaf:

 ----
 mvn clean install
 ----

 [NOTE]
 ====
 You can speed up the build by bypassing the unit tests:

 ----
 mvn clean install -DskipTests
 ----
 ====

 Now, you can find the built binary distribution in `assemblies\apache-karaf\target\apache-karaf-4.0.0.zip`.

 ===== Building on Unix platforms

 You can get the Apache Karaf sources from:

 * the sources distribution `apache-karaf-4.0.0-src.tar.gz` available at http://karaf.apache.org/download.html. Extract the files in the directory of your choice.
 * by checking out the git repository:

 ----
 git clone https://github.com/apache/karaf karaf
 ----

 Use Apache Maven to build Apache Karaf:

 ----
 mvn clean install
 ----

 [NOTE]
 ====
 You can speed up the build by bypassing the unit tests:

 ----
 mvn clean install -DskipTests
 ----
 ====

 Now, you can find the built binary distribution in `assemblies/apache-karaf/target/apache-karaf-4.0.0.tar.gz`.
	//
	// 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.
	//

	=== Installation

	Apache Karaf is a lightweight container, that is very easy to install and administer, on both Unix and Windows platforms.

	==== Requirements

	Hardware:

	* 50 MB of free disk space for the Apache Karaf binary distribution.

	Operating Systems:

	* Windows: Windows 8, Windows 7, Windows 2003, Windows Vista, Windows XP SP2, Windows 2000.
	* Unix: RedHat Enterprise Linux, Debian, SuSE/OpenSuSE, CentOS, Fedora, Ubuntu, MacOS, AIX, HP-UX, Solaris, any Unix platform that supports Java.

	Environment:

	* Java SE 1.8 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,

	==== Using Apache Karaf binary distributions

	Apache Karaf is available in two distributions, both as a tar.gz and zip archives.

	The "default" distribution is a "ready to use" distribution, with pre-installed features.

	The "minimal" distribution is like the minimal distributions that you can find for most of the Unix distributions.
	Only the core layer is packaged, most of the features and bundles are downloaded from Internet at bootstrap.
	It means that Apache Karaf minimal distribution requires an Internet connection to start correctly.
	The features provided by the "minimal" distribution are exactly the same as in the "default" distribution, the difference
	is that the minimal distribution will download the features from Internet.

	===== Installation on Windows platform

	[NOTE]
	====
	The JAVA_HOME environment variable has to be correctly defined. To accomplish that, press Windows key and Break key together, switch to "Advanced" tab and click on "Environment Variables".
	====

	. From a browser, navigate to http://karaf.apache.org/download.html.
	. Download Apache Karaf binary distribution in the zip format: `apache-karaf-4.0.0.zip`.
	. Extract the files from the zip file into a directory of your choice (it's the `KARAF_HOME`).

	[NOTE]
	====
	Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
	====

	[NOTE]
	====
	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

	----
	subst S: "C:\your very % problematic path!\KARAF"
	----

	so your Karaf root directory is S: --- which works for sure and is short to type.
	====

	===== Installation on Unix platforms

	[NOTE]
	====
	The JAVA_HOME environment variable has to be correctly defined. Check the current value using

	----
	echo $JAVA_HOME
	----

	If it's not correct, fix it using:

	----
	export JAVA_HOME=....
	----
	====

	. From a browser, navigate to http://karaf.apache.org/download.html.
	. Download Apache Karaf binary distribution in the tar.gz format: `apache-karaf-4.0.0.tar.gz`.
	. Extract the files from the tar.gz file into a directory of your choice (it's the `KARAF_HOME`). For example:

	----
	tar zxvf apache-karaf-4.0.0.tar.gz
	----

	[NOTE]
	====
	Remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
	====

	====== Installation on Debian GNU/linux

	There is an unofficial debian package of karaf:

	. Add the key of the unofficial debian archive containing karaf
	+
	----
	wget -O - https://apt.bang.priv.no/apt_pub.gpg \| apt-key add -
	----
	. Open /etc/apt/sources.list in a text editor and add the following lines:
	+
	----
	# Unofficial APT archive for apache karaf
	deb http://apt.bang.priv.no/public stable main
	----
	. Update the APT package index and install the package
	+
	----
	apt-get update
	apt-get install openjdk-8-jdk karaf
	----

	The installed karaf will run as user karaf, group karaf, listening to the usual default karaf ports, be started with systemd, with KARAF_ETC in /etc/karaf and KARAF_DATA in /var/lib/karaf/data.



	[NOTE]
	====
	When/if the link:++https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881297++[Debian Request For Package (RFP) of karaf] results in an official karaf package becoming available, the unofficial debian package will be discontinued.
	====

	==== 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 Apache 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 8 installation.

	By default, all Apache Karaf files are "gathered" in one directory: `KARAF_HOME`.

	You can define your own directory layout, by using some Karaf environment variables:

	* `KARAF_DATA` is the location of the data folder, where Karaf stores temporary files.
	* `KARAF_ETC` is the location of the etc folder, where Karaf stores configuration files.
	* `KARAF_BASE` is the Karaf base folder. By default `KARAF_BASE` is the same as `KARAF_HOME`.

	==== Building from Sources

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

	Hardware:

	* 500 MB of free disk space for the Apache Karaf source distributions or SVN checkout, the Maven build and the dependencies Maven downloads.

	Environment:

	* Java SE Development Kit 1.8 or greater (http://www.oracle.com/technetwork/java/javase/).
	* Apache Maven 3.5.0 or greater (http://maven.apache.org/download.html).

	===== Building on Windows platform

	You can get the Apache Karaf sources from:

	* the sources distribution `apache-karaf-4.0.0-src.zip` available at http://karaf.apache.org/download.html. Extract the files in the directory of your choice.
	* by checking out the git repository:

	----
	git clone https://github.com/apache/karaf karaf
	----

	Use Apache Maven to build Apache Karaf:

	----
	mvn clean install
	----

	[NOTE]
	====
	You can speed up the build by bypassing the unit tests:

	----
	mvn clean install -DskipTests
	----
	====

	Now, you can find the built binary distribution in `assemblies\apache-karaf\target\apache-karaf-4.0.0.zip`.

	===== Building on Unix platforms

	You can get the Apache Karaf sources from:

	* the sources distribution `apache-karaf-4.0.0-src.tar.gz` available at http://karaf.apache.org/download.html. Extract the files in the directory of your choice.
	* by checking out the git repository:

	----
	git clone https://github.com/apache/karaf karaf
	----

	Use Apache Maven to build Apache Karaf:

	----
	mvn clean install
	----

	[NOTE]
	====
	You can speed up the build by bypassing the unit tests:

	----
	mvn clean install -DskipTests
	----
	====

	Now, you can find the built binary distribution in `assemblies/apache-karaf/target/apache-karaf-4.0.0.tar.gz`.