Cave Deployer allows you to manage a "farm" of Apache Karaf instances local or remote from the deployer itself.

Connections

To interact with a Apache Karaf instance, you have to create a connection describing the access to this instance.

A connection has:

  • an unique name for the connection

  • the JMX URL to the given Apache Karaf instance

  • the name of the Apache Karaf instance

  • username and password to connect to the Apache Karaf instance

Create connections
cave:deployer-connection-register shell command

You can add a new Apache Karaf connection using cave:deployer-connection-register shell command:

karaf@root()> cave:deployer-connection-register myconnection service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root root karaf karaf
REST API

You can create a connection via the Cave Deployer REST API on /cave/deployer/api/connections using a JSON description of your connection. For instance, using curl:

curl -X POST -H "Content-Type: application/json" http://localhost:8181/cave/deployer/api/connections -d '{
 "name": "myconnection",
 "jmxUrl": "service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root",
 "karafName": "root",
 "user": "karaf",
 "password": "karaf"
}'
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the registerConnection(String name, String jmxUrl, String karafName, String user, String password) operation allowing you to create a new connection.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the registerConnection(Connection connection) method allowing you to create a new connection.

List connections
cave:deployer-connection-list shell command

You can list available connections using the cave:deployer-connection-list command:

karaf@root()> cave:deployer-connection-list
Name         │ JMX URL                                                 │ Instance │ Username │ Password
─────────────┼─────────────────────────────────────────────────────────┼──────────┼──────────┼─────────
myconnection │ service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root │ root     │ karaf    │ *****
REST API

You can list available connections using the Cave Deployer REST API on /cave/deployer/api/connections (GET) URL.

For instance, using curl:

curl -X GET -H "Content-Type: application/json" http://localhost:8181/cave/deployer/api/connections
[{"name":"myconnection","jmxUrl":"service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root","karafName":"root","user":"karaf","password":"karaf"}]
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the connections attribute. It’s a tabular data where you can find all connections available.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the connections() method providing the list of all connections available.

Delete a connection
cave:deployer-connection-delete shell command

You can delete an existing connection with cave:deployer-connection-delete shell command:

karaf@root()> cave:deployer-connection-delete myconnection
REST API

You can delete an existing connection using Cave Deployer Rest API on /cave/deployer/api/connections/{name} URL (DELETE). For instance, using curl:

curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the deleteConnection(String name) operation to delete an existing connection.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the deleteConnection(String connectionName) method to delete an existing connection.

Artifacts

Download & upload artifacts

Cave Deployer is able to download an artifacts into a target directory.

For instance you can download an artifact using cave:deployer-download shell command:

karaf@root()> cave:deployer-download mvn:commons-lang/commons-lang/2.6 /path/to/my/repo

You can also use Cave Deployer REST API on /cave/deployer/api/download (POST). The artifact URL is passed using artifact header and the directory is passed using directory header.

For instance, using curl:

curl -X POST -H "artifact: mvn:commons-lang/commons-lang/2.6" -H "directory: /path/to/my/repo" http://localhost:8181/cave/deployer/api/download

You can also use the download(String url, String directory) operation on the org.apache.karaf.cave:type=deployer MBean.

On the org.apache.karaf.cave.deployer.DeployerService service, you can also use the download(String artifact, String directory) method.

On the other hand, you can also upload an artifact to a target repository providing the Maven coordinates. It’s exactly the same as doing mvn deploy:deploy-file.

To upload an artifact, you can use the cave:deployer-upload shell command:

karaf@root()> cave:deployer-upload -g groupId -a artifactId -v 1.0-SNAPSHOT mvn:foo/bar/x.x http://host/repository

You can also use the Cave Deployer REST API on /cave/deployer/api/upload (POST) with the following header parameters:

  • groupId

  • artifactId

  • version

  • artifactUrl

  • repositoryUrl

For instance, using curl:

curl -X POST -H "groupId: groupId" -H "artifactId: artifactId" -H "version: 1.0-SNAPSHOT" -H "artifactUrl: mvn:foo/bar/x.x" -H "repositoryUrl: http://host/repository" http://localhost:8181/cave/deployer/api/upload

You can also use the upload(String groupId, String artifactId, String version, String artifactUrl, String repositoryUrl) operation on the org.apache.karaf.cave:type=deployer MBean.

The org.apache.karaf.cave.deployer.DeployerService service also provides the upload(String groupId, String artifactId, String version, String artifactUrl, String repositoryUrl) method.

Extract & explode artifacts

Cave Deployer is also able to process zip and kar artifacts.

Cave Deployer is able to extract zip or kar files to a given Maven repository or local directory:

  • explode will download and extract an artifact into a target folder/repository, looking for features repositories XML (typically in KAR files)

  • extract will download and extract an artifact into a target folder/repository

To explode an artifact into a target Maven repository, you can use cave:deployer-explode shell command:

karaf@root()> cave:deployer-explode mvn:foo/bar/1.0/kar /path/to/repository

You can also use the Cave Deployer REST API on /cave/deployer/api/explode URL (POST) with url header for the artifact URL, and repository header for the repository URL. For instance, using curl:

curl -X POST -H "url: mvn:foo/bar/1.0/kar" -H "repository: /path/to/repository" http://localhost:8181/cave/deployer/api/explode
["foo.xml"]

You can also use explode(String url, String repository) operation on the org.apache.karaf.cave:type=deployer MBean.

The org.apache.karaf.cave.deployer.DeployerService also provides the explode(String url, String repository) method.

Similar to explode, you can extract artifact (without looking for features repositories XML).

You can use the cave:deployer-extract shell command to extract an artifact:

karaf@root()> cave:deployer-extract mvn:foo/bar/1.0/zip /path/to/directory

You can also use the Cave Deployer REST API on /cave/deployer/api/extract URL (POST) with url header for the artifact URL, and directory header for the directory. For instance, using curl:

curl -X POST -H "url: mvn:foo/bar/1.0/zip" -H "directory: /path/to/directory" http://localhost:8181/cave/deployer/api/extract

The org.apache.karaf.cave:type=deployer MBean also provides extract(String url, String directory) operation to extract an artifact into a directory.

You can also programmatically use ` extract(String url, String directory)` method on the org.apache.karaf.cave.deployer.DeployerService service.

Features

Assemble features

You can create new Karaf features by composing existing features, configurations or bundles.

For instance, you can create myfeature composed by feature1, feature2, bundle1, bundle2.

  • karaf@root()> cave:deployer-assemble-feature -g groupId -a artifactId -v 1.0-SNAPSHOT myfeature http://myrepo feature1 feature2

  • Using assembleFeature(String groupId, String artifactId, String version, String repositoryUrl, String feature, List<String> repositories, List<String> features, List<String> bundles) operation on the org.apache.karaf.cave:type=deployer MBean

  • Using assembleFeature(String groupId, String artifactId, String version, String repositoryUrl, String feature, List<String> featureRepositoryUrls, List<String> features, List<String> bundles, List<Config> configs) method on the org.apache.karaf.cave.deployer.DeployerService service

Add features repositories

  • karaf@root()> cave:deployer-feature-repo-add myconnection mvn:foo/bar/1.0/xml/features

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/features/repositories

  • addFeatureRepository(String url, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • addFeaturesRepository(String featuresRepositoryUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List features repositories
List features provided by a features repository

  • karaf@root()> cave:deployer-feature-repo-provide mvn:foo/bar/1.0/xml/features

  • curl -X GET -H "featuresRepositoryUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/features/repository

  • getProvidedFeatures(String featuresRepositoryUrl) operation on the org.apache.karaf.cave:type=deployer MBean.

  • providedFeatures(String featuresRepositoryUrl) method on the org.apache.karaf.cave.deployer.DeployerService service.

Remove features repositories

  • karaf@root()> cave:deployer-feature-repo-remove myconnection mvn:foo/bar/1.0/xml/features

  • curl -X DELETE -H "artifactUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/features/repositories

  • removeFeatureRepository(String repository, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • removeFeaturesRepository(String featuresRepositoryUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Install features
List features
List installed features

  • karaf@root()> cave:deployer-feature-installed-list myconnection

  • installedFeatures(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Uninstall features

KARs

Install KAR

  • karaf@root()> cave:deployer-kar-install myconnection mvn:foo/bar/1.0/kar

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0/kar" http://localhost:8181/cave/deployer/api/connections/myconnection/kars

  • installKar(String url, String connection) operation on the org.apache.karaf.cave:typye=deployer MBean.

  • installKar(String karUrl, String connection) on the org.apache.karaf.cave.deployer.DeployerService service.

List KARs
Uninstall KAR

Bundles

Install bundle

  • karaf@root()> cave:deployer-bundle-install myconnection mvn:foo/bar/1.0

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0" http://localhost:8181/cave/deployer/api/connections/myconnection/bundles

  • installBundle(String url, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • installBundle(String artifactUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List bundles
Start bundle
Stop bundle
Uninstall bundle

  • karaf@root()> cave:deployer-bundle-uninstall myconnection 81

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/bundles/81

  • uninstallBundle(String id, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • uninstallBundle(String id, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Configurations

Create configuration
Create configuration factory
List configurations
Set configuration property

  • karaf@root()> cave:deployer-config-property-set myconnection myconfiguration myproperty myvalue

  • setConfigProperty(String pid, String key, String value, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • setConfigProperty(String pid, String key, String value, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List configuration properties
Delete configuration property

  • karaf@root()> cave:deployer-config-property-delete myconnection myconfiguration myproperty

  • deleteConfigProperty(String pid, String key, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • deleteConfigProperty(String pid, String key, String connection) methood on the org.apache.karaf.cave.deployer.DeployerService service.

Delete configuration

Karaf Cellar cluster

Cave Deployer is able to administrate a Karaf Cellar cluster.

List cluster nodes

  • cave:deployer-cluster-node-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/cluster/nodes

  • getClusterNodes(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterNodes(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List cluster groups

  • cave:deployer-cluster-group-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/cluster/groups

  • getClusterGroups(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterGroups(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Add features repository to cluster group
Remove features repository from cluster group
Install feature on cluster group
Uninstall feature from cluster group