Get started with Apache Karaf is very easy!

Easy to install

The only prerequisite to start with Karaf is a Java SE 8 / 9 / 10 / 11 environment to run. Refer to https://www.oracle.com/technetwork/java/javase for details on how to download and install Java SE 1.8 or greater.

Download and extract

Open a Web browser and access the following URL: https://karaf.apache.org/download.html.
Download the binary distribution of Karaf Runtime that matches your system (zip for windows, tar.gz for unixes).
Extract the archive to a new folder on your hard drive. For example in /opt/karaf, from now on this directory will be referenced as $KARAF_HOME.

Start and connect

Open a command line console and change the directory to $KARAF_HOME.
To start the server, run the following command on Unix:
```
$KARAF_HOME/bin/karaf
```
Respectively on Windows:
```
$KARAF_HOME\bin\karaf.bat
```
You are now connected to the Karaf shell!


 __ __ ____
 / //_/____ __________ _/ __/
 / ,< / __ `/ ___/ __ `/ /_ / /| |/ /_/ / / / /_/ / __/ /_/ |_|\__,_/_/ \__,_/_/ Apache Karaf (4.3.5) Hit '' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '' or type 'system:shutdown' or 'logout' to shutdown Karaf.
karaf@root()>

If you want to launch your Karaf instance in background, run on Unix:

$KARAF_HOME/bin/start

Respectively on Windows:

$KARAF_HOME\bin\start.bat

Easy to manage

You can manage your Karaf instance with the shell console to a local instance or to a remote instance using the ssh client.

Connect to the shell console

Open a command line console and change the directory to $KARAF_HOME.
To connect to the local instance, run in Unix:
```
$KARAF_HOME/bin/client
```
Respectively on Windows:
```
$KARAF_HOME\bin\client.bat
```

To connect to a remote instance, run:

$KARAF_HOME/bin/client -a "IP" -p "PORT"

You can also use any regular ssh client.

Shell console basics

You can now run your first command. Simply type the tab key in the console.


karaf@root()>
karaf: do you wish to see to see all 356 possibilities (219 lines)?
karaf@root()> Display all 294 possibilities? (y or n)
...
shell:logout shell:more shell:new shell:printf shell:sleep shell:sort shell:source
shell:stack-traces-print shell:tac shell:tail shell:threads shell:watch shell:wc shell:while
shutdown sleep sort source ssh ssh ssh-host-change
ssh-port-change ssh:ssh stack-traces-print start start-level status stop
su sudo system system:framework system:name system:property system:shutdown
system:start-level system:version tac tail threads tree-show uninstall
update user-add user-delete user-list version version-list wait
watch wc while

You can then grab more specific help for a given command using the --help option for this command:


karaf@root()> bundle:list --help
DESCRIPTION
 bundle:list
 Lists all installed bundles.
SYNTAX
 bundle:list [options] [ids]
ARGUMENTS
 ids
 The list of bundle (identified by IDs or name or name/version) separated by whitespaces
OPTIONS
 -name, -n
 Show bundle name
 -u
 Shows the update locations
 -r
 Shows the bundle revisions
 --no-ellipsis
 -l
 Show the locations
 -s
 Shows the symbolic name
 --context, -c
 Use the given bundle context
 (defaults to 0)
 --help
 Display this help message
 -t
 Specifies the bundle threshold; bundles with a start-level less than this value will not get printed out.
 --no-format
 Disable table rendered output

Note that the console supports tab completion so if you start typing a command it will show all possible completions and also auto complete if there is only one completion.

Stop

You have multiple options for shuting down your Karaf instance:

For a background running instance, run the command on Unix:
```
$KARAF_HOME/bin/stop
```
Respectively on Windows:
```
$KARAF_HOME\bin\stop.bat
```
To stop Karaf from the console, enter Ctrl+D.

Alternatively, you can also run the following command:


karaf@root()> feature:install system
karaf@root()> system:shutdown
Confirm: halt instance root (yes/no): yes
karaf@root()>

Halt is also an alias for system:shutdown

karaf@root()> halt

Easy to develop

You are now ready to develop your first application!

A list of examples are packaged in the distribution ($KARAF_HOME/examples). You can have an overview of this examples in the documentation page here.

Tips for developers

You can activate debug mode by adding the parameter debug to the command line:

$KARAF_HOME/bin/karaf debug

Then you can connect to the instance from remote with your IDE on the port 5005.

After building your bundle with maven, you can install it from the console:

karaf@root()> bundle:install -s mvn:groupId/artifactId/1.0.0-SNAPSHOT

The bundle:watch command enables watching the local Maven repository for updates on bundles. If the bundle file changes on the Maven repository, Apache Karaf will automatically update the bundle.

karaf@root()> bundle:watch *

From now, your bundle will automatically update by Karaf after each local build.

What? You thought it was difficult to develop with Karaf?

You want more! Ok, let's going deeper with the manual here.