blob: c45f773c518d096299d0091e06494ee1b8f68ab2 [file] [log] [blame]
h1. 1. Quick Start
If you are in a hurry to have Apache Karaf up and running right away, this section will provide you with some basic steps for downloading, building (when needed) and running the server in no time. This is clearly not a complete guide so you may want to check other sections of this guide for further information.
All you need is 5 to 10 minutes and to follow these basic steps.
* Background
* Getting the software
* Start the server
* Deploy a sample application
h2. Background
Apache Karaf is a small and lightweight OSGi based runtime. This provides a small lightweight container onto which various bundles can be deployed.
Apache Karaf started life as the [Apache ServiceMix|http://servicemix.apache.org] kernel and then moved as a [Apache Felix|http://felix.apache.org] subproject before becoming a top level project.
h2. Getting the software
At this time you have one option to get the software. The fastest and easiest way is to get the binary directly from the Apache site. Since this article is intended to help you to have Apache Karaf up and running in the fastest way only the binary download will be covered at this time.
h3. Prerequisites
Although this installation path is the fastest one, you will still need to install some software before installing Karaf.
Karaf requires a Java SE 5 environment to run. Refer to [http://www.oracle.com/technetwork/java/javase/] for details on how to download and install Java SE 1.5 or greater.
h3. Download binaries
You will need to select the appropriate installation image for the platform you're using to run Karaf. Open a Web browser and access the following URL, there you will find the available packages for download (binaries and source code).
[http://karaf.apache.org/index/community/download.html]
Select the file compression format compatible with your system (zip for windows, tar.gz for unixes) by clicking directly on the link, download it and expand the binary to your hard drive in a new directory; for example in z:\karaf - from now on this directory will be referenced as <KARAF_HOME>. Please remember the restrictions concerning illegal characters in Java paths, e.g. \!, % etc.
The installation of Karaf is as simple as uncompressing the .zip or .tar.gz files. The next step is to start the server.
h2. Start the server
With Karaf already installed, open a command line console and change directory to <KARAF_HOME>. To start the server, run the following command in Windows:
{code}
bin\karaf.bat
{code}
respectively on Unix:
{code}
bin/karaf
{code}
You should see the following information on the command line console:
{include:Karaf welcome screen}
You can now run your first command. Simply type the {{<tab>}} key in the console.
{code:borderStyle=solid}
karaf@root>
admin:change-port admin:connect admin:create admin:destroy
admin:list admin:start admin:stop config:cancel
config:edit config:list config:propappend config:propdel
config:proplist config:propset config:update dev:dynamic-import
dev:framework dev:print-stack-traces dev:show-tree features:addUrl
features:info features:install features:list features:listUrl
features:refreshUrl features:removeUrl features:uninstall log:display
log:display-exception log:get log:set osgi:bundle-level
osgi:headers osgi:install osgi:list osgi:ls
osgi:refresh osgi:resolve osgi:restart osgi:shutdown
osgi:start osgi:start-level osgi:stop osgi:uninstall
osgi:update packages:exports packages:imports shell:cat
shell:clear shell:each shell:echo shell:exec
shell:grep shell:history shell:if shell:info
shell:java shell:logout shell:new shell:printf
shell:sleep shell:sort shell:tac ssh:ssh
ssh:sshd cat clear each
echo exec grep history
if info java logout
new printf sleep sort
tac bundle-level headers install
list ls refresh resolve
restart shutdown start start-level
stop uninstall update
karaf@root>
{code}
You can then grab more specific help for a given command using the {{--help}} option for this command:
{code:borderStyle=solid}
karaf@root> admin:create --help
DESCRIPTION
admin:create
Create a new instance.
SYNTAX
admin:create [options] name
ARGUMENTS
name
The name of the new container instance
OPTIONS
--help
Display this help message
-f, --feature
Initial features. This option can be specified multiple times to enable multiple initial
features
-p, --port
Port number for remote shell connection
-l, --location
Location of the new container instance in the file system
-furl, --featureURL
Additional feature descriptor URLs. This option can be specified multiple times to add
multiple URLs
karaf@root>
{code}
Note that the console supports tab completion, so you just need to enter {{ad <tab> cr <tab>}} instead of {{admin:create}}.
h2. Deploy a sample application
While you will learn in the Karaf user's guide how to fully use and leverage Apache Karaf, let's install a sample [Apache Camel|http://camel.apache.org] application for now:
In the console, run the following commands:
{code}
features:addurl mvn:org.apache.camel/camel-example-osgi/2.10.0/xml/features
features:install camel-example-osgi
{code}
The example installed is using Camel to start a timer every 2 seconds and output a message on the console.
The previous commands download the Camel features descriptor and install the example feature.
{code}
>>>> SpringDSL set body: Fri Jan 07 11:59:51 CET 2011
>>>> SpringDSL set body: Fri Jan 07 11:59:53 CET 2011
>>>> SpringDSL set body: Fri Jan 07 11:59:55 CET 2011
{code}
h3. Stopping and uninstalling the sample application
To stop this demo, run the following command:
{code}
features:uninstall camel-example-osgi
{code}
h3. Common Problems
# Launching Karaf can result in a deadlock in Felix during module dependency resolution.
This is often a result of sending a SIGINT (control-C) to the process when it will not cleanly exit.
This can corrupt the caches and cause startup problems in the very next launch. It is fixed by emptying the component cache:
{code}
rm -rf data/cache/*
{code}
h2. Stopping Karaf
To stop Karaf from the console, enter {{^D}} in the console:
{code}
^D
{code}
Alternatively, you can also run the following command:
{code}
system:shutdown
{code}
h2. Summary
This document showed how simple it is to have Apache Karaf up and running. The overall time for getting the server running should be less than five
minutes if you have the prerequisite (Java 1.5) already installed. Additionally, this article also showed you how to deploy and test a simple
Apache Camel application.