get-started.html

---
layout: page
title: Apache Karaf - Get started
permalink: /get-started
---

<main role="main">

    <div class="container pt-5 pb-3">
      <div class="jumbotron p-3 p-md-5 text-white bg-primary">
        <div class="col-md-12 px-0">
          <h1 class="display-4 font-italic">Get started with Apache Karaf is very easy!</h1>
        </div>
      </div>
    </div>

    <main role="main">

      <div class="container">

        <!-- Easy to install -->
        <div class="row mb-2 mt-3">
            <div class="col">
              <h2 class="pb-3 mb-4 font-italic border-bottom"><i class="fas fa-box"></i> Easy to install</h2>
              <p>The only prerequisite to start with Karaf is a Java SE 8 / 9 / 10 / 11 environment to run.
                Refer to <a target="_blank" href="https://www.oracle.com/technetwork/java/javase">https://www.oracle.com/technetwork/java/javase</a> for details on how to download and install Java SE 1.8 or greater.</p>
            </div>
        </div>

        <div class="row mb-2 mt-2">
            <div class="col">
              <h4 class="pb-3 mb-1">Download and extract</h4>
              <ol>
                <li>Open a Web browser and access the following URL: <a target="_blank" href="https://karaf.apache.org/download">
                  https://karaf.apache.org/download.html</a>.</li>
                <li>Download the binary distribution of Karaf Runtime that matches your system (zip for windows, tar.gz for unixes).</li>
                <li>Extract the archive to a new folder on your hard drive. For example in <code>/opt/karaf</code>, from now on this directory will be
                  referenced as <code>$KARAF_HOME</code>.</li>
              </ol>
            </div>
        </div>

        <div class="row mb-5 mt-2">
          <div class="col">
            <h4 class="pb-3 mb-1">Start and connect</h4>
            <ol>
              <li>Open a command line console and change the directory to <code>$KARAF_HOME</code>.</li>
              <li>To start the server, run the following command on Unix:
                <pre class="alert alert-primary"><code>$KARAF_HOME/bin/karaf</code></pre>
                Respectively on Windows:
                <pre class="alert alert-primary"><code>$KARAF_HOME\bin\karaf.bat</code></pre>
              </li>
              <li>You are now connected to the Karaf shell!</li>
            </ol>

            <p>
              <pre class="alert alert-primary"><code>
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.3.5)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.

karaf@root()>
              </code></pre>
            </p>
            <p><i class="fa fa-info-circle"></i> If you want to launch your Karaf instance in background, run on Unix:
              <pre class="alert alert-primary"><code>$KARAF_HOME/bin/start</code></pre>
            </p>
            <p>Respectively on Windows:
              <pre class="alert alert-primary"><code>$KARAF_HOME\bin\start.bat</code></pre>
            </p>
          </div>
        </div>

        <!-- Easy to manage -->
        <div class="row mb-2 mt-3">
          <div class="col">
            <h2 class="pb-3 mb-4 font-italic border-bottom"><i class="fas fa-laptop"></i> Easy to manage</h2>
            <p>You can manage your Karaf instance with the shell console to a local instance or to a remote instance using the ssh client.</p>
          </div>
        </div>

        <div class="row mb-2 mt-2">
          <div class="col">
            <h4 class="pb-3 mb-1">Connect to the shell console</h4>
            <ol>
              <li>Open a command line console and change the directory to <code>$KARAF_HOME</code>.</li>
              <li>To connect to the local instance, run in Unix:
                <pre class="alert alert-primary"><code>$KARAF_HOME/bin/client</code></pre>
                Respectively on Windows:
                <pre class="alert alert-primary"><code>$KARAF_HOME\bin\client.bat</code></pre>
                </li>
            </ol>
            <p><i class="fa fa-info-circle"></i> To connect to a remote instance, run:</p>
            <pre class="alert alert-primary"><code>$KARAF_HOME/bin/client -a "IP" -p "PORT"</code></pre>
            <p>You can also use any regular <code>ssh</code> client.</p>
          </div>
        </div>

        <div class="row mb-2 mt-2">
          <div class="col">
            <h4 class="pb-3 mb-1">Shell console basics</h4>
            <p>
              You can now run your first command. Simply type the <code>tab</code> key in the console.
            </p>
            <pre class="alert alert-primary"><code>
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
            </code></pre>
            <p>You can then grab more specific help for a given command using the <code>--help</code> option for this command:</p>
            <pre class="alert alert-primary"><code>
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
            </code></pre>
            <p>
              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.
            </p>
          </div>
        </div>

        <div class="row mb-2 mt-2">
          <div class="col">
            <h4 class="pb-3 mb-1">Stop</h4>
            You have multiple options for shuting down your Karaf instance:
            <ul>
              <li>For a background running instance, run the command on Unix:
                <pre class="alert alert-primary"><code>$KARAF_HOME/bin/stop</code></pre>
                Respectively on Windows:
                <pre class="alert alert-primary"><code>$KARAF_HOME\bin\stop.bat</code></pre>
              </li>
              <li>To stop Karaf from the console, enter <code>Ctrl+D</code>.</li>
              <li>Alternatively, you can also run the following command:
                <pre class="alert alert-primary"><code>
karaf@root()> feature:install system
karaf@root()> system:shutdown
Confirm: halt instance root (yes/no): yes
karaf@root()>
                </code></pre>
              </li>
            </ul>
            <p><i class="fa fa-info-circle"></i> Halt is also an alias for <code>system:shutdown</code>
              <pre class="alert alert-primary"><code>karaf@root()> halt</code></pre>
            </p>
          </div>
        </div>

        <!-- Easy to develop -->
        <div class="row mb-2 mt-3">
          <div class="col">
            <h2 class="pb-3 mb-4 font-italic border-bottom"><i class="fas fa-code"></i> Easy to develop</h2>
            <p>You are now ready to develop your first application!</p>
            <p>A list of examples are packaged in the distribution (<code>$KARAF_HOME/examples</code>).
              You can have an overview of this examples in the documentation page <a href="/documentation.html">here</a>.
            </p>
          </div>
        </div>

        <div class="row mb-2 mt-2">
          <div class="col">
            <h4 class="pb-3 mb-1">Tips for developers</h4>
            <p>You can activate debug mode by adding the parameter <code>debug</code> to the command line:
                <pre class="alert alert-primary"><code>$KARAF_HOME/bin/karaf debug</code></pre></li>
              Then you can connect to the instance from remote with your IDE on the port <code>5005</code>.
            </p>
            <p>After building your bundle with maven, you can install it from the console:</p>
            <pre class="alert alert-primary"><code>karaf@root()> bundle:install -s mvn:groupId/artifactId/1.0.0-SNAPSHOT</code></pre>
            <p>The <code>bundle:watch</code> 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.</p>
            <pre class="alert alert-primary"><code>karaf@root()> bundle:watch *</code></pre>
            <p>From now, your bundle will automatically update by Karaf after each local build.</p>
          </div>
        </div>

        <!-- Want more -->
        <div class="row mb-2 mt-3">
          <div class="col">
            <h2 class="pb-3 mb-4 font-italic border-bottom"><i class="far fa-comments"></i> What? You thought it was difficult to develop with Karaf?</h2>
            <p>You want more! Ok, let's going deeper with the manual <a href="/manual/latest" target="_blank">here</a>.</p>
          </div>
        </div>

      </div>
</main>