Repository: karaf-cave Updated Branches: refs/heads/cave-3.x 204130168 -> 859c8c241
Use article format for documentation Project: http://git-wip-us.apache.org/repos/asf/karaf-cave/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf-cave/commit/859c8c24 Tree: http://git-wip-us.apache.org/repos/asf/karaf-cave/tree/859c8c24 Diff: http://git-wip-us.apache.org/repos/asf/karaf-cave/diff/859c8c24 Branch: refs/heads/cave-3.x Commit: 859c8c241bae634ea757ead19015d74e39a765ec Parents: 2041301 Author: Jean-Baptiste Onofré <[email protected]> Authored: Mon Jan 4 17:16:41 2016 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Mon Jan 4 17:16:41 2016 +0100 ---------------------------------------------------------------------- manual/pom.xml | 4 +-- manual/src/main/asciidoc/index.adoc | 6 ++-- .../asciidoc/user-guide/administrate-cave.adoc | 2 +- .../asciidoc/user-guide/cave-repository.adoc | 29 +++++++++++++------- .../main/asciidoc/user-guide/http-wrapper.adoc | 11 +++++--- .../main/asciidoc/user-guide/installation.adoc | 13 +++++---- .../main/asciidoc/user-guide/obr-commands.adoc | 12 ++++++-- .../user-guide/populate-repository.adoc | 13 +++++---- .../asciidoc/user-guide/proxy-repository.adoc | 12 ++++++-- 9 files changed, 66 insertions(+), 36 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/pom.xml ---------------------------------------------------------------------- diff --git a/manual/pom.xml b/manual/pom.xml index 75f075f..488d723 100644 --- a/manual/pom.xml +++ b/manual/pom.xml @@ -49,7 +49,7 @@ <configuration> <sourceHighlighter>coderay</sourceHighlighter> <backend>html5</backend> - <doctype>book</doctype> + <doctype>article</doctype> <attributes> <toc/> <linkcss>false</linkcss> @@ -60,7 +60,7 @@ <configuration> <sourceDirectory>src/main/asciidoc</sourceDirectory> <headerFooter>true</headerFooter> - <imagesDir>../resources/images</imagesDir> + <imagesDir>src/main/asciidoc/images</imagesDir> </configuration> </plugin> <plugin> http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/index.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/index.adoc b/manual/src/main/asciidoc/index.adoc index 751ea42..9669985 100644 --- a/manual/src/main/asciidoc/index.adoc +++ b/manual/src/main/asciidoc/index.adoc @@ -15,17 +15,17 @@ Apache Karaf Cave 3.x - Documentation ===================================== Apache Software Foundation -:doctype: book +:doctype: article :toc: left :toclevels: 3 :toc-position: left :toc-title: Apache Karaf Cave 3.x - Documentation :numbered: -= User Guide - include::overview.adoc[] +== User Guide + include::user-guide/installation.adoc[] include::user-guide/cave-repository.adoc[] http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/administrate-cave.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/administrate-cave.adoc b/manual/src/main/asciidoc/user-guide/administrate-cave.adoc index 513b817..3ef650a 100644 --- a/manual/src/main/asciidoc/user-guide/administrate-cave.adoc +++ b/manual/src/main/asciidoc/user-guide/administrate-cave.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Administration +=== Administration When you install Apache Karaf Cave server, it provides a new CaveServerMBean. http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/cave-repository.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/cave-repository.adoc b/manual/src/main/asciidoc/user-guide/cave-repository.adoc index 7408e61..dcaa3c3 100644 --- a/manual/src/main/asciidoc/user-guide/cave-repository.adoc +++ b/manual/src/main/asciidoc/user-guide/cave-repository.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Repository +=== Repository A Cave Repository is a container for: @@ -51,7 +51,7 @@ storage.location=cave For instance, you can define `/var/cave/store` for the `storage.location` property. -=== Create +==== Create The `cave:repository-create` command creates a new repository: @@ -84,10 +84,13 @@ option to avoid this step: karaf@root()> cave:repository-create -ni -l /home/user/m2/repository m2 ---- -NB: the `-no` and `-ni` options are interesting when you use an existing location for the repository. If you create a +[NOTE] +==== +The `-no` and `-ni` options are interesting when you use an existing location for the repository. If you create a new empty repository, these options don't have really any effect. +==== -=== List +==== List You can list the repositories using the `cave:repositories` command: @@ -101,7 +104,7 @@ m2 | /home/jbonofre/.m2/repository You can find the repository name and location. -=== Repository and OBR service +==== Repository and OBR service By default, Apache Karaf Cave installs the repository in the Apache Karaf OBR service. @@ -155,10 +158,13 @@ karaf@root()> cave:repository-update my-repository This command scan the repository storage location, seeking all OSGi bundles, and generate the OBR metadata (aka a repository.xml). -NB: If you add or remove any artifact in the repository storage location by hand (for instance, using cp, rm, etc on Unix), +[NOTE] +==== +If you add or remove any artifact in the repository storage location by hand (for instance, using cp, rm, etc on Unix), you have to update the repository OBR metadata using the `cave:repository-update` command. +==== -=== Destroy +==== Destroy The `cave:repository-destroy` command deletes the repository storage location: @@ -166,10 +172,13 @@ The `cave:repository-destroy` command deletes the repository storage location: karaf@root()> cave:repository-destroy my-repository ---- -*Be aware that this command completely deletes the repository storage. By extremely careful when using this command -with repository using "custom" location.* +[NOTE] +==== +Be aware that this command completely deletes the repository storage. By extremely careful when using this command +with repository using "custom" location. +==== -=== What's next +==== What's next Apache Karaf Cave provides a HTTP service to expose the repositories. It allows you to use the repositories remotely. You can find details in the link::http-wrapper[HTTP wrapper service section] of the user guide. http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/http-wrapper.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/http-wrapper.adoc b/manual/src/main/asciidoc/user-guide/http-wrapper.adoc index eb2aab9..964ebce 100644 --- a/manual/src/main/asciidoc/user-guide/http-wrapper.adoc +++ b/manual/src/main/asciidoc/user-guide/http-wrapper.adoc @@ -12,13 +12,13 @@ // limitations under the License. // -== HTTP wrapper service +=== HTTP wrapper service When you install the Apache Karaf Cave Server, it starts a HTTP service wrapper. It means that all artifacts and OBR metadata presents in local repositories are exposed over HTTP. -=== OBR metadata access +==== OBR metadata access Assuming that you have the following repositories: @@ -42,7 +42,10 @@ and http://localhost:8181/cave/my-repository-repository.xml ---- -NB: the port 8181 is the default one of the Apache Karaf HTTP service. +[NOTE] +==== +The port 8181 is the default one of the Apache Karaf HTTP service. +==== You can see that the URL follows the format: @@ -62,7 +65,7 @@ karaf@other()> obr:url-add http://cave_server:8181/cave/cave-repo-repository.xml karaf@other()> obr:url-add http://cave_server:8181/cave/m2-repository.xml ---- -=== OSGi bundles access +==== OSGi bundles access Apache Karaf Cave HTTP wrapper service also provide the OSGi bundles binaries via HTTP. http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/installation.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/installation.adoc b/manual/src/main/asciidoc/user-guide/installation.adoc index 19147bb..0445f20 100644 --- a/manual/src/main/asciidoc/user-guide/installation.adoc +++ b/manual/src/main/asciidoc/user-guide/installation.adoc @@ -12,18 +12,18 @@ // limitations under the License. // -== Installation +=== Installation This chapter describes how to install Apache Karaf Cave into an existing Apache Karaf instance. -=== Pre-installation requirements +==== Pre-installation requirements As Apache Karaf Cave is a Apache Karaf sub-project, it has to be installed into a running Apache Karaf instance. Apache Karaf Cave is available as Apache Karaf features. The easiest way to install is just to have an internet connection from the Apache Karaf running instance. -=== Registration of the Apache Karaf Cave features +==== Registration of the Apache Karaf Cave features Simply register the Apache Karaf Cave features URL in your Apache Karaf instance: @@ -38,7 +38,7 @@ karaf@root()> feature:list |grep -i cave cave-server | 3.0.0 | x | karaf-cave-3.0.0 | ---- -=== Starting Apache Karaf Cave Server +==== Starting Apache Karaf Cave Server The Apache Karaf Cave Server is installed by the `cave-server` feature: @@ -46,8 +46,11 @@ The Apache Karaf Cave Server is installed by the `cave-server` feature: karaf@root()> feature:install cave-server ---- -NB: installation of the cave-server feature will install additional features, such as obr, http, war. It could take +[NOTE] +==== +Installation of the cave-server feature will install additional features, such as obr, http, war. It could take several minutes depending of your network connection speed. +==== New Apache Karaf Cave commands are now available: http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/obr-commands.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/obr-commands.adoc b/manual/src/main/asciidoc/user-guide/obr-commands.adoc index 6577ece..eb59c99 100644 --- a/manual/src/main/asciidoc/user-guide/obr-commands.adoc +++ b/manual/src/main/asciidoc/user-guide/obr-commands.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== OBR commands +=== OBR commands To install a repository in the OBR service, you have to use: @@ -74,7 +74,10 @@ Capabilities: package:{package=org.apache.commons.jocl, uses:=org.xml.sax.helpers,org.xml.sax, version=1.4.0} ---- -NB: in Apache Karaf, the OBR entry format is symbolicname,version +[NOTE] +==== +In Apache Karaf, the OBR entry format is symbolicname,version +==== You have the details of the OSGi bundle, especially the requirements and capabilities of the bundle. @@ -161,4 +164,7 @@ Deploying...done. Done: the OBR has resolved the commons-dbcp requirements using the commons-pool capabilities and so installed the commons-pool bundle. -NB: in the `obr:deploy` command, if you don't mention the version, it will take the highly version available. \ No newline at end of file +[NOTE] +==== +In the `obr:deploy` command, if you don't mention the version, it will take the highly version available. +==== \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/populate-repository.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/populate-repository.adoc b/manual/src/main/asciidoc/user-guide/populate-repository.adoc index fcb3b5c..27661f6 100644 --- a/manual/src/main/asciidoc/user-guide/populate-repository.adoc +++ b/manual/src/main/asciidoc/user-guide/populate-repository.adoc @@ -12,11 +12,11 @@ // limitations under the License. // -== Populate repository +=== Populate repository You can add new artifacts in a repository. -=== Upload a single artifact +==== Upload a single artifact You can upload a single artifact into a Cave Repository: @@ -31,7 +31,7 @@ You can also use Maven style URL: karaf@root()> cave:repository-upload-artifact my-repository mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.ant/1.7.0_5 ---- -=== Populate from an external repository +==== Populate from an external repository You can also make a kind of "bulk" population of your repository, using an external repository: @@ -55,8 +55,11 @@ You can also populate with the whole Central Maven Repository: karaf@root()> cave:repository-populate my-repository http://repo1.maven.org/maven2 ---- -*Maven Central repository is really huge and populating from the whole Maven Central Repository will take -very very long time. It's just for demonstration purpose.* +[NOTE] +==== +Maven Central repository is really huge and populating from the whole Maven Central Repository will take +very very long time. It's just for demonstration purpose. +==== You can filter the artifacts that you want to pick up to populate the repository. The `cave:repository-populate` command accepts a regex option for the filter. For instance, to pick up only joda-time version 2 artifact, you can run: http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/859c8c24/manual/src/main/asciidoc/user-guide/proxy-repository.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/user-guide/proxy-repository.adoc b/manual/src/main/asciidoc/user-guide/proxy-repository.adoc index ae56768..645f09b 100644 --- a/manual/src/main/asciidoc/user-guide/proxy-repository.adoc +++ b/manual/src/main/asciidoc/user-guide/proxy-repository.adoc @@ -12,7 +12,7 @@ // limitations under the License. // -== Proxy repository +=== Proxy repository As you can link::populate-repository[populate repository], you can also proxy an "external" repository. @@ -23,10 +23,16 @@ for the remote artifacts: karaf@root()> cave:repository-proxy my-repository http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.commons-lang/ ---- -NB: the Cave repository will only handle the OBR metadata, it doesn't monitor the remote repository. It means that you +[NOTE] +==== +The Cave repository will only handle the OBR metadata, it doesn't monitor the remote repository. It means that you have to call the `cave:proxy-repository` command each time the remote repository change (new artifacts, etc). +==== -NB: a best practice is to create a Cave repository dedicated for each proxied repository. +[NOTE] +==== +A best practice is to create a Cave repository dedicated for each proxied repository. +==== The `cave:proxy-repository` command accepts the filter option, as the `cave:populate-repository` command:
