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.