Return-Path: X-Original-To: apmail-brooklyn-commits-archive@minotaur.apache.org Delivered-To: apmail-brooklyn-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id B4E1C10D30 for ; Tue, 20 Jan 2015 16:12:49 +0000 (UTC) Received: (qmail 11400 invoked by uid 500); 20 Jan 2015 16:12:49 -0000 Delivered-To: apmail-brooklyn-commits-archive@brooklyn.apache.org Received: (qmail 11377 invoked by uid 500); 20 Jan 2015 16:12:49 -0000 Mailing-List: contact commits-help@brooklyn.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.incubator.apache.org Delivered-To: mailing list commits@brooklyn.incubator.apache.org Received: (qmail 11368 invoked by uid 99); 20 Jan 2015 16:12:49 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 20 Jan 2015 16:12:49 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED,T_RP_MATCHES_RCVD,WEIRD_PORT X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Tue, 20 Jan 2015 16:12:40 +0000 Received: (qmail 8947 invoked by uid 99); 20 Jan 2015 16:12:20 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 20 Jan 2015 16:12:20 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 50A53E0831; Tue, 20 Jan 2015 16:12:19 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: heneveld@apache.org To: commits@brooklyn.incubator.apache.org Date: Tue, 20 Jan 2015 16:12:27 -0000 Message-Id: <66663b7ba37c4a83b2900f80e34728d1@git.apache.org> In-Reply-To: <413964b101ab428da3e9bbc4e51682bd@git.apache.org> References: <413964b101ab428da3e9bbc4e51682bd@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [09/13] incubator-brooklyn git commit: lots more tidy-up of docs, esp in ops X-Virus-Checked: Checked by ClamAV on apache.org lots more tidy-up of docs, esp in ops also removing the negative margin / extra padding above headers in favour of an auto-scroll technique to position window appropriately (not blocked by menu bar) Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/3add5d21 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/3add5d21 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/3add5d21 Branch: refs/heads/master Commit: 3add5d210092e71c0f35313709aba45e226bb958 Parents: a24f148 Author: Alex Heneveld Authored: Tue Jan 20 03:18:50 2015 +0000 Committer: Alex Heneveld Committed: Tue Jan 20 04:26:17 2015 +0000 ---------------------------------------------------------------------- .../DownloadProducerFromProperties.java | 2 +- .../management/entitlement/Entitlements.java | 1 + docs/README.md | 5 + docs/_build/build.sh | 10 +- docs/_includes/java_link.html | 6 +- docs/_includes/sidemenu.html | 6 +- docs/_includes/topmenu.html | 5 +- docs/_plugins/brooklyn_metadata.rb | 3 + docs/guide/dev/env/index.md | 2 +- docs/guide/dev/index.md | 6 + .../guide/dev/tips/debugging-remote-brooklyn.md | 46 ++- docs/guide/java/common-usage.md | 100 +++++- docs/guide/ops/brooklyn_properties.md | 173 ++++++++++ docs/guide/ops/cli.md | 143 ++++++++ docs/guide/ops/index.md | 5 +- docs/guide/ops/launching/index.md | 143 -------- docs/guide/ops/locations/index.md | 6 +- docs/guide/ops/locations/more-locations.md | 2 +- docs/guide/ops/locations/ssh-keys.md | 37 ++- docs/guide/ops/logging.md | 46 +++ docs/guide/ops/runtime-management/index.md | 325 ------------------- .../webconsole-dashboard-w400.png | Bin 137463 -> 0 bytes .../runtime-management/webconsole-dashboard.png | Bin 214723 -> 0 bytes .../webconsole-detail-w400.png | Bin 111993 -> 0 bytes .../runtime-management/webconsole-detail.png | Bin 165359 -> 0 bytes docs/guide/start/_my-web-cluster.yaml | 8 +- docs/guide/start/blueprints.md | 70 ++-- docs/guide/start/config.md | 52 --- docs/guide/start/index.md | 1 - docs/guide/start/managing.md | 26 +- docs/guide/start/running.md | 70 +--- .../yaml/chef/advanced-chef-integration.md | 4 +- docs/guide/yaml/configuring-vms.md | 2 +- docs/guide/yaml/creating-yaml.md | 2 +- docs/guide/yaml/multiple-services.md | 39 ++- docs/guide/yaml/mutlitple-services.md | 100 ------ docs/guide/yaml/setting-locations.md | 17 +- docs/style/css/_basic.scss | 6 - docs/style/css/_main_container.scss | 18 +- docs/website/community/index.md | 2 +- docs/website/developers/index.md | 2 +- docs/website/documentation/index.md | 11 +- docs/website/documentation/install-on-server.md | 17 +- docs/website/documentation/passwordless-ssh.md | 29 -- docs/website/documentation/ssh-key.md | 9 - docs/website/documentation/todo.md | 7 - docs/website/learnmore/blueprint-tour.md | 2 +- docs/website/learnmore/theory.md | 3 +- 48 files changed, 720 insertions(+), 849 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/core/src/main/java/brooklyn/entity/drivers/downloads/DownloadProducerFromProperties.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/brooklyn/entity/drivers/downloads/DownloadProducerFromProperties.java b/core/src/main/java/brooklyn/entity/drivers/downloads/DownloadProducerFromProperties.java index 16de798..55696a4 100644 --- a/core/src/main/java/brooklyn/entity/drivers/downloads/DownloadProducerFromProperties.java +++ b/core/src/main/java/brooklyn/entity/drivers/downloads/DownloadProducerFromProperties.java @@ -90,7 +90,7 @@ import com.google.common.collect.Maps; * * A URL can be a "template", where things of the form ${version} will be substituted for the value * of "version" provided for that entity. The freemarker template engine is used to convert URLs - * (see http://freemarker.org). For example, one could use the URL: * 
  * {@code
  * http://repo.acme.com/${simpletype}-${version}.${fileSuffix!tar.gz}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/core/src/main/java/brooklyn/management/entitlement/Entitlements.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/brooklyn/management/entitlement/Entitlements.java b/core/src/main/java/brooklyn/management/entitlement/Entitlements.java
index a555cac..0c4a232 100644
--- a/core/src/main/java/brooklyn/management/entitlement/Entitlements.java
+++ b/core/src/main/java/brooklyn/management/entitlement/Entitlements.java
@@ -292,6 +292,7 @@ public class Entitlements {
     public static EntitlementManager newManager(ManagementContext mgmt, BrooklynProperties brooklynProperties) {
         EntitlementManager result = newGlobalManager(mgmt, brooklynProperties);
         // TODO read per user settings from brooklyn.properties, if set there ?
+        // update brooklyn_properties.md when done
         return result;
     }
     private static EntitlementManager newGlobalManager(ManagementContext mgmt, BrooklynProperties brooklynProperties) {

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index c2fb5e7..5d1b386 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -218,6 +218,11 @@ using the instructions in `build.sh` as a guide.)
 A typical update consists of the following commands (or a subset),
 copied to `${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public}`:
 
+    # ensure svn repo is up-to-date (very painful otherwise)
+    cd ${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public}
+    svn up
+    cd -
+
     # main website, relative to / 
     _build/build.sh website-root --install
     

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/_build/build.sh
----------------------------------------------------------------------
diff --git a/docs/_build/build.sh b/docs/_build/build.sh
index eb9215a..cca232e 100755
--- a/docs/_build/build.sh
+++ b/docs/_build/build.sh
@@ -161,7 +161,15 @@ function test_site() {
   echo "Running htmlproof on _site"
   mkdir -p target
   LOG="target/htmlproof.log"
-  htmlproof _site --href_ignore "https?://127.*" --alt_ignore ".*" 2>&1 | tee $LOG
+  # TODO for now exclude all javadoc; in time it would be nice to police that also
+  # (but not sure this is properly working yet)
+  htmlproof _site \
+    --href_ignore "https?://127.*" \
+    --href_ignore "https?://github.com/apache/incubator-brooklyn/edit/.*" \
+    --href_ignore "/" \
+    --alt_ignore ".*" \
+    --file_ignore ".*/javadoc/.*" \
+    2>&1 | tee $LOG
 }
 
 function make_jekyll() {

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/_includes/java_link.html
----------------------------------------------------------------------
diff --git a/docs/_includes/java_link.html b/docs/_includes/java_link.html
index b296652..01ac1d7 100644
--- a/docs/_includes/java_link.html
+++ b/docs/_includes/java_link.html
@@ -8,9 +8,9 @@ usage:
 
 
 {% endcomment %}{% if include.project_subpath %}{{ include.class_name }}
-  (javadoc, 
-   src)
-{% else %}
+  (javadoc, 
+   src){% comment %}
+{% endcomment %}{% else %}
 {{ include.class_name }}
 {% endif %}{% comment %}
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/_includes/sidemenu.html
----------------------------------------------------------------------
diff --git a/docs/_includes/sidemenu.html b/docs/_includes/sidemenu.html
index 808d9e2..ec3cf1c 100644
--- a/docs/_includes/sidemenu.html
+++ b/docs/_includes/sidemenu.html
@@ -120,8 +120,12 @@ var highlight_section = function() {
      if (item && item.length) {
        if (highlight_section_last_top == -1 || !highlight_section_completed) {
          // just opening page - take item matching hash, or otherwise the first item visible
-         if (item.selector === window.location.hash || (item.offset().top > highlight_section_new_top - 15 && !found_top)) {
+         if (item.selector === window.location.hash || (item.offset().top > highlight_section_new_top - 20 && !found_top)) {
            found_top = true;
+           if (item.selector === window.location.hash && item.offset().top < highlight_section_new_top + 60) {
+             // because of our top header, we need to scroll 64px down from any link
+             $('html, body').animate({scrollTop: item.offset().top - 64}, 0);
+           }
            return item;
          }
        } else if (scroll_advancing) {

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/_includes/topmenu.html
----------------------------------------------------------------------
diff --git a/docs/_includes/topmenu.html b/docs/_includes/topmenu.html
index 37a39d0..0275794 100644
--- a/docs/_includes/topmenu.html
+++ b/docs/_includes/topmenu.html
@@ -65,8 +65,9 @@
               data-toggle="tooltip" data-placement="bottom" title="Twitter: @brooklyncentral"/>
             
-            
-            
+            
+            
          
       
       

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/_plugins/brooklyn_metadata.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/brooklyn_metadata.rb b/docs/_plugins/brooklyn_metadata.rb
index 89d82aa..c50f844 100644
--- a/docs/_plugins/brooklyn_metadata.rb
+++ b/docs/_plugins/brooklyn_metadata.rb
@@ -61,6 +61,9 @@ module BrooklynMetadata
           "is_snapshot" => is_snapshot,
           "url" => url_set
       }
+      # config is preferred of data, because you can write just {{ site.brooklyn.xxx }},
+      # but some places reference site.data.brooklyn
+      site.data['brooklyn'] = site.config['brooklyn']
   
     end
   end

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/dev/env/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/index.md b/docs/guide/dev/env/index.md
index ef00e89..8e1e422 100644
--- a/docs/guide/dev/env/index.md
+++ b/docs/guide/dev/env/index.md
@@ -10,4 +10,4 @@ children:
 - ide/
 ---
 
-TODO
\ No newline at end of file
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
index ee62245..dd709de 100644
--- a/docs/guide/dev/index.md
+++ b/docs/guide/dev/index.md
@@ -15,6 +15,9 @@ children:
 - tips/debugging-remote-brooklyn.md
 ---
 
+{% comment %}
+TODO
+
 The Developer Guide contains information on working with the Brooklyn codebase.
 
 Of particular note to people getting started, there is:
@@ -29,3 +32,6 @@ And for the Brooklyn codebase itself, see:
 * Areas of Special Hairiness
 
 (All links are TODO.)
+{% endcomment %}
+
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/dev/tips/debugging-remote-brooklyn.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/debugging-remote-brooklyn.md b/docs/guide/dev/tips/debugging-remote-brooklyn.md
index 0f1677c..4d14e5f 100644
--- a/docs/guide/dev/tips/debugging-remote-brooklyn.md
+++ b/docs/guide/dev/tips/debugging-remote-brooklyn.md
@@ -19,27 +19,25 @@ Thankfully, the tools are available to do this, and setting it up is quite strai
 The first step is to ensure that your local copy of the source code is at the version used to build the remote Brooklyn
 instance. The git commit that was used to build Brooklyn is available via the REST API:
 
-```
-http://:/v1/server/version
-```
+    http://:/v1/server/version
 
 This should return details of the build as a JSON string similar to the following (formatted for clarity):
 
-```JSON
+{% highlight json %}
 {
     "version": "0.7.0-SNAPSHOT",
     "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224",
     "buildBranch": "UNKNOWN"
 }
-```
+{% endhighlight %}
 
 The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now
 checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo:
 
-```
-git checkout c0fdc15291702281acdebf1b11d431a6385f5224
-mvn clean install -DskipTests
-```
+{% highlight bash %}
+% git checkout c0fdc15291702281acdebf1b11d431a6385f5224
+% mvn clean install -DskipTests
+{% endhighlight %}
 
 Whilst building the code isn't strictly necessary, it can help prevent some IDE issues.
 
@@ -48,25 +46,24 @@ By default, Brooklyn does not listen for a debugger to be attached, however this
 which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the
 root of the Brooklyn installation:
 
-```
+{% highlight bash %}
 # NOTE: Running this kill command will lose existing apps and machines if persistence is disabled.
-kill `cat pid_java`
-export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
-bin/brooklyn launch &
-```
+% kill `cat pid_java`
+% export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
+% bin/brooklyn launch &
+{% endhighlight %}
 
 If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why
 we have prepended the agentlib settings with these values here.
 
 You should see the following in the console output:
 
-```
-Listening for transport dt_socket at address: 8888
-```
+    Listening for transport dt_socket at address: 8888
 
 This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached.
 
 ## Creating an SSH tunnel
+
 If port 8888 is accessible on the remote Brooklyn server, then you can skip this step and simply use the address of the
 server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE) section below. It will normally be possible to
 make the port accessible by configuring Security Groups, iptables, endpoints etc., but for a quick ad-hoc connection it's
@@ -74,7 +71,7 @@ usually simpler to create an SSH tunnel. This will create an open SSH connection
 on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local
 machine:
 
-```
+{% highlight bash %}
 # replace this with the address or IP of the remote Brooklyn node
 REMOTE_HOST=
 # if you wish to use a different port, this value must match the port specified in the JAVA_OPTS
@@ -86,15 +83,12 @@ SSH_USER=root
 # The private key file used to SSH to the remote node. If you use a password, see the alternative command below
 PRIVATE_KEY_FILE=~/.ssh/id_rsa 
 
-ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-
-```
+% ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
+{% endhighlight %}
 
 If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so:
 
-```
-ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
-```
+    ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
 
 If you are using a password to connect, you will be prompted to enter your password to connect to the remote node upon
 running the SSH command.
@@ -104,10 +98,12 @@ tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible
 debugging.
 
 ##  Connecting your IDE
+
 Setting up your IDE will differ depending upon which IDE you are using. Instructions are given here for Eclipse and
 IntelliJ, and have been tested with Eclipse Luna and IntelliJ Ultimate 14.
 
 ### Eclipse Setup
+
 To debug using Eclipse, first open the Brooklyn project in Eclipse (see [IDE Setup](../env/ide/)).
 
 Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the 
@@ -119,6 +115,7 @@ Connection Type should be set to 'Standard (Socket Attach)'. The Host should be
 and the Port should be set to 8888. Click 'Debug' to start debugging.
 
 ### IntelliJ Setup
+
 To debug using IntelliJ, first open the Brooklyn project in IntelliJ (see [IDE Setup](../env/ide/)).
 
 Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the
@@ -134,6 +131,7 @@ configuration, then select the configuration from the configurations drop-down a
 debugging.
 
 ### Testing
+
 The easiest way to test that remote debugging has been setup correctly is to set a breakpoint and see if it is hit. An
 easy place to start is to create a breakpoint in the `ServerResource.java` class, in the `getStatus()` 
 method. 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/java/common-usage.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/common-usage.md b/docs/guide/java/common-usage.md
index 3e631a2..8f0ed32 100644
--- a/docs/guide/java/common-usage.md
+++ b/docs/guide/java/common-usage.md
@@ -3,6 +3,8 @@ title: Common Classes and Entities
 layout: website-normal
 ---
 
+
+
 ### Entity Class Hierarchy
 
 By convention in Brooklyn the following words have a particular meaning, both as types (which extend ``Group``, which extends ``Entity``) and when used as words in other entities (such as ``TomcatFabric``):
@@ -39,4 +41,100 @@ These include:
 - **PaaS**: Cloud Foundry, Stackato; OpenShift
 
 
-®
+### Sensors
+
+Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example:
+{% highlight java %}
+/** a sensor for saying hi (illustrative), carrying a String value 
+    which is typically the name of the person to whom we are saying hi */
+public static final Sensor HELLO_SENSOR = ...
+
+{% endhighlight %}
+
+If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs.
+
+Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``.
+
+Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` – an attribute value being reported on change or periodically – or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT".
+
+
+
+Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON:
+        
+    {
+      config : {
+        url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
+        status : "running"
+      }
+      workrate : {
+        msgsPerSec : 432
+      }
+    }
+
+Sensor values are defined as statics, which can be used to programmatically drive the subscription.
+
+A range of `Feed` instances are available to simplify reading sensor information.
+
+
+### Effectors
+
+Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows:
+
+{% highlight java %}
+/** an effector which returns no value,
+    but which causes the entity to emit a HELLO sensor event */
+public static Effector SAY_HI = ...
+
+{% endhighlight %}
+
+Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map.
+
+Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning.
+
+The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location).
+
+It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
+
+
+### Tasks and the Execution Manager
+
+The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**.
+Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface.
+
+By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling
+``ExecutionManager.getTasksWithTag(...)``.
+
+The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended.
+    
+    ExecutionManager em = []
+    em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
+    em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
+    assert em.getTasksWithTag("a").size()==2
+    assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
+    Thread.sleep(1500)
+    assert em.getTasksWithTag("a").size()==2
+    assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
+
+It is possible to define `ParallelTask` and sequential `Task` instancess 
+and to specify inter-task relationships with `TaskPreprocessor` instances. 
+This allows building quite sophisticated workflows relatively easily.
+
+Continuing the example above, submitting a `SequentialTask` 
+or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` 
+will cause ``Two Mississippi`` to run after ``One Mississippi`` completes.
+
+It is also possible to register `ScheduledTask` instances which run periodically.
+
+**The `Tasks` factory supplies a number of conveniences including builders to make working with tasks easier
+and should be the entry point in most cases.**
+
+
+
+### Subscriptions and the Subscription Manager
+
+In addition to scheduled tasks, tasks can triggered by subscriptions on other events including sensors.
+
+To register low-level listeners to events, use the `SubscriptionManager` API.
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/brooklyn_properties.md b/docs/guide/ops/brooklyn_properties.md
new file mode 100644
index 0000000..0485afe
--- /dev/null
+++ b/docs/guide/ops/brooklyn_properties.md
@@ -0,0 +1,173 @@
+---
+title: brooklyn.properties
+layout: website-normal
+children:
+- { section: Quick Setup }
+- { section: Locations }
+- { section: Java }
+- { section: Authentication }
+- { section: Entitlements }
+- { section: HTTPS Configuration }
+---
+
+The file `~/.brooklyn/brooklyn.properties` is read when Brooklyn starts
+to load server configuration values.
+A different properties file can be specified either additionally or instead
+through [CLI options](cli.html#configuration). 
+
+A template [brooklyn.properties]({{brooklyn_properties_url_path}}) file is available,
+with abundant comments.
+
+
+## Quick Setup
+
+The most common properties set in this file are for access control.
+Without this, Brooklyn will bind only to localhost or will create a random
+password written to the log for use on other networks.
+The simplest way to specify users and passwords is:
+ 
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin,bob
+brooklyn.webconsole.security.user.admin.password=AdminPassw0rd
+brooklyn.webconsole.security.user.bob.password=BobPassw0rd
+{% endhighlight %}
+
+The properties file *must* have permissions 600 
+(i.e. readable and writable only by the file's owner),
+for some security.
+
+In many cases, it is preferable instead to use an external credentials store such as LDAP
+or at least to have passwords in this file.
+Information on configuring these is [below](#authentication). 
+
+If coming over a network it is highly recommended additionally to use `https`.
+This can be configured with:
+
+{% highlight properties %}
+brooklyn.webconsole.security.https.required=true
+{% endhighlight %}
+
+More information, including setting up a certificate, is described [further below](#https-configuration).
+
+
+## Locations
+
+Information on defining locations in the `brooklyn.properties` file is available [here](locations/).
+
+
+## Java
+
+Arbitrary data can be set in the `brooklyn.properties`.
+This can be accessed in java using `ManagementContext.getConfig(KEY)`.
+
+
+## Authentication
+
+**Security Providers** are the mechanism by which different authentication authorities are plugged in to Brooklyn.
+These can be configured by specifying `brooklyn.webconsole.security.provider` equal 
+to the name of a class implementing `SecurityProvider`.
+An implementation of this could point to Spring, LDAP, OpenID or another identity management system.
+
+The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords
+which should be specified as configuration parameters e.g. in `brooklyn.properties`.
+This configuration could look like:
+
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users.
+
+To generate this, the brooklyn CLI can be used:
+{% highlight bash %}
+brooklyn generate-password --user admin
+
+Enter password: 
+Re-enter password: 
+
+Please add the following to your brooklyn.properies:
+
+brooklyn.webconsole.security.users=admin
+brooklyn.webconsole.security.user.admin.salt=OHDf
+brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
+{% endhighlight %}
+
+Alternatively, in dev/test environments where a lower level of security is required,
+the syntax `brooklyn.webconsole.security.user.=` can be used for
+each `` specified in the `brooklyn.webconsole.security.users` list.
+
+Other security providers available include:
+
+* **No one**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider`
+  will block all logins (e.g. if not using the web console)
+* **No security**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
+  will allow logins with no credentials (e.g. in secure dev/test environments) 
+* **LDAP**: `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.LdapSecurityProvider`
+  will cause Brooklyn to call to an LDAP server to authenticate users;
+  `brooklyn.webconsole.security.ldap.{url,realm}` must also be set as `brooklyn.properties`
+
+
+## Entitlements
+
+In addition to login access, fine-grained permissions including 
+seeing entities, creating applications, seeing sensors, and invoking effectors
+can be defined on a per-user *and* per-target (e.g. which entity/effector) basis
+using an **Entitlement Manager**.
+
+This can be set globally with the property:
+
+{% highlight properties %}
+brooklyn.entitlements.global=
+{% endhighlight %}
+
+The default entitlement manager is one which responds to per-user entitlement rules,
+and understands:
+
+* `root`:  full access, including to the Groovy console
+* `readonly`:  read-only access to almost all information
+* `minimal`:  access only to server stats, for use by monitoring systems
+
+{% comment %}
+TODO in Entitlements
+
+These keywords are also understood at the `global` level, so to grant full access to `admin`
+but read-only access to any other authenticated users, you can write:
+
+{% highlight properties %}
+brooklyn.entitlements.global=readonly
+brooklyn.entitlements.user.admin=root
+{% endhighlight %}
+
+{% endcomment %}
+
+For more information, see {% include java_link.html class_name="EntitlementManager" package_path="brooklyn/management/entitlement" project_subpath="api" %}.
+
+
+## HTTPS Configuration
+
+To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the
+following command:
+
+{% highlight bash %}
+% keytool -genkey -keyalg RSA -alias brooklyn -keystore /server.key -storepass mypassword -validity 360 -keysize 2048
+{% endhighlight %}
+
+You will then be prompted to enter you name and organization details. This will create 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 `` with the full path of the folder where you wish to store your
+keystore. 
+
+The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server 
+name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed 
+certificate from a trusted certifying authority should be used instead
+
+To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
+
+{% highlight properties %}
+brooklyn.webconsole.security.https.required=true
+brooklyn.webconsole.security.keystore.url=/server.key
+brooklyn.webconsole.security.keystore.password=mypassword
+brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
+{% endhighlight %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/cli.md b/docs/guide/ops/cli.md
new file mode 100644
index 0000000..3e44c62
--- /dev/null
+++ b/docs/guide/ops/cli.md
@@ -0,0 +1,143 @@
+---
+title: CLI
+layout: website-normal
+---
+
+To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
+
+{% highlight bash %}
+% bin/brooklyn launch
+{% endhighlight %}
+
+With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
+No password is set, but the server is listening only on the loopback network interface for security.
+Once [security is configured](brooklyn_properties.html), Brooklyn will listen on all network interfaces by default.
+
+You may wish to [add Brooklyn to your path](#path-setup);
+assuming you've done this, to get information the supported CLI options 
+at any time, just run `brooklyn help`:
+
+{% highlight bash %}
+% bin/brooklyn help
+
+usage: brooklyn [(-q | --quiet)] [(-v | --verbose)]  []
+
+The most commonly used brooklyn commands are:
+    help     Display help information about brooklyn
+    info     Display information about brooklyn
+    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
+
+See 'brooklyn help ' for more information on a specific command.
+{% endhighlight %}
+
+
+
+## Configuration
+
+Brooklyn can read configuration from a variety of places:
+        
+* the file `~/.brooklyn/brooklyn.properties` (unless `--noGlobalBrooklynProperties` is specified)
+* another file, if the `--localBrooklynProperties `
+* ``-D`` defines on the brooklyn (java) command-line
+* shell environment variables
+
+These properties are described in more detail [here](brooklyn_properties.html).
+
+
+
+## Path Setup
+
+In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory:
+
+{% highlight bash %}
+BROOKLYN_HOME=/path/to/brooklyn/
+export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
+{% endhighlight %}
+
+
+## Running from a Source Build
+
+Here is an example of the commands you might run to get the Brooklyn code, 
+compile it and launch an application:
+
+{% highlight bash %}
+git clone https://github.com/apache/incubator-brooklyn.git
+cd brooklyn
+mvn clean install -DskipTests
+BROOKLYN_HOME=$(pwd)
+export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
+export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
+brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
+{% endhighlight %}
+
+
+## Extending the Classpath
+
+You can add things to the Brooklyn classpath in a number of ways:
+
+* Add ``.jar`` files to Brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath.
+* Add ``.jar`` files to Brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath.
+* Add resources to Brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath.
+* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the Brooklyn classpath.
+
+
+## Cloud Explorer
+
+The `brooklyn` command line tool includes support for querying (and managing) cloud
+compute resources and blob-store resources. 
+
+For example, `brooklyn cloud-compute list-instances --location aws-ec2:eu-west-1`
+will use the AWS credentials from `brooklyn.properties` and list the VM instances
+running in the given EC2 region.
+
+Use `brooklyn help` and `brooklyn help cloud-compute` to find out more information.
+
+This functionality is not intended as a generic cloud management CLI, but instead 
+solves specific Brooklyn use-cases. The main use-case is discovering the valid 
+configuration options on a given cloud, such as for `imageId` and `hardwareId`.
+
+
+### Cloud Compute
+
+The command `brooklyn cloud-compute` has the following options:
+
+* `list-images`: lists VM images within the given cloud, which can be chosen when
+  provisioning new VMs.
+  This is useful for finding the possible values for the `imageId` configuration.
+
+* `get-image   ...`: retrieves metadata about the specific images.
+
+* `list-hardware-profiles`: lists the ids and the details of the hardware profiles
+  available when provisioning. 
+  This is useful for finding the possible values for the `hardwareId` configuration.
+
+* `default-template`: retrieves metadata about the image and hardware profile that will
+  be used by Brooklyn for that location, if no additional configuration options
+  are supplied.
+
+* `list-instances`: lists the VM instances within the given cloud.
+
+* `terminate-instances   ...`: Terminates the instances with
+  the given ids.
+
+
+## Blob Store
+
+The command `brooklyn cloud-blobstore` is used to access a given object store, such as S3
+or Swift. It has the following options:
+
+* `list-containers`: lists the containers (i.e. buckets in S3 terminology) within the 
+  given object store.
+
+* `list-container `: lists all the blobs (i.e. objects) contained within 
+  the given container.
+
+* `blob --container  --blob `: retrieves the given blob
+  (i.e. object), including metadata and its contents.
+
+
+## Other Topics
+
+The CLI arguments for [persistence and HA](persistence/)
+are described separately,
+as is [detailed configuration](brooklyn_properties.html).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index b224852..6b523f6 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -2,11 +2,12 @@
 title: Operations
 layout: website-normal
 children:
+- cli.md
+- brooklyn_properties.md
 - locations/
 - persistence/
-- launching/
 - catalog/
-- runtime-management/
+- logging.md
 ---
 
 {% include list-children.html %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/launching/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/launching/index.md b/docs/guide/ops/launching/index.md
deleted file mode 100644
index c35281e..0000000
--- a/docs/guide/ops/launching/index.md
+++ /dev/null
@@ -1,143 +0,0 @@
----
-title: Launching Brooklyn
-layout: website-normal
----
-
-There are several ways to launch applications with brooklyn, and useful configuration options,
-as well as a debug-view web console.
-
-This chapter describes how to launch brooklyn.
-
-
-Startup Configuration
----------------------
-
-brooklyn can read configuration from a variety of places:
-
-* the file ``~/.brooklyn/brooklyn.properties``
-* ``-D`` defines on the brooklyn (java) command-line
-* shell environment variables
-
-Default properties are described in the Javadoc and code of the class ``BrooklynProperties``,
-but some of the most common ones are:
- 
-{% highlight properties %}
-brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55
-brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa       # use specified key (default is ~/.ssh/id_rsa)
-brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub    # (optional, inferred from previous if omitted)
-{% endhighlight %} 
-
-These can be specified as a shell environment variable or as a Java system property,
-although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY`` 
-is supported and recommended.
-
-The recommended approach is to use the properties file, with permissions 600 
-(i.e. readable and writable only by the file's owner).
-
-
-Command Line Interface
-----------------------
-
-Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application.
-
-In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory:
-
-{% highlight bash %}
-BROOKLYN_HOME=/path/to/brooklyn/
-export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
-{% endhighlight %}
-
-If you have set this up correctly you should be able to invoke the ```brooklyn``` command:
-
-{% highlight bash %}
-brooklyn
-{% endhighlight %}
-
-To get information about all the supported cli options just run:
-
-{% highlight bash %}
-brooklyn help
-usage: brooklyn [(-q | --quiet)] [(-v | --verbose)]  []
-
-The most commonly used brooklyn commands are:
-    help     Display help information about brooklyn
-    info     Display information about brooklyn
-    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
-
-See 'brooklyn help ' for more information on a specific command.
-{% endhighlight %}
-
-Here is an example of the commands you might run to get the Brooklyn code, compile it and launch an application:
-
-{% highlight bash %}
-git clone https://github.com/apache/incubator-brooklyn.git
-cd brooklyn
-mvn clean install -DskipTests
-BROOKLYN_HOME=$(pwd)
-export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
-export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
-brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
-{% endhighlight %}
-
-You can add things to the brooklyn classpath in a number of ways:
-
-* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath.
-* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath.
-* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath.
-* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn classpath.
-
-
-### Cloud Explorer
-
-The `brooklyn` command line tool includes support for querying (and managing) cloud
-compute resources and blob-store resources. 
-
-For example, `brooklyn cloud-compute list-instances --location aws-ec2:eu-west-1`
-will use the AWS credentials from brooklyn.properties, and will list the VM instances
-running in the given EC2 region.
-
-Use `brooklyn help` and `brooklyn help cloud-compute` to find out more information.
-
-This functionality is not intended as a generic cloud management CLI, but instead 
-solves specific brooklyn use-cases. The main use-case is discovering the valid 
-configuration options on a given cloud, such as for `imageId` and `hardwareId`.
-
-
-#### Cloud Compute
-
-The command `brooklyn cloud-compute` has the following options:
-
-* `list-images`: lists VM images within the given cloud, which can be chosen when
-  provisioning new VMs.
-  This is useful for finding the possible values for the `imageId` configuration.
-
-* `get-image   ...`: retrieves metadata about the specific images.
-
-* `list-hardware-profiles`: lists the ids and the details of the hardware profiles
-  available when provisioning. 
-  This is useful for finding the possible values for the `hardwareId` configuration.
-
-* `default-template`: retrieves metadata about the image and hardware profile that will
-  be used by Brooklyn for that location, if no additional configuration options
-  are supplied.
-
-* `list-instances`: lists the VM instances within the given cloud.
-
-* `terminate-instances   ...`: Terminates the instances with
-  the given ids.
-
-
-#### Blob Store
-
-The command `brooklyn cloud-blobstore` is used to access a given object store, such as S3
-or Swift. It has the following options:
-
-* `list-containers`: lists the containers (i.e. buckets in S3 terminology) within the 
-  given object store.
-
-* `list-container `: lists all the blobs (i.e. objects) contained within 
-  the given container.
-
-* `blob --container  --blob `: retrieves the given blob
-  (i.e. object), including metadata and its contents.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md
index b5e5afd..810f7b8 100644
--- a/docs/guide/ops/locations/index.md
+++ b/docs/guide/ops/locations/index.md
@@ -60,7 +60,7 @@ brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1
 
 And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
 
-The Getting Started [template brooklyn.properties](../start/brooklyn.properties) contains more examples 
+The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples 
 of configuring cloud endpoints, including information on credential types used in different clouds.
 
 
@@ -264,5 +264,5 @@ brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassph
 
 ### Other Location Topics
 
-* [More Locations](more-locations.md)
-* [SSH Keys](ssh-keys.md)
+* [More Locations](more-locations.html)
+* [SSH Keys](ssh-keys.html)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/locations/more-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/more-locations.md b/docs/guide/ops/locations/more-locations.md
index 35e2398..994eaf7 100644
--- a/docs/guide/ops/locations/more-locations.md
+++ b/docs/guide/ops/locations/more-locations.md
@@ -50,6 +50,6 @@ and then to `acct2`.
 
 ### The Server Pool
 
-The {% include java_link.html package_path="brooklyn/entity/pool" project_subpath="software/base" %}
+The {% include java_link.html class_name="ServerPool" package_path="brooklyn/entity/pool" project_subpath="software/base" %}
 entity type allows defining an entity which becomes available as a location.
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/locations/ssh-keys.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/ssh-keys.md b/docs/guide/ops/locations/ssh-keys.md
index 6839f62..f805253 100644
--- a/docs/guide/ops/locations/ssh-keys.md
+++ b/docs/guide/ops/locations/ssh-keys.md
@@ -40,18 +40,43 @@ and that your key is authorized for ssh access:
 $ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
 {% endhighlight %}
 
-You should be able to run `ssh localhost` without any password required.
+Now verify that your setup by running the command: `ssh localhost echo hello world`
+
+If your setup is correct, you should see `hello world` printed back at you.
+
+On the first connection, you may see a message similar to this:
+
+
+The authenticity of host 'localhost (::1)' can't be established.
+RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
+Are you sure you want to continue connecting (yes/no)?
+

+
+Simply answer 'yes' and then repeat the command again.
+
+If this isn't the case, see below. 
 
-**Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
-as described [here](index.html#os-setup)
 
-**MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
 
 
 ### Potential Problems
 
-* `~/.ssh/` or files in that directory too open: they should be visible only to the user (apart from public keys),
-  both on the source machine and the target machine
+* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
+
+* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
+  as described [here](index.html#os-setup).
+  If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
+  If it does *not* ask for a passphrase, then your key has no passphrase.
+  If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
+
+* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
+  if not, create one as described above
+  
+* `~/.ssh/` or files in that directory may have permissions they shouldn't: 
+  they should be visible only to the user (apart from public keys),
+  both on the source machine and the target machine.
+  You can verify this with `ls -l ~/.ssh/`:  lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories). 
+  If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
  
 * Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
   if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/logging.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/logging.md b/docs/guide/ops/logging.md
new file mode 100644
index 0000000..fc1da3c
--- /dev/null
+++ b/docs/guide/ops/logging.md
@@ -0,0 +1,46 @@
+---
+title: Logging
+layout: website-normal
+---
+
+
+Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including `logback`, 
+`java.util.logging` and `log4j`.
+
+The convention for log levels is as follows:
+
+* `ERROR` and above:  exceptional situations which indicate that something has unexpectedly failed or
+some other problem has occured which the user is expected to attend to
+* `WARN`:  exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response
+* `INFO`:  a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer
+* `DEBUG` and lower:  detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances.
+
+Loggers follow the ``package.ClassName`` naming standard.  
+
+## Standard Configuration
+
+A `logback.xml` file is included in the `conf/` directly of the Brooklyn distro;
+this is read by `brooklyn` at launch time.  Changes to the logging configuration,
+such as new appenders or different log levels, can be made directly in this file
+or in a new file included from this.
+
+
+## Advanced Configuration
+
+The default `logback.xml` file references a collection of other log configuration files
+included in the Brooklyn jars. It is necessary to understand the source structure
+in the [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project.
+
+For example, to change the debug log inclusions, create a folder `brooklyn` under `conf`
+and create a file `logback-debug.xml` based on the
+[brooklyn/logback-debug.xml]({{ site.brooklyn.url.git }}/usage/logback-includes/src/main/resources/brooklyn/logback-debug.xml)
+from that project.
+
+
+## For More Information
+
+The following resources may be useful when configuring logging:
+
+* The [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project
+* [Brooklyn Developer Guide]({{ site.path.guide }}/dev/tips/logging.html) logging tips
+* The [Logback Project](http://logback.qos.ch/) home page

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/runtime-management/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/index.md b/docs/guide/ops/runtime-management/index.md
deleted file mode 100644
index dd825dd..0000000
--- a/docs/guide/ops/runtime-management/index.md
+++ /dev/null
@@ -1,325 +0,0 @@
----
-title: Runtime Management
-layout: website-normal
----
-
-brooklyn uses many of the ideas from autonomic computing to implement management of entities in a 
-structured and reusable fashion (including provisioning, healing, and optimising).
-
-Each external system, process or service is represented as an entity within brooklyn, with 
-collections of these being represented and managed by other entities, and so forth through 
-a hierarchy rooted in entities referred to as "Applications". Each entity has:
-
-- provisioning and tear-down logic for the external system(s) it represents
-- sensors which it publishes to report on its state and activity
-- effectors which can be invoked to change it
-- policies which perform analysis, enrichment (sensors), and execution (effectors). It is the 
-  policies in brooklyn which perform the self-management (in autonomic terms) by monitoring sensors 
-  and invoking effectors.
-
-This chapter describes these high-level runtime concepts, as well as presenting more
-detailed information on the underlying implementation of management within brooklyn.
-
-
-
-
-Management Web Console
-----------------------
-
-The web-based management console that comes with brooklyn serves as a way to observe and manage brooklyn entities.
-It provides low-level details of activity (including stack-traces), sensor values, and policies,
-and some visual widgets for observing what is happening.
-This console is not designed as a management dashboard or portal -- 
-many good options exist in that space --
-but what could be useful is to embed widgets from the brooklyn portal for selected high-level views.
-
-
-To start a management console from your own code, use ``BrooklynLaucher.launch``:
-{% highlight java %}
-public static void main(String[] argv) {
-	Application app = new MyApplicationExample(displayName:"myapp")
-    BrooklynServerDetails server = BrooklynLauncher.newLauncher()
-            .managing(app)
-            .launch();
-	// ...
-}
-{% endhighlight %}
-
-This will start an embedded brooklyn management node, including the web console.
-The URL for the web console defaults to http://127.0.0.1:8081, .
-
-The mechanism for launching brooklyn management will change in a future release. For this release, the brooklyn management node is embedded.
-
-The console contains two main views: Dashboard and Detail. These update in real-time.
-
-**Dashboard**
-
-The dashboard is a high level overview of the state of the application:
-
-[![Screenshot of the Webconsole Dashboard](webconsole-dashboard-w400.png "Screenshot of the Webconsole Dashboard")](webconsole-dashboard.png)
-
-
-**Detail**
-
-The Detail view gives an in-depth view of the application and its entities. 
-Child-parent relationships between entities are navigable using the entity tree;
-each entity is shown with its children (or, in the case of childless group entities, the members). 
-Selecting a specific entity allows you to access detailed information about that entity.
-
-[![Screenshot of the Webconsole Detail](webconsole-detail-w400.png "Screenshot of the Webconsole Detail")](webconsole-detail.png)
-
-The Detail view contains a breadcrumb trail, showing the current entitiy's position in the heirarchy, and six tabs:
-
-**Summary:** Description of the selected entity.
-
-**Sensors:** Lists the attribute sensors that the entity has and their values.
-
-**Effectors:** Lists the effectors that can be invoked on the selected entity.
-
-**Activity:** Current and historic activity of the entity, currently running effectors, finished effectors.
-
-**Location:** The geographical location of the selected entity.
-
-**Policies:** Lists the policies associated with the current entity. Policies can be suspended, resumed and removed through the UI.
-
-### Security
-
-Security providers can be configured by specifying `brooklyn.webconsole.security.provider` equal 
-to the name of a class implementing `SecurityProvider`.
-An implementation of this could point to Spring, LDAP, OpenID or another identity management system.
-
-The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords
-which should be specified as configuration parameters e.g. in `brooklyn.properties`.
-This configuration could look like:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users.
-
-To generate this, the brooklyn CLI can be used:
-{% highlight bash %}
-brooklyn generate-password --user admin
-
-Enter password: 
-Re-enter password: 
-
-Please add the following to your brooklyn.properies:
-
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-For legacy and dev purposes, the password can also be stored in plain text:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.password=mypassword
-{% endhighlight %}
-
-If not using the web console, you can specify
-`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider` to prevent inadvertant logins.
-During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
-to allow logins with no credentials. 
-
-To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the
-following command:
-
-`keytool -genkey -keyalg RSA -alias brooklyn -keystore /server.key -storepass mypassword -validity 360 -keysize 2048`
-
-You will then be prompted to enter you name and organization details. This will create 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 `` with the full path of the folder where you wish to store your
-keystore. 
-
-The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server 
-name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed 
-certificate from a trusted certifying authority should be used instead
-
-To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
-
-```
-# HTTPS
-brooklyn.webconsole.security.https.required=true
-brooklyn.webconsole.security.keystore.url=/server.key
-brooklyn.webconsole.security.keystore.password=mypassword
-brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
-```
-
-In order to access the Brooklyn console, you will also need to enable security, and setup a user as described above
-
-Other Ways to Observe Activity
-------------------------------
-
-### Java API
-
-``ManagementContext`` provides a Java programmatic API. 
-
-More information can be found in the javadoc for ``ManagementContext``.
-
-### Command-line Console
-
-*Not available yet.*
-
-### Management REST API
-
-Brooklyn's REST API supports a wide range of queries and operations. All information
-and operations shown in the web-console is performed via the REST API.
-
-The REST API can be explored through the Brooklyn web-console, via the menu Script -> REST API.
-
-### Logging
-
-Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including logback, java.util.logging and log4j.
-
-The convention for log levels is as follows:
-* ERROR and above:  exceptional situations which indicate that something has unexpectedly failed or
-some other problem has occured which the user is expected to attend to
-* WARN:  exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response
-* INFO:  a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer
-* DEBUG and lower:  detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances.
-
-Loggers follow the ``package.ClassName`` naming standard.  
-
-It is possible for entities to emit logging activity sensors so that an operator can observe what is occurring within their application through the web console or via programmatic means.
-
-Examples for testing can be found in some of the poms.
-
-
-
-
-
-
-
-Key APIs
---------
-
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-- ``ManagementContext`` (Java management API)
-- ``EntityLocal`` (used by policies)
-
-
-
-
-Sensors and Effectors
----------------------
-
-### Sensors
-
-Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example:
-{% highlight java %}
-/** a sensor for saying hi (illustrative), carrying a String value 
-	which is typically the name of the person to whom we are saying hi */
-public static final Sensor HELLO_SENSOR = ...
-
-{% endhighlight %}
-
-If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs.
-
-
-
-Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``.
-
-Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` – an attribute value being reported on change or periodically – or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT".
-
-
-
-Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON:
-		
-	{
-	  config : {
-		url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
-		status : "running"
-	  }
-	  workrate : {
-		msgsPerSec : 432
-	  }
-	}
-
-Sensor values are defined as statics, which can be used to programmatically drive the subscription.
-
-
-### SubscriptionManager
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-*See the* ``SubscriptionManager`` *class.*
-
-
-### Effectors
-
-Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows:
-
-{% highlight java %}
-/** an effector which returns no value,
-	but which causes the entity to emit a HELLO sensor event */
-public static Effector SAY_HI = ...
-
-{% endhighlight %}
-
-Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map.
-
-Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning.
-
-The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location).
-
-It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
-
-### ExecutionManager
-
-The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**.
-Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface.
-
-By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling
-``ExecutionManager.getTasksWithTag(...)``.
-
-The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended.
-	
-	ExecutionManager em = []
-	em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
-	em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
-	Thread.sleep(1500)
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
-
-It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily. 
-
-Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi`` completes.
-
-For more information consult the javadoc on these classes and associated tests.
-
-Note that it is currently necessary to prune dead tasks, either periodically or by the caller. By default they are kept around for reference. It is expected that an enhancement in a future release will allow pruning completed and failed tasks after a specified amount of time.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png b/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png
deleted file mode 100644
index 6364dc5..0000000
Binary files a/docs/guide/ops/runtime-management/webconsole-dashboard-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/runtime-management/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-dashboard.png b/docs/guide/ops/runtime-management/webconsole-dashboard.png
deleted file mode 100644
index cac5567..0000000
Binary files a/docs/guide/ops/runtime-management/webconsole-dashboard.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/runtime-management/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-detail-w400.png b/docs/guide/ops/runtime-management/webconsole-detail-w400.png
deleted file mode 100644
index b372e55..0000000
Binary files a/docs/guide/ops/runtime-management/webconsole-detail-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/ops/runtime-management/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/runtime-management/webconsole-detail.png b/docs/guide/ops/runtime-management/webconsole-detail.png
deleted file mode 100644
index 17829cd..0000000
Binary files a/docs/guide/ops/runtime-management/webconsole-detail.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/_my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/start/_my-web-cluster.yaml b/docs/guide/start/_my-web-cluster.yaml
index 3b6134b..7862c6b 100644
--- a/docs/guide/start/_my-web-cluster.yaml
+++ b/docs/guide/start/_my-web-cluster.yaml
@@ -1,8 +1,10 @@
 name: My Web Cluster
-location: location
+
+location: localhost
+
 services:
 
-- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
   name: My Web
   brooklyn.config:
     wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/{{ site.data.brooklyn.version }}/brooklyn-example-hello-world-sql-webapp-{{ site.data.brooklyn.version }}.war
@@ -12,7 +14,7 @@ services:
         component("db").attributeWhenReady("datastore.url"),
         "visitors", "brooklyn", "br00k11n")
 
-- serviceType: brooklyn.entity.database.mysql.MySqlNode
+- type: brooklyn.entity.database.mysql.MySqlNode
   id: db
   name: My DB
   brooklyn.config:

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints.md b/docs/guide/start/blueprints.md
index 9657d0d..d50cd94 100644
--- a/docs/guide/start/blueprints.md
+++ b/docs/guide/start/blueprints.md
@@ -1,57 +1,63 @@
 ---
-title: Launching Applications
-title_in_menu: Launching Applications
+title: Deploying Blueprints
 layout: website-normal
 menu_parent: index.md
+children:
+- { section: Launching from a Blueprint, title: Blueprint } 
+- { section: Launching from the Catalog, title: Catalog } 
 ---
 
 {% include fields.md %}
 
-### Launching from the Catalog
 
+## Launching from a Blueprint
 
-Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
+We'll start by deploying an application from a YAML blueprint.
 
-Now when we open the web console, two applications are displayed from the catalog.
+![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-application-modal-yaml.png)
 
-Select the 'Demo Web Cluster with DB' and click 'Next'.
+Copy the blueprint below into the large text box on the YAML tab. 
+But *before* you submit it, we need to make a modification.
 
-[![Viewing Catalog entries in Add Application dialog.](images/add-application-catalog-web-cluster-with-db.png)](add-application-catalog-web-cluster-with-db-large.png)
+{% highlight yaml %}
+{% readj _my-web-cluster.yaml %}
+{% endhighlight %}
 
-Select the Location that Brooklyn should deploy to, and name your application then click 'Finish' to launch the application as before.
+Find the line near the top of the blueprint that starts `location:`. 
+Change this to have the right values for your preferred target; for example: 
 
-## Launching from a blueprint
+{% highlight yaml %}
+location:
+  jclouds:aws-ec2:
+    identity: ABCDEFGHIJKLMNOPQRST
+    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
 
-There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
+(Alternatively, if you have `ssh localhost` [configured](../ops/locations/#localhost) you can leave it as is.
+See [Locations](../ops/locations) in the Operations section of the User Guide for detail on setting up 
+cloud providers, including putting credentials in a file on disk rather than in the blueprint.)
 
-For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
+With the modified YAML in the dialog, click "Finish". The dialog will close and Brooklyn will begin deploying your
+application. Your application will be shown as "Starting" on the web console's front page.
 
-Open the web console ([127.0.0.1:8081](http://127.0.0.1:8081)). As Brooklyn is not currently managing any applications the 'Create Application' dialog opens automatically. Select the YAML tab.
 
-![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-application-modal-yaml.png)
+### Launching from the Catalog
 
-Copy this document into the large text box on the YAML tab, labelled `Enter CAMP Plan YAML code here`. But *before* you
-submit it, we need to make a modification.
+Instead of pasting the YAML blueprint each time,
+this blueprint can be [added to the catalog](../ops/catalog/).
+Or, even easier, you can download a sample [catalog.xml](catalog.xml).
+Install this to your `~/.brooklyn/` folder and relaunch Brooklyn
+(navigating to the "Help" tab in order to shutdown Brooklyn *and* the application you launched in the previous step).
 
-{% highlight yaml %}
-{% readj _my-web-cluster.yaml %}
-{% endhighlight %}
+Now when the web console is re-opened, the catalog contains our blueprints.
+Select the "Demo Web Cluster with DB" and click "Next".
 
-Find the line near the top of the blueprint that starts `location:`. Change the line to name a location. For example,
-one of these lines:
-
-{% highlight yaml %}
-location: aws-ec2:us-east-1
-location: rackspace-cloudservers-us:ORD
-location: google-compute-engine:europe-west1-a
-location: localhost
-{% endhighlight %}
+[![Viewing Catalog entries in Add Application dialog.](images/add-application-catalog-web-cluster-with-db.png)](images/add-application-catalog-web-cluster-with-db-large.png)
 
-**My Web Cluster Blueprint**
+Select the location to use, give your application a name, and then click "Finish".
 
-With the modified YAML in the dialog, click 'Finish'. The dialog will close and Brooklyn will begin deploying your
-application. Your application will be shown as 'Starting' on the web console's front page.
 
-### Next 
+## Next 
 
-So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this a very small part of Brooklyn's capabilities!
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, 
+but this just the beginning.  **[Start managing this application.](managing.html)**

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/config.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/config.md b/docs/guide/start/config.md
deleted file mode 100644
index 10895d6..0000000
--- a/docs/guide/start/config.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Configuring Brooklyn
-title_in_menu: Configuring Brooklyn
-layout: website-normal
-menu_parent: index.md
----
-
-{% include fields.md %}
-
-Brooklyn reads startup configuration from a file `~/.brooklyn/brooklyn.properties`, by default.
-You can create this from a template [brooklyn.properties]({{brooklyn_properties_url_path}}) file which you edit.
-
-## Configuring Security
-
-To configure Brooklyn to run on a public IP address, security should be enabled.
-The simplest way is to define a user and password in `~/.brooklyn/brooklyn.properties`
-(described above): 
-
-    brooklyn.webconsole.security.users=admin
-    brooklyn.webconsole.security.user.admin.password=s3cr3t
-
-Other modes, including LDAP, are described in this file.
-
-The other common setting is to run under https (on port 8443 by default):
-
-    brooklyn.webconsole.security.https.required=true
-
-## Configuring a Location
-
-Brooklyn deploys applications to locations. These locations
-can be clouds, machines with fixed IPs or localhost (for testing).
-Their configuration can be specified in `~/.brooklyn/brooklyn.properties` (described above),
-and then these locations can be easily selected within Brooklyn.
-Alternatively this information can be specified in the YAML when applications are deployed,
-without needing to set it in `brooklyn.properties`.
-
-Some sample settings for this are:
-
-    brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-    brooklyn.location.jclouds.aws-ec2.credential = 
-    brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
-    brooklyn.location.named.aws-california.displayName = AWS US West 1 (CA)
-
-    brooklyn.location.jclouds.softlayer.identity = username
-    brooklyn.location.jclouds.softlayer.credential = 
-    brooklyn.location.named.softlayer-dal05 = jclouds:softlayer:dal05
-    brooklyn.location.named.softlayer-dal05.displayName = Softlayer Dallas
-
-If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/ops/locations/) 
-to ensure that your Brooklyn can access your machine.
-
-Once updated, restart Brooklyn (or reload the properties within the web GUI).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.md b/docs/guide/start/index.md
index 3bc9f92..41ab28b 100644
--- a/docs/guide/start/index.md
+++ b/docs/guide/start/index.md
@@ -4,7 +4,6 @@ title: Getting Started
 menu_parent: ../index.md
 children:
 - running.md
-- config.md
 - blueprints.md
 - managing.md
 - policies.md

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/managing.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/managing.md b/docs/guide/start/managing.md
index b36bcaf..e01edbf 100644
--- a/docs/guide/start/managing.md
+++ b/docs/guide/start/managing.md
@@ -17,24 +17,40 @@ We can explore the management hierarchy of the application, which will show us t
 
 
 
-Clicking on the 'My Web' entity will show the Summary tab. Here we can see if the cluster is ready to serve and, when ready, grab the web address for the front of the loadbalancer.
+Clicking on the "My Web" entity will show the "Summary" tab,
+giving a very high level of what that component is doing. 
 
 ![Exploring My Web.](images/my-web.png)
 
 
-The Activity tab allows us to drill down into what activities each entity is currently doing or has recently done. It is possible to drill down to all child tasks, and view the commands issued, and any errors or warnings that occured.
+## Sensors
 
-Drill into the 'My DB' start operation. Working down through  'Start (processes)', then 'launch', we can discover the ssh command used including the stdin, stdout and stderr.
+Now click on the "Sensors" tab:
+these data feeds drive the real-time picture of the application.
+As you navigate in the tree at the left, you can see more targeted statistics coming in in real-time.
+
+Explore the sensors and the tree to find a URL where the webapp we just deployed is running
+and open that in a new tab. Quickly return to the "Sensors" tab and observe the requests-per-second sensor increase.  
+
+
+## Activities
+
+The Activity tab allows us to drill down into the activities each entity is currently doing or has recently done. 
+It is possible to drill down to all child tasks, and view the commands issued, and any errors or warnings that occured.
+
+Drill into the "My DB" start operation. 
+Working down through  "Start (processes)", then "launch", we can discover the ssh command used including the stdin, stdout and stderr.
 
 [![My DB Activities.](images/my-db-activities.png)](images/my-db-activities-large.png)
 
 
 ## Stopping the Application
 
-To stop an application, select the application in the tree view (the top/root entity), click on the Effectors tab, and invoke the 'Stop' effector. This will cleanly shutdown all components in the application and return any cloud machines that were being used.
+To stop an application, select the application in the tree view (the top/root entity), click on the Effectors tab, and invoke the "Stop" effector. This will cleanly shutdown all components in the application and return any cloud machines that were being used.
 
 [![My DB Activities.](images/my-web-cluster-stop-confirm.png)](images/my-web-cluster-stop-confirm-large.png)
 
+
 ### Next
 
-Brooklyn's real power is in using [Policies](policies.html)  to automatically *manage* applications. 
+Brooklyn's real power is in using **[Policies](policies.html)**  to automatically *manage* applications. 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/start/running.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/running.md b/docs/guide/start/running.md
index 17e3d934..965272d 100644
--- a/docs/guide/start/running.md
+++ b/docs/guide/start/running.md
@@ -31,65 +31,19 @@ $ tar -zxf brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz
 
 This will create a `brooklyn-{{ site.data.brooklyn.version }}` folder.
 
-Note: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers.
-
-## Verify SSH
-
-Brooklyn uses SSH extensively and therefore it is worth making sure that you have a known working SSH setup before
-starting.
-
-Please check the following items:
-
-- If you are using Mac OSX, open System Preferences, go to the Sharing item, and enable 'Remote Login'.
-- You have two files named `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`.
-  - If these files do not exist, they can be created with `ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa`.
-- `~/.ssh/id_rsa` is NOT readable by any other user.
-  - You can verify this with `ls -l ~/.ssh/id_rsa` - the line should start with `-rw-------` or `-r--------`. If it
-    does not, execute `chmod 0600 ~/.ssh/id_rsa`.
-- The file `~/.ssh/authorized_keys` exists and contains a copy of your public key from `~/.ssh/id_rsa.pub`.
-  - Note that it is normal for it to contain other items as well.
-- The key in `~/.ssh/id_rsa` does *not* have a passphrase.
-  - You can test this by executing `ssh-keygen -y`. If it does *not* ask for a passphrase, then your key is OK.
-  - If your key does have a passphrase, remove it. You can do this by running `ssh-keygen -p`. Enter the passphrase,
-    then when prompted for the new passphrase, hit Enter.
-
-Now verify your setup by running the command: `ssh localhost echo hello world`
-
-If you see a message similar to this:
-
-
-The authenticity of host 'localhost (::1)' can't be established.
-RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
-Are you sure you want to continue connecting (yes/no)?
-

-
-then answer 'yes', and then repeat the command run again.
-
-If the response is `hello world`, with no other output or prompts, then your SSH setup is good and Brooklyn should be
-able to use it without a problem.
-
-If these steps are not working, [these instructions]({{ site.path.guide }}/ops/locations/) may be
-useful.
-
+**Note**: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers.
 
+**Node #2**: If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/ops/locations/#localhost) 
+to ensure that your Brooklyn can access your machine.
 
 
 ## Launch Brooklyn
 
-Let's setup some paths for easy commands.
-
-(Click the clipboard on these code snippets for easier c&p.)
-
-{% highlight bash %}
-$ cd brooklyn-{{ site.data.brooklyn.version }}
-$ BROOKLYN_DIR="$(pwd)"
-$ export PATH=$PATH:$BROOKLYN_DIR/bin/
-{% endhighlight %}
-
-We can do a quick test drive by launching Brooklyn:
+Now start Brooklyn with the following command:
 
 {% highlight bash %}
-$ brooklyn launch
+$ cd brooklyn-{{ site.brooklyn.version }}
+$ bin/brooklyn launch
 {% endhighlight %}
 
 Brooklyn will output the address of the management interface:
@@ -99,6 +53,16 @@ INFO  Starting brooklyn web-console on loopback interface because no security co
 INFO  Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []
+ ### Next -Now that Brooklyn is up and running we can look at getting it to manage some applications. +Next, open the web console on [127.0.0.1:8081](http://127.0.0.1:8081). +No application shave been deployed yet, so the "Create Application" dialog opens automatically: +let's remedy this by **[deploying a blueprint](blueprints.html)**. + +It is not necessary at this time, but depending on what you are going to do, +you may wish to set up other configuration options first: + +* [Security](../ops/brooklyn_properties.html) +* [Persistence](../ops/persistence/) +* [Cloud credentials](../ops/locations/) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/3add5d21/docs/guide/yaml/chef/advanced-chef-integration.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/chef/advanced-chef-integration.md b/docs/guide/yaml/chef/advanced-chef-integration.md index 18a4ff9..0d65286 100644 --- a/docs/guide/yaml/chef/advanced-chef-integration.md +++ b/docs/guide/yaml/chef/advanced-chef-integration.md @@ -30,7 +30,7 @@ indicated earlier. If you'd like to work with us to implement these, please let A general schema for the supported YAML is below: -``` +{% highlight yaml %} - type: chef:cookbook_name cookbook_urls: cookbook_name: url://for/cookbook.tgz @@ -39,7 +39,7 @@ A general schema for the supported YAML is below: launch_attributes: # map of arguments to set in the chef node service_name: cookbook_service pid_file: /var/run/cookbook.pid -``` +{% endhighlight %} If you are interested in exploring the Java code for creating blueprints, start with the `TypedToyMySqlEntiyChef` class, which essentially does what this tutorial has shown;