h1. Cave Repository

A Karaf Cave Repository is a container for:

* the OSGi bundles (jar files)
* the OBR metadata (repository.xml)

By default, a Cave Repository uses a filesystem backend for the storage, the directory used is KARAF_BASE/case.

You can change the storage location in the etc/org.apache.karaf.cave.server.storage.cfg configuration file:

{code}
# default value
storage.location=cave
# custom storage location
#storage.location=/path/to/your/storage/folder
{code}

h2. Create a Cave Repository

The cave:repository-create command creates a Cave Repository:

{code}
karaf@root> cave:repository-create cave-repo
{code}

A Cave Repository is identified by a name, cave-repo in our example.

Karaf Cave will create the repository storage. In this example, you can see a cave-repo folder in the storage location:

{code}
shell$ ls cave/
cave-repo
{code}

If you want to use an existing directory, and avoid Cave to create one in the storage location, you can use the -l or
--location option:

{code}
karaf@root> cave:repository-create -l /home/jbonofre/.m2/repository m2
{code}

You can also generate the OBR metadata at creation time using the -s or --scan option. Karaf Cave scans the repository
storage, looking for OSGi bundles, and create the OBR metadata:

{code}
karaf@root> cave:repository-create -s -l /home/jbonofre/.m2/repository m2
{code}

In the same way, you can register the Cave Repository in the OBR service directly at creation time. For instance, you
can combine the three options to:

1. create the Cave Repository using an existing location
2. scan for OSGi bundle and create the OBR metadata
3. register the Cave repository in the OBR service

{code}
karaf@root> cave:repository-create -s -r -l /home/jbonofre/.m2/repository m2
{code}

h2. List of Cave Repositories

You can list the Cave Repositories:

{code}
karaf@root> cave:repositories-list
Name                 Location
[cave-repo]          [/home/jbonofre/apache-karaf-2.3.1/cave/cave-repo]
[m2]                 [/home/jbonofre/.m2/repository]
{code}

h2. Remove and destroy a Cave Repository

You can remove a Cave Repository from the repositories registry:

{code}
karaf@root> cave:repository-uninstall cave-repo
{code}

The Cave Repository storage won't be removed. It means that the artifacts will stay in the storage folder.

If you want to destroy a Cave Repository, including the artifacts and the storage folder, you have to use:

{code}
karaf@root> cave:repository-destroy cave-repo
{code}

h2. Generate OBR metadata

You can generate the OBR metadata:

{code}
karaf@root> cave:repository-scan cave-repo
{code}

Cave will scan the Cave Repository storage, looking for OSGi bundle, and generate the OBR metadata.

h2. Register Cave Repository in the OBR service

Once you have generated the OBR metadata, you can register the Cave Repository in the OBR service:

{code}
karaf@root> cave:repository-install cave-repo
{code}

You are now ready to use the [OBR commands|/user-guide/obr-command].

You can also use a remote Cave server via the [HTTP Wrapper Service|/user-guide/http-wrapper]
or the [Cave Client|/user-guide/client].