brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [24/44] incubator-brooklyn git commit: moving around docs more
Date Fri, 09 Jan 2015 15:34:53 GMT
moving around docs more

removed duplication of quickstart, yaml things under yaml, java under java, and a start at getting landing pages right


Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4afc8590
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4afc8590
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4afc8590

Branch: refs/heads/master
Commit: 4afc8590fecfbae15087e663673842e3bb26f92b
Parents: 1d6ce7c
Author: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Authored: Wed Jan 7 14:18:55 2015 +0000
Committer: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Committed: Wed Jan 7 14:20:43 2015 +0000

----------------------------------------------------------------------
 .../_extra/big_examples/before-begin.include.md |  56 +++
 .../console-geoscaling-details-w700.png         | Bin 0 -> 167441 bytes
 .../console-geoscaling-details.png              | Bin 0 -> 176651 bytes
 .../global-web-fabric/console-map-w700.png      | Bin 0 -> 201060 bytes
 .../global-web-fabric/console-map.png           | Bin 0 -> 331520 bytes
 .../geopaas-deployed-app-w700.png               | Bin 0 -> 153738 bytes
 .../global-web-fabric/geopaas-deployed-app.png  | Bin 0 -> 114615 bytes
 .../big_examples/global-web-fabric/index.md     | 378 +++++++++++++++++++
 docs/_extra/big_examples/index.md               |  18 +
 docs/_extra/big_examples/messaging/index.md     | 181 +++++++++
 .../nosql-cassandra/cassandra.include.md        | 282 ++++++++++++++
 .../big_examples/nosql-cassandra/index.md       |   7 +
 docs/_extra/big_examples/simple-web-cluster.md  |   9 +
 docs/_extra/big_examples/toc.json               |  13 +
 docs/_extra/big_examples/webcluster.md          |   9 +
 docs/_extra/big_examples/webcluster/index.md    |   7 +
 .../webcluster/webcluster.include.md            | 124 ++++++
 docs/_extra/debugging-remote-brooklyn.md        | 140 -------
 docs/_extra/dev/code-structure.md               |  97 -----
 docs/_extra/dev/maven-build.md                  | 184 ---------
 docs/_extra/dev/tests.md                        |  26 --
 docs/_extra/examples/before-begin.include.md    |  56 ---
 .../console-geoscaling-details-w700.png         | Bin 167441 -> 0 bytes
 .../console-geoscaling-details.png              | Bin 176651 -> 0 bytes
 .../global-web-fabric/console-map-w700.png      | Bin 201060 -> 0 bytes
 .../examples/global-web-fabric/console-map.png  | Bin 331520 -> 0 bytes
 .../geopaas-deployed-app-w700.png               | Bin 153738 -> 0 bytes
 .../global-web-fabric/geopaas-deployed-app.png  | Bin 114615 -> 0 bytes
 docs/_extra/examples/global-web-fabric/index.md | 378 -------------------
 docs/_extra/examples/index.md                   |  18 -
 docs/_extra/examples/messaging/index.md         | 181 ---------
 .../nosql-cassandra/cassandra.include.md        | 282 --------------
 docs/_extra/examples/nosql-cassandra/index.md   |   7 -
 docs/_extra/examples/simple-web-cluster.md      |   9 -
 docs/_extra/examples/toc.json                   |  13 -
 docs/_extra/examples/webcluster.md              |   9 -
 docs/_extra/examples/webcluster/index.md        |   7 -
 .../examples/webcluster/webcluster.include.md   | 124 ------
 docs/_extra/ide/eclipse.include.md              |  15 -
 docs/_extra/ide/ide.md                          | 123 ------
 docs/_extra/local-artifact-repo.md              |  32 ++
 docs/_extra/release.md                          | 288 ++++++++++++++
 .../example_files/tomcat_multi-location.java    |  15 +
 .../example_files/tomcat_nginx.java             |  17 +
 .../example_files/tomcat_simple.java            |   9 +
 docs/_extra/simple_java_examples/examples.md    | 121 ++++++
 docs/_extra/standards.md                        |  15 +
 docs/_extra/tips/index.md                       |  50 ---
 docs/_extra/tips/local-artifact-repo.md         |  32 --
 docs/_extra/tips/logging.md                     | 144 -------
 docs/_extra/tips/release.md                     | 288 --------------
 docs/_extra/tips/standards.md                   |  15 -
 docs/_extra/tips/toc.json                       |  14 -
 docs/_extra/tips/update-docs.md                 |  14 -
 docs/_extra/update-docs.md                      |  14 +
 docs/_plugins/site_structure.rb                 |   3 +-
 docs/guide/dev/code/index.md                    |  94 ++++-
 docs/guide/dev/code/tests.md                    |  26 ++
 docs/guide/dev/env/ide/eclipse.include.md       |  15 +
 docs/guide/dev/env/ide/index.md                 | 123 ++++++
 docs/guide/dev/env/index.md                     |   3 +
 docs/guide/dev/env/maven-build.md               | 184 +++++++++
 docs/guide/dev/index.md                         |   4 +
 .../guide/dev/tips/debugging-remote-brooklyn.md | 140 +++++++
 docs/guide/dev/tips/index.md                    |  49 +++
 docs/guide/dev/tips/logging.md                  | 143 +++++++
 docs/guide/java/common-usage.md                 |  42 +++
 docs/guide/java/index.md                        |   6 +-
 .../java/walkthrough/_java_walkthrough_p1.md    | 235 ++++++++++++
 docs/guide/java/walkthrough/index.md            |   6 +
 .../walkthrough/wt-deployed-application-700.png | Bin 0 -> 176494 bytes
 .../walkthrough/wt-deployed-application.png     | Bin 0 -> 127347 bytes
 docs/guide/java/walkthrough/wt-starting-700.png | Bin 0 -> 303892 bytes
 docs/guide/java/walkthrough/wt-starting.png     | Bin 0 -> 332710 bytes
 .../walkthrough/wt-tree-jboss-sensors-700.png   | Bin 0 -> 268853 bytes
 .../java/walkthrough/wt-tree-jboss-sensors.png  | Bin 0 -> 169929 bytes
 docs/guide/ops/index.md                         |   3 +-
 docs/guide/ops/locations/configuring.md         | 105 ++++++
 docs/guide/ops/locations/index.md               |   2 +-
 docs/guide/start/_my-web-cluster.yaml           |  19 +
 docs/guide/start/blueprints.md                  | 219 +++++++++++
 docs/guide/start/brooklyn.properties            | 324 ++++++++++++++++
 docs/guide/start/catalog.md                     |  48 +++
 docs/guide/start/catalog.xml                    |  22 ++
 ...cation-catalog-web-cluster-with-db-large.png | Bin 0 -> 131618 bytes
 ...talog-web-cluster-with-db-location-large.png | Bin 0 -> 152721 bytes
 ...ion-catalog-web-cluster-with-db-location.png | Bin 0 -> 86425 bytes
 ...-application-catalog-web-cluster-with-db.png | Bin 0 -> 76065 bytes
 .../start/images/add-application-modal-yaml.png | Bin 0 -> 68401 bytes
 .../images/jboss7-cluster-policies-large.png    | Bin 0 -> 157883 bytes
 .../start/images/jboss7-cluster-policies.png    | Bin 0 -> 94056 bytes
 .../start/images/my-db-activities-large.png     | Bin 0 -> 208313 bytes
 docs/guide/start/images/my-db-activities.png    | Bin 0 -> 130262 bytes
 .../start/images/my-web-cluster-starting.png    | Bin 0 -> 32948 bytes
 .../my-web-cluster-stop-confirm-large.png       | Bin 0 -> 148155 bytes
 .../images/my-web-cluster-stop-confirm.png      | Bin 0 -> 79280 bytes
 .../guide/start/images/my-web-summary-large.png | Bin 0 -> 178785 bytes
 docs/guide/start/images/my-web-summary.png      | Bin 0 -> 80583 bytes
 docs/guide/start/images/my-web.png              | Bin 0 -> 83081 bytes
 docs/guide/start/index.md                       |   6 +-
 docs/guide/start/policies.md                    |  37 ++
 docs/guide/start/quickstart/brooklyn.properties | 324 ----------------
 docs/guide/start/quickstart/catalog.xml         |  23 --
 ...cation-catalog-web-cluster-with-db-large.png | Bin 131618 -> 0 bytes
 ...talog-web-cluster-with-db-location-large.png | Bin 152721 -> 0 bytes
 ...ion-catalog-web-cluster-with-db-location.png | Bin 86425 -> 0 bytes
 ...-application-catalog-web-cluster-with-db.png | Bin 76065 -> 0 bytes
 .../images/add-application-modal-yaml.png       | Bin 68401 -> 0 bytes
 .../images/jboss7-cluster-policies-large.png    | Bin 157883 -> 0 bytes
 .../images/jboss7-cluster-policies.png          | Bin 94056 -> 0 bytes
 .../images/my-db-activities-large.png           | Bin 208313 -> 0 bytes
 .../quickstart/images/my-db-activities.png      | Bin 130262 -> 0 bytes
 .../images/my-web-cluster-starting.png          | Bin 32948 -> 0 bytes
 .../my-web-cluster-stop-confirm-large.png       | Bin 148155 -> 0 bytes
 .../images/my-web-cluster-stop-confirm.png      | Bin 79280 -> 0 bytes
 .../quickstart/images/my-web-summary-large.png  | Bin 178785 -> 0 bytes
 .../start/quickstart/images/my-web-summary.png  | Bin 80583 -> 0 bytes
 docs/guide/start/quickstart/images/my-web.png   | Bin 83081 -> 0 bytes
 docs/guide/start/quickstart/index.md            | 221 -----------
 docs/guide/start/quickstart/my-web-cluster.yaml |  19 -
 .../start/quickstart/policies-and-catalogs.md   |  66 ----
 docs/guide/start/quickstart/toc.json            |   4 -
 docs/guide/start/walkthrough/index.md           | 239 ------------
 .../walkthrough/wt-deployed-application-700.png | Bin 176494 -> 0 bytes
 .../walkthrough/wt-deployed-application.png     | Bin 127347 -> 0 bytes
 .../guide/start/walkthrough/wt-starting-700.png | Bin 303892 -> 0 bytes
 docs/guide/start/walkthrough/wt-starting.png    | Bin 332710 -> 0 bytes
 .../walkthrough/wt-tree-jboss-sensors-700.png   | Bin 268853 -> 0 bytes
 .../start/walkthrough/wt-tree-jboss-sensors.png | Bin 169929 -> 0 bytes
 .../yaml/defining-applications/common-usage.md  | 145 -------
 .../example_files/tomcat_multi-location.java    |  15 -
 .../example_files/tomcat_nginx.java             |  17 -
 .../example_files/tomcat_simple.java            |   9 -
 .../yaml/defining-applications/examples.md      | 121 ------
 docs/guide/yaml/index.md                        |   2 -
 docs/website/index.md                           |   2 +-
 docs/website/quickstart/_my-web-cluster.yaml    |  19 -
 docs/website/quickstart/catalog.xml             |  22 --
 ...cation-catalog-web-cluster-with-db-large.png | Bin 131618 -> 0 bytes
 ...talog-web-cluster-with-db-location-large.png | Bin 152721 -> 0 bytes
 ...ion-catalog-web-cluster-with-db-location.png | Bin 86425 -> 0 bytes
 ...-application-catalog-web-cluster-with-db.png | Bin 76065 -> 0 bytes
 .../images/add-application-modal-yaml.png       | Bin 68401 -> 0 bytes
 .../images/jboss7-cluster-policies-large.png    | Bin 157883 -> 0 bytes
 .../images/jboss7-cluster-policies.png          | Bin 94056 -> 0 bytes
 .../images/my-db-activities-large.png           | Bin 208313 -> 0 bytes
 .../quickstart/images/my-db-activities.png      | Bin 130262 -> 0 bytes
 .../images/my-web-cluster-starting.png          | Bin 32948 -> 0 bytes
 .../my-web-cluster-stop-confirm-large.png       | Bin 148155 -> 0 bytes
 .../images/my-web-cluster-stop-confirm.png      | Bin 79280 -> 0 bytes
 .../quickstart/images/my-web-summary-large.png  | Bin 178785 -> 0 bytes
 .../quickstart/images/my-web-summary.png        | Bin 80583 -> 0 bytes
 docs/website/quickstart/images/my-web.png       | Bin 83081 -> 0 bytes
 docs/website/quickstart/index.md                | 218 -----------
 .../website/quickstart/policies-and-catalogs.md |  67 ----
 155 files changed, 3443 insertions(+), 3769 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/before-begin.include.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/before-begin.include.md b/docs/_extra/big_examples/before-begin.include.md
new file mode 100644
index 0000000..e05f9f1
--- /dev/null
+++ b/docs/_extra/big_examples/before-begin.include.md
@@ -0,0 +1,56 @@
+{% include fields.md %}
+
+## Before You Begin
+
+To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven`` (v3) installed.
+
+### Installing Brooklyn
+
+(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.)
+
+{% if SNAPSHOT %}
+
+First, grab a copy of the Brooklyn snapshot distribution you wish to use from 
+[the Sonatype snapshot repo]({{ sonatype_repo_groupid_url }}brooklyn-dist/)
+(or build it yourself following instructions [here]({{ site.path.guide }}/dev/build/)),
+unpack it to your favourite location (e.g. `$(pwd)`), 
+and export `BROOKLYN_HOME`:
+
+{% highlight bash %}
+% curl -L -o brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz "{{ this_dist_url_tgz }}"
+% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
+% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
+{% endhighlight %}
+
+{% else %}
+
+Grab a copy of the Brooklyn distribution and set up `BROOKLYN_HOME`:
+
+{% highlight bash %}
+% curl -LO "{{ this_dist_url_tgz }}"
+% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
+% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
+{% endhighlight %}
+
+{% endif %}
+
+### Installing the Examples 
+
+Grab a copy of the brooklyn-examples source code and build it with Maven:
+
+{% highlight bash %}
+% git clone https://github.com/apache/incubator-brooklyn.git
+% cd incubator-brooklyn/examples
+% mvn clean install
+{% endhighlight %}
+
+{% if SNAPSHOT %}
+Please note, these instructions are for a SNAPSHOT release of Brooklyn,
+so proceed with caution. 
+For the latest stable version, go [here](/meta/versions.html). 
+{% endif %}
+
+For more information on ways to download Brooklyn please
+see the [download page]({{site.path.guide}}/start/download.html).
+For more information on the Brooklyn CLI and launching apps,
+please visit [this section of the user guide]({{site.path.guide}}/use/guide/management/index.html#cli).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png b/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png
new file mode 100644
index 0000000..c34217f
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details.png b/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details.png
new file mode 100644
index 0000000..f47226a
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/console-geoscaling-details.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/console-map-w700.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/console-map-w700.png b/docs/_extra/big_examples/global-web-fabric/console-map-w700.png
new file mode 100644
index 0000000..af353a9
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/console-map-w700.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/console-map.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/console-map.png b/docs/_extra/big_examples/global-web-fabric/console-map.png
new file mode 100644
index 0000000..cd0f811
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/console-map.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png b/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png
new file mode 100644
index 0000000..33c811d
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png b/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png
new file mode 100644
index 0000000..4e743e3
Binary files /dev/null and b/docs/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/global-web-fabric/index.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/global-web-fabric/index.md b/docs/_extra/big_examples/global-web-fabric/index.md
new file mode 100644
index 0000000..b59eae0
--- /dev/null
+++ b/docs/_extra/big_examples/global-web-fabric/index.md
@@ -0,0 +1,378 @@
+---
+layout: guide-normal
+title: Global Web Fabric
+toc: /guide/toc.json
+---
+
+This example shows how to build a multi-site web application *fabric*
+with DNS configured on the front-end to combine the sites,
+routing users to the location closest to them.
+
+It can combine with the [Simple Web Cluster](../webcluster) example
+or the [Portable Cloud Foundry](https://github.com/cloudsoft/brooklyn-cloudfoundry) example,
+but does not assume knowledge of either of these.
+
+{% readj ../before-begin.include.md %}
+
+Now, go to this particular example's directory:
+
+{% highlight bash %}
+% cd global-web-fabric
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``global-web-fabric`` contains the code used
+in this example under ``src/main/java``.
+
+
+### Setting Up Geographic DNS
+
+This example uses [geoscaling.com](http://www.geoscaling.com) to provide **free** geographic-dependent DNS services.
+This will forward a domain name of your choice to various IPs depending on a script,
+e.g. computing the nearest IP based on latitude and longitude of the requester and the targets.
+Brooklyn will automatically generate and update this script, but you do need to 
+create and configure a Geoscaling account:
+
+ 1. Create the free account [here](https://www.geoscaling.com/dns2/?module=register).
+ 1. Click the link in the email you receive.
+ 1. Enter the domain name you wish to use into geoscaling (see below).
+
+The simplest domain name to choose is something unique under `geopaas.org`, e.g. `yourname.geopaas.org`,
+which we have already configured for Geoscaling to manage.
+If you are using your own domain name, 
+set its nameservers as advised by geoscaling (e.g. `ns{1,2,3,4}.geoscaling.com`).
+
+Next we need to supply this information to Brooklyn at runtime.
+The simplest way is to create or add the following fields to `~/.brooklyn/brooklyn.properties`:
+
+{% highlight bash %}
+brooklyn.geoscaling.username=yourname
+brooklyn.geoscaling.password=s3cr3t
+brooklyn.geoscaling.primaryDomain=yourname.geopaas.org
+{% endhighlight %}
+
+Replace the values of these fields as appropriate, of course!
+You can, if you prefer, supply (or override) these values in your Brooklyn application.
+
+
+### Setting Up the Locations Database
+
+In order to generate the "closest-IP" script,
+Brooklyn needs a way to find out the latitude and longitude of the
+servers you are using.
+The simplest way to do this is do download the free GeoCityLite binary flatfile 
+from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/#Downloads),
+unpack it, and copy it to `~/.brooklyn/GeoLite2-City.mmdb`.
+
+This will be picked up automatically if it is installed.
+You can instead specify to use an online lookup service, such as 
+[utrace.de](http://www.utrace.de) by specifying
+`-Dbrooklyn.location.geo.HostGeoLookup=brooklyn.location.geo.UtraceHostGeoLookup`;
+but note this has a cap of 100 per day.
+
+This information is also used to display locations on the map
+in the Brooklyn dashboard.
+Note however that these free services are not 100% accurate;
+they are handy for dev/test but in a production system
+you may wish to specify the geographical information manually in your application,
+or purchase a commercial locations-database subscription.
+
+
+## The Code
+
+Now let's start writing our application.
+The heavy lifting will be done by off-the-shelf Brooklyn classes:
+
+ * `DynamicFabric` will create the entity specified by `factory` in each location it is given
+ * `GeoscalingDnsService` monitors children of a specified entity (the `DynamicFabric`) 
+   and adds them as DNS targets for the region they are in  
+
+First, however, let's create the Java class -- call it `GlobalWebFabricExample`.
+This will extend the Brooklyn `AbstractApplication`:
+
+{% highlight java %}
+package brooklyn.demo;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import brooklyn.entity.basic.AbstractApplication;
+
+public class GlobalWebFabricExample extends AbstractApplication {
+    @Override
+    public void init() {
+         // TODO create our app!
+    }
+}
+{% endhighlight %}
+
+### The Fabric
+
+The `DynamicFabric` by default has no knowledge of what it will build,
+other than the `factory` it is given to create an entity in each region.
+We'll use the class `ElasticJavaWebAppService.Factory` which creates
+an elastic Java Web App service,
+such as the `ControlledDynamicWebAppCluster` used in the
+[Simple Web Cluster](../webcluster) example, if deploying to VMs,
+or perhaps a `CloudFoundryJavaWebAppCluster` if deploying to a Cloud Foundry location
+(see [brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry)).
+
+{% highlight java %}
+        DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+                .displayName("Web Fabric")
+                .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+                .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH));
+{% endhighlight %}
+
+Here we have specified the WAR to use with `configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)`.
+The war configuration used in the previous example is only available on web-aware entities;
+configuration specified with a ConfigKey can be done on any entity,
+and is inherited at runtime, so this provides a useful way to specify the WAR to use
+even though the web-aware entities are only constructed at runtime.
+
+
+### Stitching the Fabric together with DNS
+
+To stitch these together seamlessly, another entity will run a policy
+which collects the public-facing IP address of each cluster created by the fabric,
+as it comes online, by watching for `SERVICE_UP` sensors.
+First, however, let's make sure any load-balancer proxies (e.g. nginx) in these clusters
+are listening on port 80:
+
+{% highlight java %}
+        DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+                .displayName("Web Fabric")
+                .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+                .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)
+                .configure(AbstractController.PROXY_HTTP_PORT, PortRanges.fromInteger(80)));
+{% endhighlight %}
+
+Let's now define the Geoscaling entity which does the stitching.
+We need to supply the username, password, and primaryDomainName for Geoscaling;
+we'll take this from the `brooklyn.properties` file mentioned above.
+We'll also specify a `smartSubdomainName`, to use Geoscaling's facility for
+lightweight sub-domains to prevent DNS caching and multiple instances of our application
+from confusing us -- e.g. `brooklyn-1234.yourname.geopaas.org`.
+
+{% highlight java %}
+        StringConfigMap config = getManagementContext().getConfig();
+        
+        GeoscalingDnsService geoDns = addChild(EntitySpec.create(GeoscalingDnsService.class)
+                .displayName("GeoScaling DNS")
+                .configure("username", checkNotNull(config.getFirst("brooklyn.geoscaling.username"), "username"))
+                .configure("password", checkNotNull(config.getFirst("brooklyn.geoscaling.password"), "password"))
+                .configure("primaryDomainName", checkNotNull(config.getFirst("brooklyn.geoscaling.primaryDomain"), "primaryDomain")) 
+                .configure("smartSubdomainName", "brooklyn"));
+{% endhighlight %}
+
+Lastly we need to tell this instance what entity it should monitor
+for children to include as targets:
+
+{% highlight java %}
+        geoDns.setTargetEntityProvider(webFabric);
+{% endhighlight %}
+
+
+
+### Cloud Foundry and other PaaS Targets
+
+At this point our core application is ready, and can be deployed to AWS or another VM cloud.
+This may take between 15 and 30 minutes to run,
+mainly spent downloading software
+(unless of course you specify a pre-configured `imageId` which contains the software).
+
+A quicker alternative is to deploy to a Java Web App platform-as-a-service
+such as Cloud Foundry.  A major advantage here is that they can provision very quickly,
+in a matter of seconds.  Code for this can be found in the 
+[brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry), 
+along with an example global-web-fabric app.
+
+
+### Imports
+
+Your imports should look as follows:
+
+{% highlight java %}
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import brooklyn.config.StringConfigMap;
+import brooklyn.entity.basic.AbstractApplication;
+import brooklyn.entity.basic.Attributes;
+import brooklyn.entity.dns.geoscaling.GeoscalingDnsService;
+import brooklyn.entity.group.DynamicFabric;
+import brooklyn.entity.proxy.AbstractController;
+import brooklyn.entity.proxying.EntitySpec;
+import brooklyn.entity.webapp.ElasticJavaWebAppService;
+import brooklyn.location.basic.PortRanges;
+{% endhighlight %}
+
+
+### Use of main method (optional)
+
+In this example, we will use the brooklyn CLI launcher. However, it is possible to write your own main method.
+
+The following static constants are assumed (most of these as in the [Simple Web Cluster](../webcluster) example and others): 
+
+ * `WAR_PATH`, pointing to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+ * `DEFAULT_LOCATIONS`, containing a string spec of the locations to deploy to if none are supplied on the command-line;
+   for this example `localhost` will frequently not work unless Geoscaling can see it 
+   (i.e. it has a public IP and appropriate firewall settings)
+
+The code (which can safely be omitted) is as follows:
+
+{% highlight java %}
+import brooklyn.launcher.BrooklynLauncher;
+import brooklyn.util.CommandLineUtil;
+
+import com.google.common.base.Joiner;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+
+// class definition, and rest of class goes here...
+
+    public static final Logger log = LoggerFactory.getLogger(GlobalWebFabricExample.class);
+    
+    // points to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+    public static final String WAR_PATH = "classpath://hello-world-webapp.war";
+    
+    // locations to deploy to if none are supplied on the command-line; for this example `localhost` will 
+    // frequently not work unless Geoscaling can see it (i.e. it has a public IP and appropriate firewall settings)
+    static final List<String> DEFAULT_LOCATIONS = ImmutableList.of(
+            "aws-ec2:eu-west-1",
+            "aws-ec2:ap-southeast-1",
+            "aws-ec2:us-west-1" );
+        
+    public static void main(String[] argv) {
+        List<String> args = Lists.newArrayList(argv);
+        String port =  CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
+        String locations = CommandLineUtil.getCommandLineOption(args, "--locations", Joiner.on(",").join(DEFAULT_LOCATIONS));
+
+        BrooklynLauncher launcher = BrooklynLauncher.newInstance()
+                .application(EntitySpec.create(StartableApplication.class, GlobalWebFabricExample.class).displayName("Brooklyn Global Web Fabric Example"))
+                .webconsolePort(port)
+                .locations(Arrays.asList(locations))
+                .start();
+        
+        Entities.dumpInfo(app);
+    }
+{% endhighlight %}
+
+
+
+## Running the Example
+
+Now let's run this example.
+
+{% highlight bash %}
+${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.GlobalWebFabricExample \
+--location jclouds:aws-ec2:eu-west-1,jclouds:aws-ec2:ap-southeast-1,jclouds:aws-ec2:us-west-1 
+{% endhighlight %}
+
+The management web console will start,
+followed by the web-app services in the locations specified
+creating the VM's as needed.
+Let's look at the management web console, on port 8081:
+
+[![Web Console Map](console-map-w700.png "Web Console Map")](console-map.png) 
+
+This shows the targets (e.g. Ireland (AWS eu-west-1),  Singapore (AWS ap-southeast-1),  and California (AWS us-west-1)).
+This also shows the current status of the application.
+
+Navigating to the "applications" tab, we can view sensors, invoke effectors, control policies,
+and track activity, 
+for instance if a cluster is slow to start and you want to find out what is going on
+(you'll find additional information in the `brooklyn.log` file).
+Let's drill down on the Geoscaling DNS entity's sensors:
+
+[![Web Console Geoscaling Details](console-geoscaling-details-w700.png "Web Console Geoscaling Details")](console-geoscaling-details.png)
+
+Here we see it has chosen `brooklyn-vOZ7b4BL.martincloudsoft.geopaas.org` as the geo-load-balanced domain name.
+(Yours will be under `yourname.geopaas.org`, unless you chose a different domain earlier.)
+We can also see the hosts it is forwarding to, one for each cluster, corresponding to the
+children of the Web Fabric (propagated from the nginx hostnames, in the case of the ControlledDynamicWebAppCluster instances).
+
+
+### Checking the Web App
+
+Once Geoscaling reports at least one target, you should be able to access it on the geo-load-balanced domain name:
+
+[![Our Deployed Application](geopaas-deployed-app-w700.png "Our Deployed Application")](geopaas-deployed-app.png)
+
+Under the covers you are being routed to one of the clusters that has been deployed --
+whichever one is closest to you.
+(Due to DNS caching, at your machine or your ISP, clusters which come online after your first lookup
+will not be picked up until TTL expires, typically 10m, although often more if DNS services don't respect TTL.)
+
+
+### Checking DNS Information
+
+Let's find out exactly where we were routed:
+
+{% highlight bash %}
+% dig brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> brooklyn-csgFCzTm.geopaas.org
+
+;; QUESTION SECTION:
+;brooklyn-csgFCzTm.geopaas.org. IN      A
+
+;; ANSWER SECTION:
+brooklyn-csgFCzTm.geopaas.org. 120 IN   CNAME   ec2-46-137-138-4.eu-west-1.compute.amazonaws.com.
+ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. 215 IN A 46.137.138.4
+{% endhighlight %}
+
+This was run from Scotland so it seems a sensible choice.
+(Some portions of the output from `dig` have been removed for readability.)
+
+We can get more information by looking at the TXT records: 
+
+{% highlight bash %}
+% dig +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+...
+
+geopaas.org.            86400   IN      NS      ns1.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns2.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns3.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns4.geoscaling.com.
+;; Received 133 bytes from 199.249.112.1#53(a2.org.afilias-nst.info) in 45 ms
+
+brooklyn-csgFCzTm.geopaas.org. 300 IN   TXT     "Request from [54,-2]-(GB) directed to Ireland (IE)"
+brooklyn-csgFCzTm.geopaas.org. 300 IN   TXT     "GeoScaling config auto-updated by Brooklyn 2012-04-26 12:27:25 UTC"
+;; Received 189 bytes from 80.87.128.195#53(ns3.geoscaling.com) in 60 ms
+{% endhighlight %}
+
+
+## Next Steps
+
+This example has shown how to create a multi-region fabric, using the abstractions from
+[jclouds](http://jclouds.org) under the covers to make it easy to access different hosting providers
+simultaneously, and using higher-level abstractions in Brooklyn to mix PaaS systems with
+bare-VM (or even bare-metal, if you specify fixed IPs).
+
+This is meant as just the beginning however.  
+Here are some questions to think about and code challenges to give you a steer for what to explore next.
+
+
+ 1. The routines used at Geoscaling optimize for latency between the user and the location of the web-cluster.
+    What other strategies might be used?  Cost?  Compliance?  How would you code these?
+    
+ 2. This example ignores data, but you clearly can't do that in the real world.
+    When big-data is involved, does this introduce other considerations for optimizing geo-location?
+    
+ 3. Add a data tier to this system, such as MySQL or Mongo, or even Hadoop.
+    You might start with a single instance or cluster,
+    but the real fun starts with a fabric, and defining the synchronization/replication strategies
+    between the different clusters.
+    This isn't for the faint-hearted, but whatever you create will certainly be of interest
+    to people in the Brooklyn community.
+    Please [let us know]({{ site.path.guide }}/meta/contact.html) what you've built!

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/index.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/index.md b/docs/_extra/big_examples/index.md
new file mode 100644
index 0000000..f55643f
--- /dev/null
+++ b/docs/_extra/big_examples/index.md
@@ -0,0 +1,18 @@
+---
+layout: guide-normal
+title: Examples
+toc: /guide/toc.json
+---
+
+We currently have the following examples on the site:
+
+{% capture ltocs %}{% readj toc.json %}{% endcapture %}
+{% jsonball ltoc from var ltocs %}
+
+{% for x in ltoc %}
+* <a href="{{ x.file }}">{{ x.title }}</a>
+{% endfor %} 
+
+There are examples in the code also, just check out the examples/ project.
+
+**Have one of your own?**  [Add it here!]({{site.path.guide}}/dev/tips/update-docs.html)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/messaging/index.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/messaging/index.md b/docs/_extra/big_examples/messaging/index.md
new file mode 100644
index 0000000..c3c2254
--- /dev/null
+++ b/docs/_extra/big_examples/messaging/index.md
@@ -0,0 +1,181 @@
+---
+layout: guide-normal
+title: Publish-Subscribe Messagiung
+toc: /guide/toc.json
+---
+
+This example shows how a simple messaging application can be build
+in brooklyn, starting with configuring and launching a broker. For
+these examples we will use the Apache [Qpid](http://qpid.apache.org/)
+Java AMQP message broker and clients using the
+[JMS](http://docs.oracle.com/javaee/6/tutorial/doc/bnceh.html) API.
+
+{% readj ../before-begin.include.md %}
+
+Now, go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-messaging-pubsub
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-messaging-pubsub`` includes a deployment
+descriptor for our example messaging application and simple _Publish_
+and _Subscribe_ JMS test client scripts.
+
+## Single Broker
+
+The first example will include a Qpid broker, which we will customize
+to use the Oracle [BDB](http://www.oracle.com/technetwork/products/berkeleydb/overview/index.html)
+message store as an example of a typical production setup. We will
+also create a queue for use by a pair of test clients.
+
+The ``QpidBroker`` entity is created like this, which uses the
+default configuration, specifying only the AMQP port and creates
+no queues or topics:
+
+{% highlight java %}
+public class StandaloneQpidBrokerExample extends AbstractApplication {
+    @Override
+    public void init() {
+        // Configure the Qpid broker entity
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672));
+    }
+}
+{% endhighlight %}
+
+To install the custom configuration files and extra libraries for
+BDB, we specify some files to copy to the broker installation, using
+the ``runtimeFiles`` property. These files should be available in
+the classpath of the application when it is running, usually by
+copying them to the ``src/main/resources`` directory. For example,
+here we copy a custom XML configuration file and a new password
+file:
+
+{% highlight java %}
+        final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml";
+        final String PASSWD_PATH = "classpath://passwd";
+
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672)
+    	        .configure("amqpVersion", AmqpServer.AMQP_0_10)
+    	        .configure("runtimeFiles", ImmutableMap.builder()
+    	                .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH)
+    	                .put(QpidBroker.PASSWD, PASSWD_PATH)
+    	                .build()));
+{% endhighlight %}
+
+Finally, we come to the complete configuration of our ``QpidBroker``
+entity using the BDB store. The additional properties here specify
+the AMQP version and that a queue named _testQueue_ should be created
+on startup.
+
+{% highlight java %}
+        final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml";
+        final String PASSWD_PATH = "classpath://passwd";
+        final String QPID_BDBSTORE_JAR_PATH = "classpath://qpid-bdbstore-0.14.jar";
+        final String BDBSTORE_JAR_PATH = "classpath://je-5.0.34.jar";
+
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672)
+    	        .configure("amqpVersion", AmqpServer.AMQP_0_10)
+    	        .configure("runtimeFiles", ImmutableMap.builder()
+    	                .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH)
+    	                .put(QpidBroker.PASSWD, PASSWD_PATH)
+    	                .put("lib/opt/qpid-bdbstore-0.14.jar", QPID_BDBSTORE_JAR_PATH)
+    	                .put("lib/opt/je-5.0.34.jar", BDBSTORE_JAR_PATH)
+    	                .build())
+    	        .configure("queue", "testQueue"));
+{% endhighlight %}
+
+
+### Running the Example
+
+You can run the example as follows:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn -v launch --app brooklyn.demo.StandaloneQpidBrokerExample --location localhost
+{% endhighlight %}
+
+Now, visit the Brooklyn web console on port 8081 (for pre 0.6 releases,
+use the credentials admin/password). This allows you to view the Brooklyn 
+entities and their current state for debugging.
+
+Note that the installation may take some time, because the default
+deployment downloads the software from the official repos.  You can
+monitor start-up activity for each entity in the ``Activity`` pane
+in the management console, and see more detail by tailing the log
+file (``tail -f brooklyn.log``).
+
+After starting up, the demo script should display a summary of all
+the Brooklyn managed entities and their attributes. This will show
+both the Qpid broker and its child entity, the queue _testQueue_
+which was created at startup. The queue entity has sensors that
+monitor the depth of unread messages, which you can check while
+running the test client scripts later.
+
+If the ``-v`` flag is passed to the startup command, all configured
+entity and sensor details will be output. This includes the broker URL,
+which is used to configure JMS clients to connect to this broker.
+This URL can also be viewed as a sensor attribute in the web console,
+named _broker.url_.
+
+This sensor is common to _all_ messaging brokers that Brooklyn
+provides, and is usually accessed by applications to allow them to
+provide it as a parameter to other entities, as shown in the code
+fragment below.
+
+{% highlight java %}
+String url = broker.getAttribute(MessageBroker.BROKER_URL)
+{% endhighlight %}
+
+Using the URL the demo script printed, you can run the test ``Subscribe``
+and then ``Publish`` classes, to send messages using the broker. Simply
+run the commands in another window, with the provided URL as the
+only argument. Note that the URLs may be different to those printed
+below, and that any unquoted ``&`` characters *must* be escaped,
+if present.
+
+{% highlight bash %}
+% URL="amqp://guest:guest@/localhost?brokerlist='tcp://localhost:5672'"
+% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Subscribe ${URL}
+% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Publish ${URL}
+{% endhighlight %}
+
+In the _Publish_ window you should see a log message every time a
+message is sent, like this:
+
+{% highlight bash %}
+2012-05-02 14:04:38,521 INFO  Sent message 65
+2012-05-02 14:04:39,522 INFO  Sent message 66
+{% endhighlight %}
+
+Similarly, the _Subscribe_ windows should log on reciept of these
+messages, as follows:
+
+{% highlight bash %}
+2012-05-02 14:04:32,522 INFO  got message 41 test message 41
+2012-05-02 14:04:33,523 INFO  got message 42 test message 42
+{% endhighlight %}
+
+### Cloud Deployment
+
+With appropriate setup (as described
+[here]({{ site.path.guide }}/use/guide/management/index.html#startup-config))
+this can also be deployed to your favourite cloud, let's pretend
+it's Amazon Ireland, as follows:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.StandaloneQpidBrokerExample --location aws-ec2:eu-west-1
+{% endhighlight %}
+
+If you encounter any difficulties, please
+[tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best
+to help.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/nosql-cassandra/cassandra.include.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/nosql-cassandra/cassandra.include.md b/docs/_extra/big_examples/nosql-cassandra/cassandra.include.md
new file mode 100644
index 0000000..56319f8
--- /dev/null
+++ b/docs/_extra/big_examples/nosql-cassandra/cassandra.include.md
@@ -0,0 +1,282 @@
+      
+{% readj ../before-begin.include.md %}
+
+## Simple Cassandra Cluster
+
+Go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-nosql-cluster
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-nosql-cluster`` includes several deployment descriptors
+for deploying and managing Cassandra, under ``src/main/java``.
+
+The simplest of these, ``SimpleCassandraCluster``, will start a Cassandra cluster. The code is:
+
+{% highlight java %}
+public class SimpleCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraCluster.class)
+        .configure(CassandraCluster.INITIAL_SIZE, 1)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn"));
+  }
+}
+{% endhighlight %}
+
+To run that example on localhost (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase):
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \
+  --location localhost
+{% endhighlight %}
+
+Then visit the Brooklyn console on ``localhost:8081``.
+Note that the installation may take some time, because the default deployment downloads the software from
+the official repos.  You can monitor start-up activity for each entity in the ``Activity`` pane in the management console,
+and see more detail by tailing the log file (``tail -f brooklyn.log``).
+
+This example runs successfully on a local machine because ``INITIAL_SIZE`` is configured to just one node
+(a limitation of Cassandra is that every node must be on a different machine/VM).
+If you want to run with more than one node in the cluster, you'll need to use a location 
+that either points to multiple existing machines or to a cloud provider where you can 
+provision new machines.
+
+With appropriate setup of credentials (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) 
+this example can also be deployed to your favourite cloud. Let's pretend it's Amazon US East, as follows: 
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \
+  --location aws-ec2:us-east-1
+{% endhighlight %}
+
+If you want more nodes in your cluster, you can either modify the deployment descriptor (i.e. change the ``INITIAL_SIZE`` value),
+or dynamically add more nodes by calling the ``resize`` effector through the web-console. 
+To do the latter, select cluster entity in the tree on the left, then click on the "effectors" tab, and invoke ``resize`` 
+with the desired number of nodes.
+
+
+### Testing your Cluster
+
+An easy way to test your cluster is to use the ``cassandra-stress`` command line tool.
+For example, run:
+
+{% highlight bash %}
+# Substitute the id below for your VM
+NODE_IDS=ec2-54-221-69-95.compute-1.amazonaws.com
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+	--nodes ${NODE_IDS} \
+    --replication-factor 1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation INSERT
+{% endhighlight %}
+
+This command will fire 10000 inserts at the cluster, via the nodes specified in the comma-separated node list. 
+If you change ``INSERT`` to ``READ``, it will read each of those 10000 values.
+
+
+## High Availability Cassandra Cluster
+
+Ready for something more interesting?  Try this:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.HighAvailabilityCassandraCluster \
+  --location aws-ec2:us-east-1
+{% endhighlight %}
+
+This launches the class ``HighAvailabilityCassandraCluster``,
+which launches a Cassandra cluster configured to replicate across availability zones.
+
+To give some background for that statement, in 
+[AWS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
+(and various other clouds), a region is a 
+separate geographic area, consisting of multiple isolated locations known as availability zones.
+To ensure high availability, the Cassandra cluster and thus the data should be spread across the 
+availability zones. Cassandra should be configured to ensure there is at least one replica in
+each availability zone. In 
+[Cassandra terminology](http://www.datastax.com/docs/1.1/cluster_architecture/replication)
+a region is normally mapped to a "datacenter" and an availability zone to a "rack".
+
+To be properly highly available, we need some automated policies to restart failed servers 
+and to replace unhealthy nodes. Brooklyn has these policies available out-of-the-box.
+To wire them up, the essential code fragment looks like this:
+
+{% highlight java %}
+public class HighAvailabilityCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraCluster.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 1)
+        .configure(CassandraCluster.ENABLE_AVAILABILITY_ZONES, true)
+        .configure(CassandraCluster.NUM_AVAILABILITY_ZONES, 3)
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "GossipingPropertyFileSnitch")
+        .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class)
+            .policy(PolicySpec.create(ServiceFailureDetector.class))
+            .policy(PolicySpec.create(ServiceRestarter.class)
+                .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED)))
+        .policy(PolicySpec.create(ServiceReplacer.class)
+            .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED)));
+  }
+}
+{% endhighlight %}
+
+This code is doing a lot and deserves some more detailed explanation:
+
+* The ``MEMBER_SPEC`` describes the configuration of the Cassandra nodes to be created in the cluster.
+  Assuming you're happy to use all the default thrift port etc, then the only configuration to add is
+  a couple of policies.
+* The ``ServiceFailureDetector`` policy watches the node's sensors, and generates
+  an ``ENTITY_FAILED`` event if the node goes down.
+* The ``ServiceRestarter`` policy responds to this failure-event
+  by restarting the node. Its default configuration is that: if a node does not come back up, or if it 
+  fails again within three minutes, then it will emit an ``ENTITY_RESTART_FAILED`` event.
+* Finally, the ``SERVICE_REPLACER`` policy on the cluster responds to this event by replacing the
+  entire VM. It sets up a new VM in the same location, and then tears down the faulty node.
+
+> *Troubleshooting:*
+
+> *In AWS, some availability zones can be constrained for particular instance sizes (see
+  [this bug report](https://github.com/brooklyncentral/brooklyn/issues/973)
+  If you get this error, the workaround is to specify explicitly the availability zones to use. 
+  This requires an additional line of code such as:*
+
+{% highlight java %}
+  .configure(AVAILABILITY_ZONE_NAMES, ImmutableList.of("us-east-1b", "us-east-1c", "us-east-1e"))
+{% endhighlight %}
+
+> *However, this prevents the blueprint from being truly portable. We're looking at fixing this issue.*
+
+
+## Wide Area Cassandra Cluster
+
+For critical enterprise use-cases, you'll want to run your Cassandra cluster across multiple regions, 
+or better yet across multiple cloud providers. This gives the highest level of availability for 
+the service.
+
+Try running:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \
+  --location "aws-ec2:us-east-1,aws-ec2:us-west-2"
+{% endhighlight %}
+
+This launches the class ``WideAreaCassandraCluster`` across two AWS regions.
+
+Cassandra provides some great support for this with the 
+[EC2MultiRegionSnitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication)
+The 
+[snitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication#snitches)
+maps IPs to racks and data centers; it defines how the nodes are grouped together within the overall 
+network topology. For wide-area deployments, it must also deal with when to use the private IPs 
+(within a region) and the public IPs (between regions).
+You'll need a more generic snitch if you're going to span different cloud providers.
+Brooklyn has a custom MultiCloudSnitch that we're looking to contribute back to Cassandra.
+
+The important piece of code in ``WideAreaCassandraCluster`` is:
+
+{% highlight java %}
+public class WideAreaCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraFabric.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 2) // per location
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch")
+        .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar"));
+  }
+}
+{% endhighlight %}
+
+The code below shows the wide-area example with the high-availability policies from the previous section also configured:
+
+{% highlight java %}
+public class WideAreaCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraFabric.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 2) // per location
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch")
+        .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar")
+        .configure(CassandraFabric.MEMBER_SPEC, EntitySpec.create(CassandraCluster.class)
+            .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class)
+                .policy(PolicySpec.create(ServiceFailureDetector.class))
+                .policy(PolicySpec.create(ServiceRestarter.class)
+                    .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED)))
+            .policy(PolicySpec.create(ServiceReplacer.class)
+                 .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED))));
+  }
+}
+{% endhighlight %}
+
+To run Cassandra across multiple clouds, try running:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \
+  --location "aws-ec2:us-east-1,google-compute-engine,rackspace-cloudservers-uk"
+{% endhighlight %}
+
+
+### Testing your Wide-Area Cluster
+
+You can again use the ``cassandra-stress`` command line tool to test the wide-area cluster.
+
+Note that the replication strategy (such as 
+[NetworkTopologyStrategy](http://www.datastax.com/docs/1.0/cluster_architecture/replication#networktopologystrategy)
+is specified when creating a 
+[keyspace](http://www.datastax.com/documentation/cassandra/1.2/webhelp/index.html#cassandra/configuration/configStorage_r.html).
+The example below specifies a minimum of 1 replica in each datacenter.
+
+To do updates against a node in a given availability zone:
+
+{% highlight bash %}
+NODE_IDS=<your node hostname>
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+    --nodes ${NODE_IDS} \
+    --replication-strategy NetworkTopologyStrategy \
+    --strategy-properties=us-east-1:1,us-west-2:1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation INSERT
+{% endhighlight %}
+
+To check that the same data is available from a different region, target the reads
+against an appropriate node:
+
+{% highlight bash %}
+NODE_IDS=<your node hostname>
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+    --nodes ${NODE_IDS} \
+    --replication-strategy NetworkTopologyStrategy \
+    --strategy-properties=us-east-1:1,us-west-2:1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation READ
+{% endhighlight %}
+
+To really test this, you may want to simulate the failure of a region first.
+You can kill the VMs or ``kill -9`` the processes. But remember that if Brooklyn policies are configured
+they will by default restart the processes automatically! You can disable the Brooklyn policies through 
+the brooklyn web-console (select the entity, go the policies tab, select the policy, and click "disable").
+
+
+## Putting it all together: CumulusRDF
+
+If you want to try this with a real example application using the Cassandra cluster, take a look at
+[CumulusRDF](https://code.google.com/p/cumulusrdf). There is an example Brooklyn application at:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.CumulusRDFApplication \
+  --location "aws-ec2:us-east-1"
+{% endhighlight %}
+
+
+## Contact us!
+
+If you encounter any difficulties or have any comments, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/nosql-cassandra/index.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/nosql-cassandra/index.md b/docs/_extra/big_examples/nosql-cassandra/index.md
new file mode 100644
index 0000000..88c1dce
--- /dev/null
+++ b/docs/_extra/big_examples/nosql-cassandra/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Cassandra Clusters
+toc: /guide/toc.json
+---
+
+{% readj cassandra.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/simple-web-cluster.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/simple-web-cluster.md b/docs/_extra/big_examples/simple-web-cluster.md
new file mode 100644
index 0000000..cd2b659
--- /dev/null
+++ b/docs/_extra/big_examples/simple-web-cluster.md
@@ -0,0 +1,9 @@
+---
+layout: guide-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+<!-- file kept to preserve old links; remove when link not used -->
+
+{% readj webcluster/webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/toc.json
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/toc.json b/docs/_extra/big_examples/toc.json
new file mode 100644
index 0000000..4bca3a1
--- /dev/null
+++ b/docs/_extra/big_examples/toc.json
@@ -0,0 +1,13 @@
+[
+{ "title": "Elastic Web Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/webcluster/index.html" },
+{ "title": "Global Web Fabric",
+  "file":  "{{ site.path.guide }}/use/examples/global-web-fabric/index.html" },
+{ "title": "Whirr Hadoop Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/whirrhadoop/index.html" },
+{ "title": "Publish-Subscribe Messaging",
+  "file":  "{{ site.path.guide }}/use/examples/messaging/index.html" },
+{ "title": "Cassandra Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/nosql-cassandra/index.html" }
+
+]

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/webcluster.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/webcluster.md b/docs/_extra/big_examples/webcluster.md
new file mode 100644
index 0000000..cd2b659
--- /dev/null
+++ b/docs/_extra/big_examples/webcluster.md
@@ -0,0 +1,9 @@
+---
+layout: guide-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+<!-- file kept to preserve old links; remove when link not used -->
+
+{% readj webcluster/webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/webcluster/index.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/webcluster/index.md b/docs/_extra/big_examples/webcluster/index.md
new file mode 100644
index 0000000..1fd80dd
--- /dev/null
+++ b/docs/_extra/big_examples/webcluster/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+{% readj webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/big_examples/webcluster/webcluster.include.md
----------------------------------------------------------------------
diff --git a/docs/_extra/big_examples/webcluster/webcluster.include.md b/docs/_extra/big_examples/webcluster/webcluster.include.md
new file mode 100644
index 0000000..e135998
--- /dev/null
+++ b/docs/_extra/big_examples/webcluster/webcluster.include.md
@@ -0,0 +1,124 @@
+      
+{% readj ../before-begin.include.md %}
+
+## Simple Web Server
+
+Go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-web-cluster
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-web-cluster`` includes several deployment descriptors
+for rolling out a web application, under ``src/main/java``.
+
+
+
+The simplest of these, ``SingleWebServerExample``, starts JBoss on a single machine with a "Hello World" war deployed,
+with a single line:
+
+{% highlight java %}
+public class SingleWebServerExample extends AbstractApplication {
+    private static final String WAR_PATH = "classpath://hello-world-webapp.war";
+
+    @Override
+    public void init() {
+        addChild(EntitySpec.create(JBoss7Server.class)
+                .configure("war", WAR_PATH)
+                .configure("httpPort", 8080));
+    }
+}
+{% endhighlight %}
+
+You can run this as follows (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase):
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \
+  --location localhost
+{% endhighlight %}
+
+
+Then visit the webapp on port 8080, or the Brooklyn console on localhost:8081.
+Note that the installation may take some time, because the default deployment downloads the software from
+the official repos.  You can monitor start-up activity for each entity in the ``Activity`` pane in the management console,
+and see more detail by tailing the log file (``tail -f brooklyn.log``).
+
+With appropriate setup (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) 
+this can also be deployed to your favourite cloud, let's pretend it's Amazon Ireland, as follows: 
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \
+  --location aws-ec2:eu-west-1
+{% endhighlight %}
+
+
+## Elastic Three-Tier
+
+Ready for something more interesting?  Try this:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WebClusterDatabaseExample \
+  --location localhost
+{% endhighlight %}
+
+This launches the class ``WebClusterDatabaseExample`` (also described in the [walkthrough]({{ site.path.guide }}/start/walkthrough/index.html))
+which launches a pool of web-servers -- of size 1 initially,
+but manually configurable (if you stop the policy first, in the GUI, then use the ``resize`` effector) --
+with an Nginx load-balancer set up in front of them, and backed by a MySQL database.
+
+The essential code fragment looks like this:
+
+{% highlight java %}
+public class WebClusterDatabaseExample extends AbstractApplication {
+    public static final String WAR_PATH = "classpath://hello-world-sql-webapp.war";
+    
+    public static final String DB_SETUP_SQL_URL = "classpath://visitors-creation-script.sql";
+    
+    public static final String DB_TABLE = "visitors";
+    public static final String DB_USERNAME = "brooklyn";
+    public static final String DB_PASSWORD = "br00k11n";
+
+    @Override
+    public void init() {
+        MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
+                .configure("creationScriptUrl", DB_SETUP_SQL_URL));
+        
+        ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+                .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
+                        .configure("httpPort", "8080+")
+                        .configure("war", WAR_PATH)
+                        .configure(javaSysProp("brooklyn.example.db.url"), 
+                                formatString("jdbc:%s%s?user=%s\\&password=%s", 
+                                        attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
+        
+        web.getCluster().addPolicy(AutoScalerPolicy.builder().
+                        metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
+                        sizeRange(1, 5).
+                        metricRange(10, 100).
+                        build());
+    }
+}
+{% endhighlight %}
+
+You can, of course, try this with your favourite cloud, 
+tweak the database start script, or drop in your favourite WAR.
+
+
+## A Few Other Things
+
+The project includes variants of the examples shown here, 
+including alternative syntax (the `*Alt*` files), 
+and a web-only cluster (no database) in `WebClusterExample``.
+
+The webapp that is used is included under ``examples/hello-world-webapp``.
+
+You may wish to check out the [Global Web Fabric example]({{ site.path.guide }}/use/examples/global-web-fabric/) next.
+
+If you encounter any difficulties, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/debugging-remote-brooklyn.md
----------------------------------------------------------------------
diff --git a/docs/_extra/debugging-remote-brooklyn.md b/docs/_extra/debugging-remote-brooklyn.md
deleted file mode 100644
index 337aa21..0000000
--- a/docs/_extra/debugging-remote-brooklyn.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-layout: guide-normal
-title: Brooklyn Remote Debugging
-toc: /guide/toc.json
----
-
-Usually during development, you will be running Brooklyn from your IDE (see [IDE Setup](ide.html)), in which case
-debugging is as simple as setting a breakpoint. There may however be times when you need to debug an existing remote
-Brooklyn instance (often referred to as Resident Brooklyn, or rBrooklyn) on another machine, usually in the cloud.
-
-Thankfully, the tools are available to do this, and setting it up is quite straightforward. The steps are as follows:
-
-* [Getting the right source code version](#sourceCodeVersion)
-* [Starting Brooklyn with a debug listener](#startingBrooklyn)
-* [Creating an SSH tunnel](#sshTunnel)
-* [Connecting your IDE](#connectingIDE)
-
-## <a name="sourceCodeVersion"></a>Getting the right source code version
-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://<remote-address>:<remote-port>/v1/server/version
-```
-
-This should return details of the build as a JSON string similar to the following (formatted for clarity):
-
-```JSON
-{
-    "version": "0.7.0-SNAPSHOT",
-    "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224",
-    "buildBranch": "UNKNOWN"
-}
-```
-
-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
-```
-
-Whilst building the code isn't strictly necessary, it can help prevent some IDE issues.
-
-## <a name="startingBrooklyn"></a>Starting Brooklyn with a debug listener
-By default, Brooklyn does not listen for a debugger to be attached, however this behaviour can be set by setting JAVA_OPTS,
-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:
-
-```
-# 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 &
-```
-
-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
-```
-
-This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached.
-
-## <a name="sshTunnel"></a>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
-usually simpler to create an SSH tunnel. This will create an open SSH connection that will redirect traffic from a port
-on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local
-machine:
-
-```
-# replace this with the address or IP of the remote Brooklyn node
-REMOTE_HOST=<remote-address>
-# if you wish to use a different port, this value must match the port specified in the JAVA_OPTS
-REMOTE_PORT=8888 
-# if you wish to use a different local port, this value must match the port specified in the IDE configuration
-LOCAL_PORT=8888 
-# set this to the login user you use to SSH to the remote Brooklyn node
-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
-
-```
-
-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
-```
-
-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.
-
-The SSH tunnel should now be redirecting traffic from port 8888 on the local 127.0.0.1 network interface via the SSH 
-tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible to connect the debugger and start
-debugging.
-
-## <a name="connectingIDE"></a> 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](ide.html)).
-
-Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the 
-Debug Configuration dialog.
-
-Select `Remote Java Application` from the list and click the 'New' button to create a new configuration. Set the name
-to something suitable such as 'Remote debug on 8888'. The Project can be set to any of the Brooklyn projects, the 
-Connection Type should be set to 'Standard (Socket Attach)'. The Host should be set to either localhost or 127.0.0.1
-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](ide.html)).
-
-Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the
-Run/Debug Configurations dialog.
-
-Click on the `+` button and select 'Remote' to create a new remote configuration. Set the name to something suitable
-such as 'Remote debug on 8888'. The first three sections simply give the command line arguments for starting the java
-process using different versions of java, however we have already done this in 
-[Starting Brooklyn with a debug listener](#startingBrooklyn). The Transport option should be set to 'Socket', the Debugger Mode should be set to 'Attach', the
-Host should be set to localhost or 127.0.0.1 (or the address of the remote machine if you are not using an SSH tunnel),
-and the Port should be set to 8888. The 'Search sources' section should be set to `<whole project>`. Click OK to save the
-configuration, then select the configuration from the configurations drop-down and click the debug button to start
-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/4afc8590/docs/_extra/dev/code-structure.md
----------------------------------------------------------------------
diff --git a/docs/_extra/dev/code-structure.md b/docs/_extra/dev/code-structure.md
deleted file mode 100644
index 41ebe07..0000000
--- a/docs/_extra/dev/code-structure.md
+++ /dev/null
@@ -1,97 +0,0 @@
-## The Basics
-
-Brooklyn is available at [GitHub apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn).  Check it out using:
-
-{% highlight bash %}
-git clone git@github.com:apache/incubator-brooklyn.git
-cd brooklyn
-{% endhighlight %}
-
-Build it with:
-
-{% highlight bash %}
-mvn clean install
-{% endhighlight %}
-
-And launch it with:
-
-{% highlight bash %}
-cd usage/dist/target/brooklyn-dist/
-bin/brooklyn launch
-{% endhighlight %}
-
-Plenty of examples are in the **examples** sub-dir,
-described [here]({{site.path.guide}}/use/examples).
-
-Information on using Brooklyn -- configuring locations (in `brooklyn.properties`) 
-and adding new projects to a catalog -- can be found in the [User's Guide]({{site.path.guide}}/use/guide/quickstart/index.html).
-This document is intended to help people become familiar with the codebase.
-
-## Project Structure
-
-Brooklyn is split into the following projects and sub-projects:
-
-* **``camp``**: the components for a server which speaks the CAMP REST API and which understands the CAMP YAML plan language
-* **``api``**: the pure-Java interfaces for interacting with the system
-* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more 
-* **``locations``**: specific location integrations
-    * **``jclouds``**: integration with many cloud APIs and providers, via Apache jclouds
-* **``policies``**: collection of useful policies for automating entity activity  
-* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof
-    * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH) 
-    * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling) 
-    * **``database``**: relational databases (SQL) 
-    * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments) 
-    * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ 
-    * **``monitoring``**: monitoring tools, including Monit
-    * **``osgi``**: OSGi servers 
-    * **...**
-* **``utils``**: projects which lower level utilities
-    * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
-    * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
-    * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP
-    * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open
-    * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
-    * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
-* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers
-    * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience
-    * **archetypes**: A maven archetype, for easily generating the structure of a new downstream projects 
-    * **camp**: Brooklyn bindings for the CAMP REST API
-    * **cli**: backing implementation for Brooklyn's command line interface
-    * **dist**: builds brooklyn as a downloadable .zip and .tar.gz
-    * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR)
-    * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project
-    * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml 
-    * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes
-    * **rest-api**: The API classes for the Brooklyn REST api
-    * **rest-client**: A client Java implementation for using the Brooklyn REST API 
-    * **rest-server**: The server-side implementation of the Brooklyn REST API
-    * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts)
-    * **qa**: longevity and stress tests
-    * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test``
-* **``docs``**: the markdown source code for this documentation, as described [here]({{site.path.guide}}/dev/tips/update-docs.html)
-* **``examples``**: some canonical examples, as listed [here]({{site.path.guide}}/use/examples)
-* **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating
-
- 
-## Next Steps
-
-If you're interested in building and editing the code, check out:
-
-* [Maven setup](../build/index.html)
-* [IDE setup](../build/ide.html)
-* [Tests](../build/tests.html)
-* [Tips](../tips/index.html)
-* [Remote Debugging](../build/debugging-remote-brooklyn.html)
-
-If you want to start writing your own policies and entities, have a look at:
-
-* [Writing a Brooklyn Entity](entity.html)
-* [Writing a Brooklyn Policy](policy.html)
-* Or see the [User Guide]({{ site.path.guide }}/use/guide/index.html) 
-  on [policies]({{ site.path.guide }}/use/guide/policies/index.html)
-  and [entities]({{ site.path.guide }}/use/guide/entities/index.html)
-
-Where things aren't documented **please ask us** at 
-[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
-so we can remedy this!

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4afc8590/docs/_extra/dev/maven-build.md
----------------------------------------------------------------------
diff --git a/docs/_extra/dev/maven-build.md b/docs/_extra/dev/maven-build.md
deleted file mode 100644
index 90aa6fa..0000000
--- a/docs/_extra/dev/maven-build.md
+++ /dev/null
@@ -1,184 +0,0 @@
----
-layout: guide-normal
-title: Maven Build
-toc: /guide/toc.json
----
-
-## The Basics
-
-To build the code, you need Maven (v3) installed and Java (1.6).
-With that in place, you should be able to build everything with a:
-
-{% highlight bash %}
-brooklyn% mvn clean install
-{% endhighlight %}
-
-Key things to note if you're new to Maven:
-
-* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
-
-  ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m``
-
-* You can do this in specific projects as well.
-
-* Add ``-DskipTests`` to skip tests. 
-
-* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
-  ([tests described here](tests.html))
-
-* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms.
-
-* You can also open and use the code in your favourite IDE,
-  although you may hit a few **[snags](ide.html)**
-  (that link has some tips for resolving them too)
-
-
-## When the RAT Bites
-
-We use RAT to ensure that all files are compliant to Apache standards.  Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as:
-
-    [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1]
-
-If there's a problem, see the file `rat.txt` in the `target` directory of the failed project.  (Maven will show you this link in its output.)
-
-Often the problem is one of the following:
-
-* You've added a file which requires the license header but doesn't have it
-
-  **Resolution:**  Simply copy the header from another file
-
-* You've got some temporary files which RAT things should have headers
-
-  **Resolution:**  Move the files away, add headers, or turn off RAT (see below)
-
-* The project structure has changed and you have stale files (e.g. in a `target` directory)
-
-  **Resolution:**  Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`)
-
-To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`.  (But note you will need RAT to pass in order for a PR to be accepted!)
-
-If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`.
-
-
-## Other Handy Hints
-
-* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories.
-  Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3).
-
-* The **mvnf** script 
-  ([get the gist here](https://gist.github.com/2241800)) 
-  simplifies building selected projects, so if you just change something in ``software-webapp`` 
-  and then want to re-run the examples you can do:
-  
-  ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}`` 
-
-* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line.
-  
-  ``wget {{site.url_root}}{{site.path.guide}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml`` 
-
-## Appendix: Sample Output
-
-A healthy build will look something like the following,
-including a few warnings (which we have looked into and
-understand to be benign and hard to get rid of them,
-although we'd love to if anyone can help!):
-
-{% highlight bash %}
-brooklyn% mvn clean install
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Reactor Build Order:
-[INFO] 
-[INFO] Brooklyn Parent Project
-[INFO] Brooklyn Utilities to Support Testing (listeners etc)
-[INFO] Brooklyn Logback Includable Configuration
-[INFO] Brooklyn Common Utilities
-[INFO] Brooklyn Groovy Utilities
-[INFO] Brooklyn API
-
-...
-
-[WARNING] Ignoring project type war - supportedProjectTypes = [jar]
-
-...
-
-[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar
-
-...
-
-[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist —
-[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml
-[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
-[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist
-[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
-
-...
-
-[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist —
-[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml
-[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
-[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz
-[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
-
-...
-
-[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png
-
-...
-
-[INFO] Reactor Summary:
-[INFO] 
-[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s]
-[INFO] Brooklyn Utilities to Support Testing (listeners etc)  SUCCESS [3.114s]
-[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s]
-[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s]
-[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s]
-[INFO] Brooklyn API ...................................... SUCCESS [2.146s]
-[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s]
-[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s]
-[INFO] CAMP Base ......................................... SUCCESS [4.079s]
-[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s]
-[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s]
-[INFO] CAMP Server ....................................... SUCCESS [5.446s]
-[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s]
-[INFO] Brooklyn Policies ................................. SUCCESS [44.425s]
-[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s]
-[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s]
-[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s]
-[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s]
-[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s]
-[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s]
-[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s]
-[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s]
-[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s]
-[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s]
-[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s]
-[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s]
-[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s]
-[INFO] Brooklyn REST API ................................. SUCCESS [4.489s]
-[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s]
-[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s]
-[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s]
-[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s]
-[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s]
-[INFO] Brooklyn All Things ............................... SUCCESS [13.875s]
-[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s]
-[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s]
-[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s]
-[INFO] Brooklyn Examples Support Aggregator Project - Webapps  SUCCESS [0.053s]
-[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s]
-[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s]
-[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s]
-[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s]
-[INFO] Brooklyn Simple Messaging Publish-Subscribe Example  SUCCESS [3.217s]
-[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s]
-[INFO] Brooklyn QA ....................................... SUCCESS [7.117s]
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 8:33.983s
-[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014
-[INFO] Final Memory: 66M/554M
-[INFO] ------------------------------------------------------------------------
-
-{% endhighlight %}


Mime
View raw message