brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject [2/5] brooklyn-docs git commit: Re-organise for better presentation in response to review comments.
Date Tue, 27 Sep 2016 08:46:57 GMT
Re-organise for better presentation in response to review comments.


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/073edb1e
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/073edb1e
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/073edb1e

Branch: refs/heads/master
Commit: 073edb1e548b307298c8b0ca6759db2dfe5b0ded
Parents: 5687acd
Author: Geoff Macartney <geoff.macartney@cloudsoftcorp.com>
Authored: Fri Sep 16 12:02:00 2016 +0100
Committer: Geoff Macartney <geoff.macartney@cloudsoftcorp.com>
Committed: Fri Sep 16 12:02:00 2016 +0100

----------------------------------------------------------------------
 guide/index.md                   |   1 -
 guide/misc/osgi.md               | 132 ----------------------------------
 guide/ops/brooklyn_properties.md |  62 +---------------
 guide/ops/https.md               |  53 ++++++++++++++
 guide/ops/index.md               |   2 +
 guide/ops/osgi-configuration.md  | 118 ++++++++++++++++++++++++++++++
 guide/ops/osgi.md                |  56 +++++++++++++++
 7 files changed, 231 insertions(+), 193 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/index.md
----------------------------------------------------------------------
diff --git a/guide/index.md b/guide/index.md
index 62c52c6..cdb3b46 100644
--- a/guide/index.md
+++ b/guide/index.md
@@ -11,7 +11,6 @@ children:
 - { path: /guide/yaml/index.md }
 - { path: /guide/java/index.md }
 - { path: /guide/ops/index.md }
-- { path: /guide/misc/osgi.md }
 - { path: /guide/misc/index.md }
 ---
 

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/misc/osgi.md
----------------------------------------------------------------------
diff --git a/guide/misc/osgi.md b/guide/misc/osgi.md
deleted file mode 100644
index dd9ba77..0000000
--- a/guide/misc/osgi.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-title: OSGi Distribution
-layout: website-normal
----
-
-# Running Apache Brooklyn inside Karaf container
-
-The Apache Brooklyn Karaf based distribution lives in brooklyn-server/karaf/apache-brooklyn
folder.
-It's still in a testing stage so some features might not work as expected. Do reach out if
you
-find any problems.
-
-## Building
-
-{% highlight bash %}
-cd brooklyn-server
-mvn clean install
-cd karaf/apache-brooklyn/target
-tar -zxvf apache-brooklyn-{{ site.brooklyn-version }}.tar.gz
-cd apache-brooklyn-{{ site.brooklyn-version }}
-{% endhighlight %}
-
-## Running
-
-Start the instance using the following command
-
-{% highlight bash %}
-bin/karaf
-{% endhighlight %}
-
-This will launch the [Karaf console](https://karaf.apache.org/manual/latest/users-guide/console.html)
-where you can interact with the running instance. Note that Brooklyn has already started
at this point
-and is reachable at the usual web console url.
-
-To start in debug mode use
-
-{% highlight bash %}
-bin/karaf debug
-{% endhighlight %}
-
-and connect to port 5005 using your debugger.
-
-To pause startup until the debugger is connected you can use
-
-{% highlight bash %}
-JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
bin/karaf debug
-{% endhighlight %}
-
-The Karaf container will keep state like installed bundles and configuration between restarts.
-To reset any changes add **clean** to the cli arguments.
-
-## Configuring
-
-To configure the Brooklyn runtime create an **etc/brooklyn.cfg** file, following the standard
**brooklyn.properties**
-file format. Values can be viewed and managed dynamically via the OSGI configuration admin
commands in Karaf,
-e.g. config:property-set. The global **~/.brooklyn/brooklyn.properties** is still supported
and has higher
-priority for duplicate keys, but it's values can't be manipulated with the Karaf commands,
so its use is
-discouraged.
-
-You can use the standard ~/.brooklyn/brooklyn.properties file to configure Brooklyn. Alternatively
-create etc/brooklyn.cfg inside the distribution folder (same file format). The keys in the
former override
-those in the latter.
-
-Web console related configuration is done through the corresponding Karaf mechanisms:
-
-  * The port is set in etc/org.ops4j.pax.web.cfg, key org.osgi.service.http.port.
-  * For authentication the JAAS realm "webconsole" is used; by default it will use any
-    SecurityProvider implementations configured in Brooklyn falling back to auto generating
-    the password. To configure a custom JAAS realm see the jetty.xml file in "brooklyn-server/karaf/jetty-config/src/main/resources"
-    and override it by creating a custom one in "etc" folder. Point the "webconsole" login
service
-    to the JAAS realm you would like to use.
-   * For other Jetty related configuration consult the Karaf and pax-web docs.
-
-
-## Catalog in Karaf
-
-
-With the traditional launcher, Brooklyn loads the initial contents of the catalog from a
`default.catalog.bom` file
-as described in the section on [installation](/guide/ops/production-installation.html). Brooklyn
finds Java 
-implementations to provide for certain things in blueprints (entities, enrichers etc.) by
scanning the classpath. 
-
-In the OSGI world this approach is not used, as each bundle only has visibility of its own
and its imported Java packages. 
-Instead, in Karaf, each bundle can declare its own `catalog.bom` file, in the root of the
bundle,
-with the catalog declarations for any entities etc. that the bundle contains.
-
-For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abbreviated):
-
-    brooklyn.catalog:
-        version: ...
-        items:
-        - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
-          itemType: entity
-          item:
-            type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
-            name: Node.JS Application
-        ...
-        - id: resilient-bash-web-cluster-template
-          itemType: template
-          name: "Template: Resilient Load-Balanced Bash Web Cluster with Sensors"
-          description: |
-            Sample YAML to provision a cluster of the bash/python web server nodes,
-            with sensors configured, and a load balancer pointing at them,
-            and resilience policies for node replacement and scaling
-          item:
-            name: Resilient Load-Balanced Bash Web Cluster (Brooklyn Example)
-
-In the above YAML the first item declares that the bundle provides an entity whose type is
-`org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService`, and whose name is 'Node.JS
Application'.  The second
-item declares that the bundle provides a template application, with id  `resilient-bash-web-cluster-template`,
and
-includes a description for what this is.
-
-## Configuring the applications in the Catalog
-
-When running some particular deployment of Brooklyn it may not be desirable for the sample
applications to appear in
-the catalog (for clarity, "application" here in the sense of an item with `itemType: template`).
-For example, if you have developed
-some bundle with your own application and added it to Karaf then you might want only your
own application to appear in
-the catalog.
-
-Brooklyn contains a mechanism to allow you to configure what bundles will add their applications
to the catalog.
-The Karaf configuration file `/etc/org.apache.brooklyn.core.catalog.bomscanner.cfg` contains
two properties,
-one `whitelist` and the other `blacklist`, that bundles must satisfy for their applications
to be added to the catalog.
-Each property value is a comma-separated list of regular expressions.  The symbolic id of
the bundle must match one of
-the regular expressions on the whitelist, and not match any expression on the blacklist,
if its applications
-are to be added to the bundle.  The default values of these properties are to admit all bundles,
and forbid none.
-
-## Caveats
-
-In the OSGi world specifying class names by string in Brooklyn's configuration will work
only
-for classes living in Brooklyn's core modules. Raise an issue or ping us on IRC if you find
-a case where this doesn't work for you. For custom SecurityProvider implementations refer
to the
-documentation of BrooklynLoginModule.
-

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
index 114e4c2..aa08875 100644
--- a/guide/ops/brooklyn_properties.md
+++ b/guide/ops/brooklyn_properties.md
@@ -211,49 +211,10 @@ or
 {% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement"
project_subpath="api" %}.
 
 
-## HTTPS Configuration
 
-### Getting the Certificate
-To enable https, you will need a server certificate in a java keystore. To create a self-signed
certificate,
-and add it to a keystore, `keystore.jks`, you can use the following command:
+## Configuring HTTPS in Brooklyn
 
-{% highlight bash %}
-% keytool -genkey -keyalg RSA -alias brooklyn \
-          -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword"
\
-          -validity 365 -keysize 2048 -keypass "password"
-{% endhighlight %}
-
-Of course, the passwords above should be changed.  Omit those arguments above for the tool
to prompt you for the values.
-
-You will then be prompted to enter your name and organization details. This will use (or
create, if it does not exist)
-a keystore with the password `mypassword` - you should use your own secure password, which
will be the same password
-used in your brooklyn.properties (below). You will also need to replace `<path-to-keystore-directory>`
with the full 
-path of the folder where you wish to store your keystore. The keystore will contain the newly
generated key, 
-with alias `brooklyn` and password `password`.
-
-The certificate generated will be a self-signed certificate, which will cause a warning to
be displayed by a browser 
-when viewing the page. (The various browsers each have ways to import the certificate as
a trusted one, for test purposes.)
-
-For production servers, a valid signed certificate from a trusted certifying authority should
be used instead.
-Typically keys from a certifying authority are not provided in Java keystore format.  To
create a Java keystore from 
-existing certificates (CA certificate, and public and private keys), you must first create
a PKCS12 keystore from them,
-for example with `openssl`; this can then be converted into a Java keystore with `keytool`.
For example, with 
-a CA certificate `ca.pem`, and public and private keys `cert.pem` and `key.pem`, create the
PKCS12 store `server.p12`,
-and then convert it into a keystore `keystore.jks` as follows:
- 
-{% highlight bash %}
-% openssl pkcs12 -export -in cert.pem -inkey key.pem \
-               -out server.p12 -name "brooklyn" \
-               -CAfile ca.pem -caname root -chain -passout pass:"password"
-
-% keytool -importkeystore \
-        -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \
-        -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \
-        -alias "brooklyn"
-{% endhighlight %}
-
-
-### Configuring HTTPS in Brooklyn
+See [HTTPS Configuration](https.html) for general information on configuring HTTPS.
 
 To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
 
@@ -264,22 +225,3 @@ brooklyn.webconsole.security.keystore.password=mypassword
 brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
 {% endhighlight %}
 
-### Configuring HTTPS in Brooklyn (Karaf launcher)
-
-In `etc/org.ops4j.pax.web.cfg` in the Brooklyn Karaf distribution root, add:
-
-{% highlight properties %}
-org.osgi.service.http.port.secure=8443
-org.osgi.service.http.secure.enabled=true
-org.ops4j.pax.web.ssl.keystore=./etc/keystores/keystore.jks
-org.ops4j.pax.web.ssl.password=password
-org.ops4j.pax.web.ssl.keypassword=password
-org.ops4j.pax.web.ssl.clientauthwanted=false
-org.ops4j.pax.web.ssl.clientauthneeded=false
-{% endhighlight %}
-
-replacing the passwords with appropriate values, and restart the server. Note the keystore
location is relative to 
-the installation root, but a fully qualified path can also be given, if it is desired to
use some separate pre-existing
-store.
-
-

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/https.md
----------------------------------------------------------------------
diff --git a/guide/ops/https.md b/guide/ops/https.md
new file mode 100644
index 0000000..7bdeacb
--- /dev/null
+++ b/guide/ops/https.md
@@ -0,0 +1,53 @@
+---
+title: HTTPS Configuration
+layout: website-normal
+---
+
+## HTTPS Configuration
+
+### Getting the Certificate
+To enable HTTPS web access, you will need a server certificate in a java keystore. To create
a self-signed certificate,
+and add it to a keystore, `keystore.jks`, you can use the following command:
+
+{% highlight bash %}
+% keytool -genkey -keyalg RSA -alias brooklyn \
+          -keystore <path-to-keystore-directory>/keystore.jks -storepass "mypassword"
\
+          -validity 365 -keysize 2048 -keypass "password"
+{% endhighlight %}
+
+Of course, the passwords above should be changed.  Omit those arguments above for the tool
to prompt you for the values.
+
+You will then be prompted to enter your name and organization details. This will use (or
create, if it does not exist)
+a keystore with the password `mypassword` - you should use your own secure password, which
will be the same password
+used in your brooklyn.properties (below). You will also need to replace `<path-to-keystore-directory>`
with the full 
+path of the folder where you wish to store your keystore. The keystore will contain the newly
generated key, 
+with alias `brooklyn` and password `password`.
+
+The certificate generated will be a self-signed certificate, which will cause a warning to
be displayed by a browser 
+when viewing the page. (The various browsers each have ways to import the certificate as
a trusted one, for test purposes.)
+
+For production servers, a valid signed certificate from a trusted certifying authority should
be used instead.
+Typically keys from a certifying authority are not provided in Java keystore format.  To
create a Java keystore from 
+existing certificates (CA certificate, and public and private keys), you must first create
a PKCS12 keystore from them,
+for example with `openssl`; this can then be converted into a Java keystore with `keytool`.
For example, with 
+a CA certificate `ca.pem`, and public and private keys `cert.pem` and `key.pem`, create the
PKCS12 store `server.p12`,
+and then convert it into a keystore `keystore.jks` as follows:
+ 
+{% highlight bash %}
+% openssl pkcs12 -export -in cert.pem -inkey key.pem \
+               -out server.p12 -name "brooklyn" \
+               -CAfile ca.pem -caname root -chain -passout pass:"password"
+
+% keytool -importkeystore \
+        -deststorepass "password" -destkeypass "password" -destkeystore keystore.jks \
+        -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass "password" \
+        -alias "brooklyn"
+{% endhighlight %}
+
+
+### Configuring Brooklyn for HTTPS
+
+How to do this depends on whether you are using the traditional or the Karaf distribution.
See either of
+
+* [Traditional Distribution](brooklyn_properties.html#https-configuration)
+* [Karaf Distribution](osgi-configuration.html#https-configuration)

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/index.md b/guide/ops/index.md
index a2f154a..e150a5d 100644
--- a/guide/ops/index.md
+++ b/guide/ops/index.md
@@ -13,7 +13,9 @@ children:
 - high-availability/
 - catalog/
 - rest.md
+- osgi.md
 - logging.md
+- https.md
 - externalized-configuration.md
 - requirements.md
 - production-installation.md

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/osgi-configuration.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi-configuration.md b/guide/ops/osgi-configuration.md
new file mode 100644
index 0000000..db2a6cd
--- /dev/null
+++ b/guide/ops/osgi-configuration.md
@@ -0,0 +1,118 @@
+---
+title: OSGi Configuration
+layout: website-normal
+---
+
+Configuration of Brooklyn when running under Karaf is largely done through standard Karaf
mechanisms. 
+The Karaf "Configuration Admin" subsystem is used to manage configuration values loaded at
first boot from the
+`.cfg` files in the `etc` directory of the distribution. In the Karaf command line these
can then be viewed
+and manipulated by the `config:` commands, see the Karaf documentation for full details.
+
+## Configuring Brooklyn Properties
+
+To configure the Brooklyn runtime create an `etc/brooklyn.cfg` file, following the standard
`brooklyn.properties`
+file format. Values can be viewed and managed dynamically via the OSGI configuration admin
commands in Karaf,
+e.g. `config:property-set`. The global `~/.brooklyn/brooklyn.properties` is still supported
and has higher
+priority for duplicate keys, but it's values can't be manipulated with the Karaf commands,
so its use is
+discouraged.
+
+You can use the standard `~/.brooklyn/brooklyn.properties` file to configure Brooklyn. Alternatively
+create `etc/brooklyn.cfg` inside the distribution folder (same file format). The keys in
the former override
+those in the latter.
+
+Web console related configuration is done through the corresponding Karaf mechanisms:
+
+  * The port is set in `etc/org.ops4j.pax.web.cfg`, key `org.osgi.service.http.port`.
+  * For authentication the JAAS realm "webconsole" is used; by default it will use any
+    SecurityProvider implementations configured in Brooklyn falling back to auto generating
+    the password. To configure a custom JAAS realm see the `jetty.xml` file in `brooklyn-server/karaf/jetty-config/src/main/resources`
+    and override it by creating a custom one in `etc` folder. Point the "webconsole" login
service
+    to the JAAS realm you would like to use.
+   * For other Jetty related configuration consult the Karaf and pax-web docs.
+
+## HTTPS Configuration
+
+See [HTTPS Configuration](https.html) for general information on configuring HTTPS.
+
+In `etc/org.ops4j.pax.web.cfg` in the Brooklyn Karaf distribution root, un-comment the settings:
+
+{% highlight properties %}
+org.osgi.service.http.port.secure=8443
+org.osgi.service.http.secure.enabled=true
+org.ops4j.pax.web.ssl.keystore=${karaf.home}/etc/keystores/keystore.jks
+org.ops4j.pax.web.ssl.password=password
+org.ops4j.pax.web.ssl.keypassword=password
+org.ops4j.pax.web.ssl.clientauthwanted=false
+org.ops4j.pax.web.ssl.clientauthneeded=false
+{% endhighlight %}
+
+replacing the passwords with appropriate values, and restart the server. Note the keystore
location is relative to 
+the installation root, but a fully qualified path can also be given, if it is desired to
use some separate pre-existing
+store.
+
+
+<!--
+----------
+-- NOTE: comment out this section on catalog as the behaviour described is not enabled by
default since
+-- https://github.com/apache/brooklyn-server/pull/233; re-enable this when that changes
+----------
+## Catalog in Karaf  
+With the traditional launcher, Brooklyn loads the initial contents of the catalog from a
`default.catalog.bom` file
+as described in the section on [installation](/guide/ops/production-installation.html). Brooklyn
finds Java 
+implementations to provide for certain things in blueprints (entities, enrichers etc.) by
scanning the classpath. 
+
+In the OSGI world this approach is not used, as each bundle only has visibility of its own
and its imported Java packages. 
+Instead, in Karaf, each bundle can declare its own `catalog.bom` file, in the root of the
bundle,
+with the catalog declarations for any entities etc. that the bundle contains.
+
+For example, the `catalog.bom` file for Brooklyn's Webapp bundle looks like (abbreviated):
+
+    brooklyn.catalog:
+        version: ...
+        items:
+        - id: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+          itemType: entity
+          item:
+            type: org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService
+            name: Node.JS Application
+        ...
+        - id: resilient-bash-web-cluster-template
+          itemType: template
+          name: "Template: Resilient Load-Balanced Bash Web Cluster with Sensors"
+          description: |
+            Sample YAML to provision a cluster of the bash/python web server nodes,
+            with sensors configured, and a load balancer pointing at them,
+            and resilience policies for node replacement and scaling
+          item:
+            name: Resilient Load-Balanced Bash Web Cluster (Brooklyn Example)
+
+In the above YAML the first item declares that the bundle provides an entity whose type is
+`org.apache.brooklyn.entity.webapp.nodejs.NodeJsWebAppService`, and whose name is 'Node.JS
Application'.  The second
+item declares that the bundle provides a template application, with id  `resilient-bash-web-cluster-template`,
and
+includes a description for what this is.
+
+## Configuring the applications in the Catalog
+
+When running some particular deployment of Brooklyn it may not be desirable for the sample
applications to appear in
+the catalog (for clarity, "application" here in the sense of an item with `itemType: template`).
+For example, if you have developed
+some bundle with your own application and added it to Karaf then you might want only your
own application to appear in
+the catalog.
+
+Brooklyn contains a mechanism to allow you to configure what bundles will add their applications
to the catalog.
+The Karaf configuration file `/etc/org.apache.brooklyn.core.catalog.bomscanner.cfg` contains
two properties,
+one `whitelist` and the other `blacklist`, that bundles must satisfy for their applications
to be added to the catalog.
+Each property value is a comma-separated list of regular expressions.  The symbolic id of
the bundle must match one of
+the regular expressions on the whitelist, and not match any expression on the blacklist,
if its applications
+are to be added to the bundle.  The default values of these properties are to admit all bundles,
and forbid none.
+
+## Caveats
+
+In the OSGi world specifying class names by string in Brooklyn's configuration will work
only
+for classes living in Brooklyn's core modules. Raise an issue or ping us on IRC if you find
+a case where this doesn't work for you. For custom SecurityProvider implementations refer
to the
+documentation of BrooklynLoginModule.
+    
+ END Catalog in Karaf comment -->
+
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/073edb1e/guide/ops/osgi.md
----------------------------------------------------------------------
diff --git a/guide/ops/osgi.md b/guide/ops/osgi.md
new file mode 100644
index 0000000..4cb07f2
--- /dev/null
+++ b/guide/ops/osgi.md
@@ -0,0 +1,56 @@
+---
+title: OSGi Distribution
+layout: website-normal
+children:
+- osgi-configuration.md
+---
+
+# Running Apache Brooklyn inside Karaf container
+
+The Apache Brooklyn Karaf based distribution lives in brooklyn-server/karaf/apache-brooklyn
folder.
+It's still in a testing stage so some features might not work as expected. Do reach out if
you
+find any problems.
+
+## Building
+
+{% highlight bash %}
+cd brooklyn-server
+mvn clean install
+cd karaf/apache-brooklyn/target
+tar -zxvf apache-brooklyn-{{ site.brooklyn-version }}.tar.gz
+cd apache-brooklyn-{{ site.brooklyn-version }}
+{% endhighlight %}
+
+## Running
+
+Start the instance using the following command
+
+{% highlight bash %}
+bin/karaf
+{% endhighlight %}
+
+This will launch the [Karaf console](https://karaf.apache.org/manual/latest/users-guide/console.html)
+where you can interact with the running instance. Note that Brooklyn has already started
at this point
+and is reachable at the usual web console url.
+
+To start in debug mode use
+
+{% highlight bash %}
+bin/karaf debug
+{% endhighlight %}
+
+and connect to port 5005 using your debugger.
+
+To pause startup until the debugger is connected you can use
+
+{% highlight bash %}
+JAVA_DEBUG_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005'
bin/karaf debug
+{% endhighlight %}
+
+The Karaf container will keep state like installed bundles and configuration between restarts.
+To reset any changes add **clean** to the cli arguments.
+
+## Configuring
+
+Configuration of Brooklyn when running under Karaf is largely done through standard Karaf
mechanisms. 
+See the page on [OSGI Configuration](osgi-configuration.html) for details.
\ No newline at end of file


Mime
View raw message