| // |
| // 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`. |