You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2015/01/09 17:09:29 UTC
[01/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Repository: incubator-brooklyn
Updated Branches:
refs/heads/0.7.0-M2-incubating-docs f31c828c5 -> d975336a0
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/index.md
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/index.md b/docs/website/quickstart/index.md
deleted file mode 100644
index 8be0bbd..0000000
--- a/docs/website/quickstart/index.md
+++ /dev/null
@@ -1,217 +0,0 @@
----
-title: Getting Started
-layout: website-normal
-children:
-- { path: policies-and-catalogs.md }
----
-
-{% include fields.md %}
-
-This guide will walk you through deploying an application to a public cloud.
-
-We will be deploying an example 3-tier web application, described using this blueprint:
-
-{% highlight yaml %}
-{% readj _my-web-cluster.yaml %}
-{% endhighlight %}
-
-(This is written in YAML, following the [camp specification](https://www.oasis-open.org/committees/camp/). )
-
-This tutorial assumes that you are using Linux or Mac OSX.
-
-
-## 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 a files named `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`
-- `~/.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:
-
-<pre>
-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)?
-</pre>
-
-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 }}/use/guide/locations/) may be
-useful.
-
-
-## Install Brooklyn
-
-Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download.html).
-
-{% if brooklyn_version contains 'SNAPSHOT' %}
-Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
-{% else %}
-Expand the `tar.gz` archive:
-{% endif %}
-
-{% if brooklyn_version contains 'SNAPSHOT' %}
-{% highlight bash %}
-$ tar -zxf brooklyn-dist-{{ site.data.brooklyn.version }}-timestamp-dist.tar.gz
-{% endhighlight %}
-{% else %}
-{% highlight bash %}
-$ tar -zxf brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz
-{% endhighlight %}
-{% endif %}
-
-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.
-
-## 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:
-
-{% highlight bash %}
-$ brooklyn launch
-{% endhighlight %}
-
-Brooklyn will output the address of the management interface:
-
-
-`INFO Starting brooklyn web-console on loopback interface because no security config is set`
-
-`INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []`
-
-But before we really use Brooklyn, we need to setup some Locations.
-
-Stop Brooklyn with ctrl-c.
-
-## Configuring a Location
-
-Brooklyn deploys applications to Locations.
-
-Locations can be clouds, machines with fixed IPs or localhost (for testing).
-
-Brooklyn loads Location configuration from `~/.brooklyn/brooklyn.properties`.
-
-Create a `.brooklyn` folder in your home directory and download the template [brooklyn.properties]({{brooklyn_properties_url_path}}) to that folder.
-
-{% highlight bash %}
-$ mkdir ~/.brooklyn
-$ cd ~/.brooklyn
-$ wget {{brooklyn_properties_url_live}}
-{% endhighlight %}
-
-Open brooklyn.properties in a text editor and add your cloud credentials.
-
-Restart Brooklyn:
-
-{% highlight bash %}
-$ brooklyn launch
-{% endhighlight %}
-
-## Launching an Application
-
-There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
-
-For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
-
-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.
-
-
-
-
-### Chose your Cloud / Location
-
-Let's look again at our YAML blueprint:
-
-{% highlight yaml %}
-{% readj _my-web-cluster.yaml %}
-{% endhighlight %}
-
-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.
-
-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 %}
-
-**My Web Cluster Blueprint**
-
-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.
-
-
-
-
-## Monitoring and Managing Applications
-
-Click on the application name, or open the Applications tab.
-
-We can explore the management hierarchy of the application, which will show us the entities it is composed of.
-
- * My Web Cluster (A `BasicApplication`)
- * My DB (A `MySqlNode`)
- * My Web (A `ControlledDynamicWebAppCluster`)
- * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`)
- * NginxController (An `NginxController`)
-
-
-
-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.
-
-
-
-
-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.
-
-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.
-
-[](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.
-
-[](images/my-web-cluster-stop-confirm-large.png)
-
-
-### 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!
-
-Brooklyn's real power is in using Policies to automatically *manage* applications. There is also the (very useful) ability to store a catalog of application blueprints, ready to go.
-
-[Getting Started - Policies and Catalogs](policies-and-catalogs.html)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/policies-and-catalogs.md
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/policies-and-catalogs.md b/docs/website/quickstart/policies-and-catalogs.md
deleted file mode 100644
index 021c0cd..0000000
--- a/docs/website/quickstart/policies-and-catalogs.md
+++ /dev/null
@@ -1,67 +0,0 @@
----
-title: Policies and Catalogs
-layout: website-normal
----
-
-In the [previous step](index.html) we downloaded Brooklyn and used it to deploy an application to a cloud, but at its heart Brooklyn is a policy driven *management* plane.
-
-Here we will introduce Polices using a simple demo app, which we will load from a Service Catalog.
-
-We strongly advise that you complete [the first tutorial](index.html) before proceeding with this one, to make sure that
-your machine is correctly configured to be able to run Brooklyn applications. Like the previous tutorial, we are also
-assuming that you are running Linux or Mac OSX.
-
-
-## Service Catalogs
-
-Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
-
-{% highlight bash %}
-$ cd ~/.brooklyn
-$ wget {{site.url_root}}{{site.path.guide}}/use/guide/quickstart/catalog.xml
-
-$ brooklyn launch
-{% endhighlight %}
-
-Now when we open the web console, two applications are displayed from the catalog.
-
-Select the 'Demo Web Cluster with DB' and click 'Next'.
-
-[](add-application-catalog-web-cluster-with-db-large.png)
-
-Select the Location that Brooklyn should deploy to, and name your application:
-
-[](images/add-application-catalog-web-cluster-with-db-location-large.png)
-
-Click 'Finish' to launch the application as before.
-
-
-### Exploring and Testing Policies
-
-The Demo Web Cluster with DB application is pre-configured with two polices.
-
-The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy.
-
-Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster's Cluster of JBoss7Servers.
-
-You will see that the `AutoScalerPolicy` is running.
-
-[](images/jboss7-cluster-policies-large.png)
-
-
-This policy automatically scales the cluster up or down to be the right size for the cluster's current load. (One server is the minimum size allowed by the policy.)
-
-The loadbalancer's `targets` policy ensures that the loadbalancer is updated as the cluster size changes.
-
-Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint to create load on the cluster. (Download a [jmeter test plan](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).)
-
-As load is added, Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster. As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
-
-### Next
-
-The [Elastic Web Cluster Example]({{site.path.guide}}/use/examples/webcluster/index.html) page
-details how to build this demo application from scratch in Java. It shows in more detail how Brooklyn can
-complement your application with policy driven management, and how applications can be
-run from the command line.
-
-
[13/13] incubator-brooklyn git commit: point to M2-incubating not M2
in docs versions
Posted by he...@apache.org.
point to M2-incubating not M2 in docs versions
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/d975336a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/d975336a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/d975336a
Branch: refs/heads/0.7.0-M2-incubating-docs
Commit: d975336a05c84f8a88ff7dfa972dbf8bde68db72
Parents: 5382bc9
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Jan 9 16:09:04 2015 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Jan 9 16:09:04 2015 +0000
----------------------------------------------------------------------
docs/website/meta/versions.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/d975336a/docs/website/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/website/meta/versions.md b/docs/website/meta/versions.md
index 949e6f6..caba0f9 100644
--- a/docs/website/meta/versions.md
+++ b/docs/website/meta/versions.md
@@ -20,7 +20,7 @@ Apache versions:
* **[0.7.0-SNAPSHOT](/v/0.7.0-SNAPSHOT/)**: bleeding-edge (not voted on or endorsed by Apache!)
-* **[0.7.0-M2](/v/0.7.0-M2/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (Dec 2014)
+* **[0.7.0-M2-incubating](/v/0.7.0-M2-incubating/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (Dec 2014)
The versions below were made prior to joining the Apache Incubator,
[08/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/release.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/release.md b/docs/guide/dev/tips/release.md
deleted file mode 100644
index 66f730b..0000000
--- a/docs/guide/dev/tips/release.md
+++ /dev/null
@@ -1,288 +0,0 @@
----
-layout: guide-normal
-title: Release Process
-toc: /guide/toc.json
----
-
-**This needs substantial updating in light of the Apache move.**
-
-<!--
-TODO
-
-vote required? see governance.
-
-
- branch-twice-then-reversion-twice
- e.g. from master=1.0.0_SNAPSHOT we will go to
- create branch: v1.0.0_SNAPSHOT
- reversion master: 1.1.0_SNAPSHOT
- create branch and reversion: v1.0.0_RC1, v1.0.0_SNAPSHOT
- describe scripts for releasing
- docs
-
-update version, using scripts
-
-push examples to repo
-
-push docs to branch and publish
-
--->
-
-Brooklyn is published to two locations:
-
-* Sonatype, for snapshots and for staging releases
-* Maven Central, for full (GA and milestone) releases
-
-Brooklyn artifacts are generally downloaded from:
-
-1. [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.brooklyn%22),
- and (http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.brooklyn%22) for pre 0.7.0 versions
-2. [Apache](https://repository.apache.org/index.html#nexus-search;quick~org.apache.brooklyn),
-2. [Sonatype](https://oss.sonatype.org/index.html#nexus-search;quick~io.brooklyn) for pre 0.7.0 versions
-3. [GitHub](https://github.com/apache/incubator-brooklyn).
-
-
-To publish:
-
-* a snapshot release:
- * mvn deploy to Sonatype
- * (optional) publish versioned docs to brooklyncentral.github.com project
-* a (milestone) release:
- * same as above, but with some git versioning
- * deploy to Sonatype, then release to Maven Central
- * deploy a version branch to brooklyn-examples
- * deploy (or update) versioned docs
-* a major release:
- * same as above, and
- * in addition to versioned examples, update brooklyn-examples master to match the current (stable) release
- * in addition to versioned docs, publish full (front page) docs to brooklyncentral.github.com project
- * bump the snapshot version in brooklyn master to the next release
-
-
-
-## Configuration
-
-Your .m2/settings.xml must be configured with the right credentials for Sonatype
-
- <servers>
- ...
- <server>
- <username> ... </username>
- <password> ... </password>
- <id>sonatype-nexus-snapshots</id>
- </server>
- <server>
- <username> ... </username>
- <password> ... </password>
- <id>sonatype-nexus-staging</id>
- </server>
- ...
- </servers>
-You must be configured to sign artifacts using PGP.
-
-If this is the first time you have used Sonatype, the [Sonatype - Maven Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) is required reading.
-
-The code snippets below use the following variables:
-{% highlight bash %}
-
-export BROOKLYN_DIR=/path/to/brooklyncentral-brooklyn
-export EXAMPLES_DIR=/path/to/brooklyncentral-brooklyn-examples
-export SITE_DIR=/path/to/brooklyncentral-brooklyncentral.github.com
-
-export SNAPSHOT_VERSION=0.6.0-SNAPSHOT
-export RELEASE_VERSION=0.6.0-M1
-{% endhighlight %}
-
-
-## Preparing a Snapshot Release
-
-### Deploy to Sonatype
-
-Execute the following:
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-### (Option) Publish snapshot docs.
-
-(Only required if there have been significant changes to docs or java docs.)
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout master
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$SNAPSHOT_VERSION
-mkdir $SITE_DIR/v/$SNAPSHOT_VERSION
-cp -r _site/* $SITE_DIR/v/$SNAPSHOT_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$SNAPSHOT_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $SNAPSHOT_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-
-## Preparing a (Milestone) Release
-
-### Prepare a Release Branch
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR
-git checkout -b $RELEASE_VERSION
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $RELEASE_VERSION
-git commit -a -m "Changed version to $RELEASE_VERSION"
-git push -u upstream $RELEASE_VERSION
-
-{% endhighlight %}
-
-### Deploy to Sonatype, and Close the repo.
-
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-* Go to [oss.sonatype.org ... #stagingRepositories](https://oss.sonatype.org/index.html#stagingRepositories) (again, need credentials)
-* 'Close' the repo
-* Email the closed repo address to brooklyn-dev list, have people download and confirm it works.
-
-### Update the brooklyn-examples repo's version Branch
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-git checkout -b $RELEASE_VERSION
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "branch for $RELEASE_VERSION"
-git push -u origin $RELEASE_VERSION
-
-{% endhighlight %}
-
-
-### Update the Versioned Docs
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout $RELEASE_VERSION
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$RELEASE_VERSION
-mkdir $SITE_DIR/v/$RELEASE_VERSION
-cp -r _site/* $SITE_DIR/v/$RELEASE_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$RELEASE_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-## Preparing a Full Release
-
-Complete *all* above steps.
-
-### Deploy to Maven Central
-
-* Confirm that the closed Sonatype repo has no errors
-* Return to [Sonatype: Staging Repositories](https://oss.sonatype.org/index.html#stagingRepositories)
-* 'Release' the repo
-
-### Deploy the Examples master branch.
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "Updated to $RELEASE_VERSION"
-git push -u origin master
-
-{% endhighlight %}
-
-### Update the brooklyn.io Front Page Version
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-
-pushd $SITE_DIR
-# remove old root files, but not the previous version in /v/
-if [ -f start/index.html ] ; then
- for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
-else
- echo IN WRONG DIRECTORY $SITE_DIR - export SITE_DIR to continue
- exit 1
-fi
-popd
-
-# re-build for hosting at / rather than at /v/VERSION/
-_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
-
-# copy to site dir
-cp -r _site/* $SITE_DIR/
-
-# and git push
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated root docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-### Announce
-* Email the Dev and Users mailing lists.
-* Tweet from [@brooklyncentral](https://twitter.com/brooklyncentral)
-
-### Update Snapshot Version
-
-{% highlight bash %}
-
-export NEW_SNAPSHOT_VERSION=0.7.0-SNAPSHOT
-
-cd $BROOKLYN_DIR
-git checkout master
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $NEW_SNAPSHOT_VERSION
-git commit -a -m "Changed version to $NEW_SNAPSHOT_VERSION"
-git push -u upstream master
-
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/standards.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/standards.md b/docs/guide/dev/tips/standards.md
deleted file mode 100644
index 66b77b0..0000000
--- a/docs/guide/dev/tips/standards.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-layout: guide-normal
-title: Code Standards
-toc: /guide/toc.json
----
-
-Without being too restrictive about how you have to code as part of Brooklyn,
-there are some style points that really make life easier when sharing code
-among ourselves:
-
-* Use spaces (not tabs!) with 4 spaces indentation
-* Keep line length <=128
-* Don't reformat code or organize imports unless there's very good
- reason (this makes history and merges much harder)
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/toc.json b/docs/guide/dev/tips/toc.json
deleted file mode 100644
index 43fddac..0000000
--- a/docs/guide/dev/tips/toc.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-{ "title": "Miscellany",
- "file": "{{ site.path.guide }}/dev/tips/index.html" },
-{ "title": "Logging",
- "file": "{{ site.path.guide }}/dev/tips/logging.html" },
-{ "title": "Code Standards",
- "file": "{{ site.path.guide }}/dev/tips/standards.html" },
-{ "title": "Local Artifact Repo",
- "file": "{{ site.path.guide }}/dev/tips/local-artifact-repo.html" },
-{ "title": "Updating Docs",
- "file": "{{ site.path.guide }}/dev/tips/update-docs.html" },
-{ "title": "Release Process",
- "file": "{{ site.path.guide }}/dev/tips/release.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/update-docs.md b/docs/guide/dev/tips/update-docs.md
deleted file mode 100644
index ccb573e..0000000
--- a/docs/guide/dev/tips/update-docs.md
+++ /dev/null
@@ -1,14 +0,0 @@
----
-layout: guide-normal
-title: Updating the Docs
-toc: /guide/toc.json
----
-
-<!-- TODO retire this page -->
-
-The Brooklyn docs live in the **docs** project in the Brooklyn codebase.
-It's built using standard jekyll/markdown with a few extensions.
-
-Instructions for building and working with docs are in a `README.md` file
-in that folder; for the most recent version of instructions click
-[here](https://github.com/apache/incubator-brooklyn/tree/master/docs/README.md).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/toc.json b/docs/guide/dev/toc.json
deleted file mode 100644
index 2123cb0..0000000
--- a/docs/guide/dev/toc.json
+++ /dev/null
@@ -1,26 +0,0 @@
-[
-{ "title": "The Code",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "exclude": true,
- "children": {% readj code/toc.json %} },
-{ "title": "Build and Test",
- "file": "{{ site.path.guide }}/dev/build/index.html",
- "exclude": true,
- "children": {% readj build/toc.json %} },
-{ "title": "Tips and Tricks",
- "file": "{{ site.path.guide }}/dev/tips/index.html",
- "exclude": true,
- "children": {% readj tips/toc.json %} },
-{ "title": "Links",
- "file": "{{ site.path.guide }}/dev/links.html",
- "children": [
- { "title": "Github repo",
- "file": "https://github.com/apache/incubator-brooklyn/" },
- { "title": "Jira issues",
- "file": "https://issues.apache.org/jira/browse/BROOKLYN/" },
- { "title": "Maven snapshots",
- "file": "https://repository.apache.org/content/repositories/snapshots/org/apache/brooklyn" }
- ] },
-{ "title": "How to Contribute",
- "file": "{{ site.path.guide }}/dev/how-to-contrib.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 41624d0..2e2dadf 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,8 +1,20 @@
---
-layout: guide-normal
-title: Overview
-toc: /guide/toc.json
-categories: [start]
+title: User Guide
+layout: website-normal
+breadcrumbs:
+- /website/documentation/index.md
+- index.md
+children:
+- { path: /guide/start/index.md }
+- { path: /guide/concepts/index.md }
+- { path: /guide/yaml/index.md }
+- { path: /guide/java/index.md }
+- { path: /guide/ops/index.md }
+- { path: /guide/misc/index.md }
---
-{% readj start/index.include.md %}
+This is the Brooklyn User Guide for v{{ site.brooklyn-version }}:
+
+{% include list-children.html %}
+
+If you are working with the Brooklyn codebase itself, also see the [Developer Guide](dev/) for this version.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/archetype.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/archetype.md b/docs/guide/java/archetype.md
new file mode 100644
index 0000000..482e51c
--- /dev/null
+++ b/docs/guide/java/archetype.md
@@ -0,0 +1,64 @@
+---
+title: Creating from a Maven Archetype
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+### Maven Archetype
+
+Brooklyn includes a maven archetype, which can be used to create the project structure for a new application.
+
+This can be done interactively using:
+{% highlight bash %}
+$ mvn archetype:generate
+{% endhighlight %}
+
+The user will be prompted for the archetype to use (i.e. group "io.brooklyn"
+and artifact "brooklyn-archetype-quickstart"), as well as options for the project
+to be created.
+
+Alternatively, all options can be supplied at the command line. For example,
+if creating a project named "autobrick" for "com.acme":
+
+{% highlight bash %}
+$ mvn archetype:generate \
+ -DarchetypeGroupId=io.brooklyn \
+ -DarchetypeArtifactId=brooklyn-archetype-quickstart \
+ -DarchetypeVersion={{ site.brooklyn-version }} \
+ -DgroupId=com.acme -DartifactId=autobrick \
+ -Dversion=0.1.0-SNAPSHOT \
+ -DpackageName=com.acme.autobrick \
+ -DinteractiveMode=false
+{% endhighlight %}
+
+This will create a directory with the artifact name (e.g. "autobrick" in the example above).
+Note that if run from a directory containing a pom, it will also modify that pom to add this as a module!
+
+The project will contain an example app. You can run this, and also replace it with your own
+application code.
+
+To build, run the commands:
+
+{% highlight bash %}
+$ cd autobrick
+$ mvn clean install assembly:assembly
+{% endhighlight %}
+
+The assembly command will build a complete standalone distribution archive in `target/autobrick-0.1.0-SNAPSHOT-dist.tar.gz`,
+suitable for redistribution and containing `./start.sh` in the root.
+
+An unpacked equivalent is placed in `target/autobrick-0.1.0-SNAPSHOT-dist`,
+thus you can run the single-node sample locally with:
+
+{% highlight bash %}
+$ cd target/autobrick-0.1.0-SNAPSHOT-dist/autobrick-0.1.0-SNAPSHOT/
+$ ./start.sh launch --single
+{% endhighlight %}
+
+This `start.sh` script has all of the same options as the default `brooklyn` script,
+including `./start.sh help` and the `--location` argument for `launch`,
+with a couple of extra `launch` options for the sample blueprints in the archetype project:
+
+- `./start.sh launch --single` will launch a single app-server instance
+- `./start.sh launch --cluster` will launch a cluster of app-servers
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/common-usage.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/common-usage.md b/docs/guide/java/common-usage.md
new file mode 100644
index 0000000..e3cf54f
--- /dev/null
+++ b/docs/guide/java/common-usage.md
@@ -0,0 +1,42 @@
+---
+title: Common Classes and Entities
+layout: guide-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``):
+
+- *Cluster* - a homogeneous collection of entities
+- *Fabric* - a multi-location collection of entities, with one per location; often used with a cluster per location
+- *Stack* - heterogeneous (mixed types of children)
+- *Application* - user's entry point
+
+<!---
+TODO
+-->
+
+- *entity spec* defines an entity, so that one or more such entities can be created; often used by clusters/groups to define how to instantiate new children.
+- *entity factories* are often used by clusters/groups to define how to instantiate new children.
+- *traits* (mixins) providing certain capabilities, such as Resizable and Balanceable
+- *Resizable* entities can re-sized dynamically, to increase/decrease the number of child entities.
+- *Movable* entities can be migrated between *balanceable containers*.
+- *Balanceable containers* can contain *movable* entities, where each contained entity is normally associated with
+ a piece of work within that container.
+
+### Off-the-Shelf Entities
+
+brooklyn includes a selection of entities already available for use in applications,
+including appropriate sensors and effectors, and in some cases include Cluster and Fabric variants.
+(These are also useful as templates for writing new entities.)
+
+These include:
+
+- **Web**: Tomcat, JBoss, Jetty (external), Play (external); nginx; GeoScaling
+- **Data**: MySQL, Redis, MongoDB, Infinispan, GemFire (external)
+- **Containers**: Karaf
+- **Messaging**: ActiveMQ, Qpid, Rabbit MQ
+- **PaaS**: Cloud Foundry, Stackato; OpenShift
+
+
+®
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/defining-and-deploying.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/defining-and-deploying.md b/docs/guide/java/defining-and-deploying.md
new file mode 100644
index 0000000..084b4f6
--- /dev/null
+++ b/docs/guide/java/defining-and-deploying.md
@@ -0,0 +1,123 @@
+---
+title: Defining and Deploying
+layout: guide-normal
+---
+
+## Intro
+
+This walkthrough will set up a sample application which you can use as foundation for creating your own applications.
+
+The sample application is a three tier web service, composed of:
+
+* an Nginx load-balancer
+* a cluster of JBoss appservers
+* a MySQL database
+
+## Define your Application Blueprint
+
+An application blueprint is defined as a Java class, as follows:
+
+{% highlight java %}
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
+ @Override
+ public void init() {
+ MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class));
+ ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class));
+ }
+}
+{% endhighlight %}
+
+The file `ClusterWebServerDatabaseSample.java` in `src/main/java/com/acme/sample/brooklyn/sample/app/`
+provides a template to follow.
+
+
+## Deploying the Application
+
+If you have not already done so, follow the section in the
+[Getting Started Guide]({{site.path.guide}}/use/guide/quickstart/index.html) to create a `brooklyn.properties`
+file containing credentials for your preferred cloud provider.
+
+To launch this application, build the project and run the `start.sh` script in the resulting assembly:
+
+{% highlight bash %}
+$ mvn clean assembly:assembly
+
+$ cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/
+
+$ ./start.sh launch \
+ --app com.acme.sample.brooklyn.sample.app.ClusterWebServerDatabaseSample \
+ --location jclouds:aws-ec2:eu-west-1
+{% endhighlight %}
+
+(Amazon is used in this walkthrough, but lots of targets are supported,
+including `--location localhost`, fixed IP addresses, and
+everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute.)
+
+Your console will inform you that it has started a Brooklyn console at [http://localhost:8081](http://localhost:8081)
+
+[](wt-starting.png)
+
+The management console provides a view on to the entities that launched,
+including the hierarchy (appservers grouped into a cluster) and their locations.
+
+Brooklyn collects information from these entities ("sensors"),
+aggregates these for clusters and other groups (using "enrichers"),
+and exposes operations ("effectors") that can be performed on entities.
+
+[](wt-tree-jboss-sensors.png)
+
+## What Next?
+
+In addition to the sample project created by the archetype, with its README and
+`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example,
+described [in detail here]({{site.path.guide}}/use/examples/webcluster).
+
+For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS.
+Brooklyn supports some of these out-of-the-box, including a wide-range of tools which it can use Whirr to provision, such as Hadoop.
+But if you have something you don't see,
+[let us know]({{site.path.guide}}/meta/contact.html) --
+we want to work with you to
+[write a new entity]({{site.path.guide}}/dev/code/entity.html) or
+[policy]({{site.path.guide}}/dev/code/policy.html)
+and [contribute it]({{site.path.guide}}/dev/how-to-contrib.html).
+
+
+<!--
+
+Alternatively you can just add a ``main`` method to the application class as follows:
+
+{% highlight java %}
+ public static void main(String[] argv) {
+ List<String> args = Lists.newArrayList(argv);
+ String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
+ String location = CommandLineUtil.getCommandLineOption(args, "--location", DEFAULT_LOCATION);
+
+ BrooklynServerDetails server = BrooklynLauncher.newLauncher()
+ .webconsolePort(port)
+ .launch();
+
+ Location loc = server.getManagementContext().getLocationRegistry().resolve(location);
+
+ StartableApplication app = new WebClusterDatabaseExample()
+ .appDisplayName("Brooklyn WebApp Cluster with Database example")
+ .manage(server.getManagementContext());
+
+ app.start(ImmutableList.of(loc));
+
+ Entities.dumpInfo(app);
+ }
+{% endhighlight %}
+
+Compile and run this with the [``brooklyn-all`` jar]({{site.path.guide}}/start/download.html) on the classpath,
+pointing at your favourite WAR on your filesystem.
+(If the ``import`` packages aren't picked up correctly,
+you can cheat by looking at [the file in Github](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/src/main/java/brooklyn/demo/WebClusterDatabaseExample.java);
+and you'll find a sample WAR which uses the database as configured above
+[here](https://http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/).)
+ TODO example webapp url
+
+If you want to adventure beyond ``localhost`` (the default),
+simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``)
+with credentials set up as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config).
+
+-->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/entities.md b/docs/guide/java/entities.md
new file mode 100644
index 0000000..f529762
--- /dev/null
+++ b/docs/guide/java/entities.md
@@ -0,0 +1,126 @@
+---
+title: Custom Entity Development
+layout: guide-normal
+---
+
+This section details how to create new custom application components or groups as brooklyn entities.
+
+The Entity Lifecycle
+--------------------
+
+- Importance of serialization, ref to How mananagement works
+- Parents and Membership (groups)
+
+What to Extend -- Implementation Classes
+----------------------------------------
+
+- entity implementation class hierarchy
+
+ - ``SoftwareProcess`` as the main starting point for base entities (corresponding to software processes),
+ and subclasses such as ``VanillaJavaApp``
+ - ``DynamicCluster`` (multiple instances of the same entity in a location) and
+ ``DynamicFabric`` (clusters in multiple location) for automatically creating many instances,
+ supplied with an ``EntityFactory`` (e.g. ``BaseEntityFactory``) in the ``factory`` flag
+ - abstract ``Group`` for collecting entities which are parented elsewhere in the hierachy
+ - ``AbstractEntity`` if nothing else fits
+
+- traits (mixins, otherwise known as interfaces with statics) to define available config keys, sensors, and effectors;
+ and conveniences e.g. ``StartableMethods.{start,stop}`` is useful for entities which implement ``Startable``
+
+- the ``Entities`` class provides some generic convenience methods; worth looking at it for any work you do
+
+A common lifecycle pattern is that the ``start`` effector (see more on effectors below) is invoked,
+often delegating either to a driver (for software processes) or children entities (for clusters etc).
+
+See ``JBoss7Server`` and ``MySqlNode`` for exemplars.
+
+
+Configuration
+-------------
+<!---
+TODO: why to use config?
+-->
+
+- AttributeSensorAndConfigKey fields can be automatically converted for ``SoftwareProcess``.
+ This is done in ``preStart()``. This must be done manually if required for other entities,
+ often with ``ConfigToAttributes.apply(this)``.
+
+- Setting ports is a special challenge, and one which the ``AttributeSensorAndConfigKey`` is particularly helpful for,
+ cf ``PortAttributeSensorAndConfigKey`` (a subclass),
+ causing ports automatically get assigned from a range and compared with the target ``PortSupplied`` location.
+
+ Syntax is as described in the PortRange interface. For example, "8080-8099,8800+" will try port 8080, try sequentially through 8099, then try from 8800 until all ports are exhausted.
+
+ This is particularly useful on a contended machine (localhost!). Like ordinary configuration, the config is done by the user, and the actual port used is reported back as a sensor on the entity.
+
+
+Implementing Sensors
+--------------------
+
+- e.g. HTTP, JMX
+
+Sensors at base entities are often retrieved by feeds which poll the entity's corresponding instance in the real world.
+The ``SoftwareProcess`` provides a good example; by subclassing it and overriding the ``connectSensors()`` method
+you could wire some example sensors using the following:
+
+{% highlight java %}
+public void connectSensors() {
+ super.connectSensors()
+
+ httpFeed = HttpFeed.builder()
+ .entity(this)
+ .period(200)
+ .baseUri(mgmtUrl)
+ .poll(new HttpPollConfig<Boolean>(SERVICE_UP)
+ .onSuccess(HttpValueFunctions.responseCodeEquals(200))
+ .onError(Functions.constant(false)))
+ .poll(new HttpPollConfig<Integer>(REQUEST_COUNT)
+ .onSuccess(HttpValueFunctions.jsonContents("requestCount", Integer.class)))
+ .build();
+}
+
+@Override
+protected void disconnectSensors() {
+ super.disconnectSensors();
+ if (httpFeed != null) httpFeed.stop();
+}
+{% endhighlight %}
+
+In this example (a simplified version of ``JBoss7Server``), the url returns metrics in JSON.
+We report the entity as up if we get back an http response code of 200, or down if any other response code or exception.
+We retrieve the request count from the response body, and convert it to an integer.
+
+Note the first line (``super.connectSensors()``); as one descends into specific convenience subclasses (such as for Java web-apps), the work done by the parent class's overridden methods may be relevant, and will want to be invoked or even added to a resulting list.
+
+For some sensors, and often at compound entities, the values are obtained by monitoring values of other sensors on the same (in the case of a rolling average) or different (in the case of the average of children nodes) entities. This is achieved by policies, described below.
+
+Implementing Effectors
+----------------------
+
+The ``Entity`` interface defines the sensors and effectors available. The entity class provides
+wiring for the sensors, and the effector implementations. In simple cases it may be straightforward
+to capture the behaviour of the effectors in a simple methods.
+For example deploying a WAR to a cluster can be done as follows:
+
+*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+
+<!---
+TODO show an effector which recurses across children
+-->
+
+For some entities, specifically base entities, the implementation of effectors might need other tools (such as SSH), and may vary by location, so having a single implementation is not appropriate.
+
+The problem of multiple inheritance (e.g. SSH functionality and entity inheritance) and multiple implementations (e.g. SSH versus Windows) is handled in brooklyn using delegates called _drivers_.
+
+In the implementations of ``JavaWebApp`` entities, the behaviour which the entity always does is captured in the entity class (for example, breaking deployment of multiple WARs into atomic actions), whereas implementations which is specific to a particular entity and driver (e.g. using scp to copy the WARs to the right place and install them, which of course is different among appservers, or using an HTTP or JMX management API, again where details vary between appservers) is captured in a driver class.
+
+Routines which are convenient for specific drivers can then be inherited in the driver class hierarchy. For example, when passing JMX environment variables to Java over SSH, ``JavaSoftwareProcessSshDriver`` extends ``AbstractSoftwareProcessSshDriver`` and parents ``JBoss7SshDriver``.
+
+<!---
+TODO more drivers such as jmx, etc are planned
+-->
+
+Testing
+-------
+
+* Run in a mock ``SimulatedLocation``, defining new metaclass methods to be able to start there and assert the correct behaviour when that is invoked
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/entity.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/entity.md b/docs/guide/java/entity.md
new file mode 100644
index 0000000..84c1b8e
--- /dev/null
+++ b/docs/guide/java/entity.md
@@ -0,0 +1,90 @@
+---
+layout: guide-normal
+title: Writing an Entity
+---
+
+## Ways to write an entity
+
+There are several ways to write a new entity:
+
+* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`.
+* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**.
+* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`.
+* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef)
+
+The rest of this section covers writing an entity in pure-java (or other JVM languages).
+
+
+## Things To Know
+
+All entities have an interface and an implementation. The methods on the interface
+are its effectors; the interface also defines its sensors.
+
+Entities are created through the management context (rather than calling the
+constructor directly). This returns a proxy for the entity rather than the real
+instance, which is important in a distributed management plane.
+
+All entity implementations inherit from `AbstractEntity`,
+often through one of the following:
+
+* **`SoftwareProcessImpl`**: if it's a software process
+* **`VanillaJavaAppImpl`**: if it's a plain-old-java app
+* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app
+* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities
+
+Software-based processes tend to use *drivers* to install and
+launch the remote processes onto *locations* which support that driver type.
+For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass,
+targetting `SshMachineLocation` (a machine to which Brooklyn can ssh).
+The various `SoftwareProcess` entities above (and some of the exemplars
+listed at the end of this page) have their own dedicated drivers.
+
+Finally, there are a collection of *traits*, such as `Resizable`,
+in the package ``brooklyn.entity.trait``. These provide common
+sensors and effectors on entities, supplied as interfaces.
+Choose one (or more) as appropriate.
+
+
+
+## Key Steps
+
+So to get started:
+
+1. Create your entity interface, extending the appropriate selection from above,
+ to define the effectors and sensors.
+2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface,
+ where `YourEntityImpl` will be the class name for your entity implementation.
+3. Create your entity class, implementing your entity interface and extending the
+ classes for your chosen entity super-types. Naming convention is a suffix "Impl"
+ for the entity class, but this is not essential.
+4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`).
+ The naming convention is to have a suffix "Driver".
+5. Create the driver class, implementing your driver interface, and again extending as appropriate.
+ Naming convention is to have a suffix "SshDriver" for an ssh-based implementation.
+ The correct driver implementation is found using this naming convention, or via custom
+ namings provided by the `BasicEntityDriverFactory`.
+6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify
+ your driver interface.
+7. Provide the implementation of missing lifecycle methods in your driver class (details below)
+8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`)..
+ See the sensor feeds, such as `HttpFeed` and `JmxFeed`.
+
+Any JVM language can be used to write an entity. However use of pure Java is encouraged for
+entities in core brooklyn.
+
+
+## Helpful References
+
+A few handy pointers will help make it easy to build your own entities.
+Check out some of the exemplar existing entities
+(note, some of the other entities use deprecated utilities and a deprecated class
+hierarchy; it is suggested to avoid these, looking at the ones below instead):
+
+* `JBoss7Server`
+* `MySqlNode`
+
+You might also find the following helpful:
+
+* **[Entity Design Tips]({{site.path.guide}}/dev/tips/index.html#EntityDesign)**
+* The **[User Guide]({{site.path.guide}}/use/guide/index.html)**
+* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)**
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md
new file mode 100644
index 0000000..eb58e8a
--- /dev/null
+++ b/docs/guide/java/index.md
@@ -0,0 +1,22 @@
+---
+title: Java Blueprints
+title_in_menu: Java Blueprints
+layout: website-normal
+children:
+- archetype.md
+- defining-and-deploying.md
+- topology-dependencies-management-policies.md
+- common-usage.md
+- entity.md
+- entities.md
+- policy.md
+- policies.md
+- service-state.md
+---
+
+Java blueprints are much more powerful than YAML but is also rather more difficult.
+Advanced Java skills are required.
+
+{% include list-children.html %}
+
+Brooklyn makes it easy to describe the structure and management of sophisticated distributed applications, and then it makes it easy to launch them in a cloud, with on-going automated management.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/policies.md b/docs/guide/java/policies.md
new file mode 100644
index 0000000..5bc8289
--- /dev/null
+++ b/docs/guide/java/policies.md
@@ -0,0 +1,123 @@
+---
+title: Policies
+layout: guide-normal
+
+---
+
+Policies perform the active management enabled by Brooklyn.
+They can subscribe to entity sensors and be triggered by them or they can run periodically.
+
+<!---
+TODO, clarify below, memebers of what?
+-->
+Policies can add subscriptions to sensors on any entity. Normally a policy will subscribe to its related entity, to the child entities, and/or those entities which are members.
+
+When a policy runs it can:
+
+* perform calculations,
+* look up other values,
+* invoke efectors (management policies) or,
+* cause the entity associated with the policy to emit sensor values (enricher policies).
+
+Entities can have zero or more ``Policy`` instances attached to them.
+
+Writing Policies
+----------------
+
+### Sample Policy
+
+<!---
+TODO
+-->
+
+*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+
+### Best Practice
+
+The following recommendations should be considered when designing policies:
+
+#### Management should take place as "low" as possible in the hierarchy
+* place management responsibility in policies at the entity, as much as possible ideally management should take run as a policy on the relevant entity
+
+* place escalated management responsibility at the parent entity. Where this is impractical, perhaps because two aspects of an entity are best handled in two different places, ensure that the separation of responsibilities is documented and there is a group membership relationship between secondary/aspect managers.
+
+
+#### Policies should be small and composable
+<!--
+TODO Requires Content
+-->
+
+e.g. one policy which takes a sensor and emits a different, enriched sensor, and a second policy which responds to the enriched sensor of the first (e.g. a policy detects a process is maxed out and emits a TOO_HOT sensor; a second policy responds to this by scaling up the VM where it is running, requesting more CPU)
+#### Where a policy cannot resolve a situation at an entity, the issue should be escalated to a manager with a compatible policy.
+
+Typically escalation will go to the entity parent, and then cascade up.
+e.g. if the earlier VM CPU cannot be increased, the TOO_HOT event may go to the parent, a cluster entity, which attempts to balance. If the cluster cannot balance, then to another policy which attempts to scale out the cluster, and should the cluster be unable to scale, to a third policy which emits TOO_HOT for the cluster.
+
+#### Management escalation should be carefully designed so that policies are not incompatible
+
+Order policies carefully, and mark sensors as "handled" (or potentially "swallow" them locally), so that subsequent policies and parent entities do not take superfluous (or contradictory) corrective action.
+
+
+For this release, some of the mechanisms for implementing the above practices are still being developed.
+
+### Implementation Classes
+
+*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+
+- extend ``AbstractPolicy``, or override an existing policy
+
+
+Off-the-Shelf Policies
+----------------------
+
+Policies are highly reusable as their inputs, thresholds and targets are customizable.
+
+### Management Policies
+- Resizer Policy
+
+ Increases or decreases the size of a Resizable entity based on an aggregate sensor value, the current size of the entity, and customized high/low watermarks.
+
+ A Resizer policy can take any sensor as a metric, have its watermarks tuned live, and target any resizable entity - be it an application server managing how many instances it handles, or a tier managing global capacity.
+
+ e.g. if the average request per second across a cluster of Tomcat servers goes over the high watermark, it will resize the cluster to bring the average back to within the watermarks.
+
+<!---
+TODO - list some
+TODO - describe how they can be customised (briefly mention sensors)
+-->
+
+
+### Enricher Policies
+
+* Delta
+
+ Converts absolute sensor values into a delta.
+
+
+* Time-weighted Delta
+
+ Converts absolute sensor values into a delta/second.
+
+* Rolling Mean
+
+ Converts the last *N* sensor values into a mean.
+
+* Rolling Time-window Mean
+
+ Converts the last *N* seconds of sensor values into a weighted mean.
+
+* Custom Aggregating
+
+ Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc.
+
+Implementing Policies
+---------------------
+
+<!---
+TODO
+-->
+
+*This section is not yet complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+
+Please see the class* ``brooklyn.policy.Policy`` *and implementations.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/policy.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/policy.md b/docs/guide/java/policy.md
new file mode 100644
index 0000000..d785f0d
--- /dev/null
+++ b/docs/guide/java/policy.md
@@ -0,0 +1,46 @@
+---
+layout: guide-normal
+title: Writing a Policy
+---
+
+Policies perform the active management enabled by Brooklyn.
+Each policy instance is associated with an entity,
+and at runtime it will typically subscribe to sensors on that entity or children,
+performing some computation and optionally actions when a subscribed sensor event occurs.
+This action might be invoking an effector or emitting a new sensor,
+depending the desired behvaiour is.
+
+Writing a policy is straightforward.
+Simply extend ``AbstractPolicy``,
+overriding the ``setEntity`` method to supply any subscriptions desired:
+
+{% highlight java %}
+ @Override
+ public void setEntity(EntityLocal entity) {
+ super.setEntity(entity)
+ subscribe(entity, TARGET_SENSOR, this)
+ }
+{% endhighlight %}
+
+and supply the computation and/or activity desired whenever that event occurs:
+
+{% highlight java %}
+ @Override
+ public void onEvent(SensorEvent<Integer> event) {
+ int val = event.getValue()
+ if (val % 2 == 1)
+ entity.sayYoureOdd();
+ }
+{% endhighlight %}
+
+You'll want to do more complicated things, no doubt,
+like access other entities, perform multiple subscriptions,
+and emit other sensors -- and you can.
+See the source code, and see some commonly used policies
+in ``AutoScalerPolicy`` and ``RollingMeanEnricher``.
+
+One rule of thumb, to close on:
+try to keep policies simple, and compose them together at runtime;
+for instance, if a complex computation triggers an action,
+define one **enricher** policy to aggregate other sensors and emit a new sensor,
+then write a second policy to perform that action.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/service-state.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/service-state.md b/docs/guide/java/service-state.md
new file mode 100644
index 0000000..32212bc
--- /dev/null
+++ b/docs/guide/java/service-state.md
@@ -0,0 +1,73 @@
+---
+title: Service State
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Any entity can use the standard "service-up" and "service-state"
+sensors to inform other entities and the GUI about its status.
+
+In normal operation, entities should publish at least one "service not-up indicator",
+using the `ServiceNotUpLogic.updateNotUpIndicator` method. Each such indicator should have
+a unique name or input sensor. `Attributes.SERVICE_UP` will then be updated automatically
+when there are no not-up indicators.
+
+When there are transient problems that can be detected, to trigger `ON_FIRE` status
+entity code can similarly set `ServiceProblemsLogic.updateProblemsIndicator` with a unique namespace,
+and subsequently clear it when the problem goes away.
+These problems are reflected at runtime in the `SERVICE_PROBLEMS` sensor,
+allowing multiple problems to be tracked independently.
+
+When an entity is changing the expected state, e.g. starting or stopping,
+the expected state can be set using `ServiceStateLogic.setExpectedState`;
+this expected lifecycle state is considered together with `SERVICE_UP` and `SERVICE_PROBLEMS`
+to compute the actual state. By default the logic in `ComputeServiceState` is applied.
+
+For common entities, good out-of-the-box logic is applied, as follows:
+
+* For `SoftwareProcess` entities, lifecycle service state is updated by the framework
+ and a service not-up indicator is linked to the driver `isRunning()` check.
+
+* For common parents, including `AbstractApplication` and `AbstractGroup` subclasses (including clusters, fabrics, etc),
+ the default enrichers analyse children and members to set a not-up indicator
+ (requiring at least one child or member who is up) and a problem indicator
+ (if any children or members are on-fire).
+ In some cases other quorum checks are preferable; this can be set e.g. by overriding
+ the `UP_QUORUM_CHECK` or the `RUNNING_QUORUM_CHECK`, as follows:
+
+ public static final ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(AbstractGroup.UP_QUORUM_CHECK,
+ "Require all children and members to be up for this node to be up",
+ QuorumChecks.all());
+
+ Alternatively the `initEnrichers()` method can be overridden to specify a custom-configured
+ enricher or set custom config key values (as done e.g. in `DynamicClusterImpl` so that
+ zero children is permitted provided when the initial size is configured to be 0).
+
+
+For sample code to set and more information on these methods' behaviours,
+see javadoc in `ServiceStateLogic`,
+overrides of `AbstractEntity.initEnrichers()`
+and tests in `ServiceStateLogicTests`.
+
+<!-- TODO include more documentation, sample code (ideally extracted on the fly from test cases so we know it works!) -->
+
+
+## Notes on Advanced Use
+
+The enricher to derive `SERVICE_UP` and `SERVICE_STATE_ACTUAL` from the maps and expected state values discussed above
+is added by the `AbstractEntity.initEnrichers()` method.
+This method can be overridden -- or excluded altogether by by overriding `init()` --
+and can add enrichers created using the `ServiceStateLogic.newEnricherFromChildren()` method
+suitably customized using methods on the returned spec object, for instance to look only at members
+or specify a quorum function (from `QuorumChecks`).
+If different logic is required for computing `SERVICE_UP` and `SERVICE_STATE_ACTUAL`,
+use `ServiceStateLogic.newEnricherFromChildrenState()` and `ServiceStateLogic.newEnricherFromChildrenUp()`,
+noting that the first of these will replace the enricher added by the default `initEnrichers()`,
+whereas the second one runs with a different namespace (unique tag).
+For more information consult the javadoc on those classes.
+
+Entities can set `SERVICE_UP` and `SERVICE_STATE_ACTUAL` directly.
+Provided these entities never use the `SERVICE_NOT_UP_INDICATORS` and `SERVICE_PROBLEMS` map,
+the default enrichers will not override these values.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/topology-dependencies-management-policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/topology-dependencies-management-policies.md b/docs/guide/java/topology-dependencies-management-policies.md
new file mode 100644
index 0000000..8039d2c
--- /dev/null
+++ b/docs/guide/java/topology-dependencies-management-policies.md
@@ -0,0 +1,69 @@
+---
+layout: guide-normal
+title: Topology, Dependencies, and Management Policies
+title_in_menu: Topology, Dependencies, and Management Policies
+---
+Of course in the real world, application deployments are more interesting;
+they do things and need configuration. For instance you might need to:
+
+* specify a WAR file
+* initialize the database
+* tell the webapp servers where to find the database
+
+Let's show how these are done using Brooklyn.
+We assume the WAR file and the database init script are accessible
+on the classpath, but a range of URL formats is supported.
+The "dependent inter-process configuration" -- giving the database's URL
+to the webapps -- we'll do here with a JVM system property,
+but you're free to use any mechanism you wish.
+
+Under the covers, ``attributeWhenReady`` is monitoring a sensor from MySQL
+and generating a string to pass to the webapp software processes; ``formatString``
+is a similar utility that returns a string once all of its parts have been resolved.
+Due to the use of futures, the Brooklyn webapp entities will automatically
+block "at the last moment" when the value is needed
+(but after e.g. the VMs have been provisioned, to speed things up).
+
+{% highlight java %}
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
+ @Override
+ public void init() {
+ MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
+ .configure(MySqlNode.CREATION_SCRIPT_URL, "classpath://visitors-database-setup.sql"));
+
+ ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+ .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
+ .configure("httpPort", "8080+")
+ .configure("war", WAR_PATH)
+ .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"),
+ formatString("jdbc:%s%s?user=%s\\&password=%s",
+ attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
+ }
+}
+{% endhighlight %}
+
+We now see our app at the Nginx URL:
+
+[](wt-deployed-application.png)
+
+Finally, we'll bring in some active management: we're going to monitor requests per second,
+and scale out if this exceeds 100 up to a maximum of 5 servers.
+This is a naively simple policy, but it shows Brooklyn's real metier,
+running management policies for applications whose topology it knows.
+
+{% highlight java %}
+ web.getCluster().addPolicy(AutoScalerPolicy.builder().
+ metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
+ sizeRange(1, 5).
+ metricRange(10, 100).
+ build());
+{% endhighlight %}
+
+*Policies* in Brooklyn typically subscribe to sensors, perform some computation, and if necessary invoke effectors on entities. This is where the ability to group entities
+becomes very useful -- policies can be attached to group entities, and groups themselves can be hierarchical. It's also handy that often Brooklyn creates the entities,
+so it knows what the hierarchy is.
+
+Under the covers, this ``AutoScalerPolicy`` attaches to any ``Resizable`` entity (exposing a ``resize`` effector), and monitors a specified sensor (or function) attempting to keep it within healthy limits. A separate policy operates at the ``Controlled`` cluster to ensure the load-balancer is updated as the pool of web servers expands and contracts.
+
+Fire up a JMeter session (or other load testing tool) and blast the Nginx address. The auto-scaler policy will scale up the cluster.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-deployed-application-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-deployed-application-700.png b/docs/guide/java/wt-deployed-application-700.png
new file mode 100644
index 0000000..7ef90d9
Binary files /dev/null and b/docs/guide/java/wt-deployed-application-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-deployed-application.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-deployed-application.png b/docs/guide/java/wt-deployed-application.png
new file mode 100644
index 0000000..751402e
Binary files /dev/null and b/docs/guide/java/wt-deployed-application.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-starting-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-starting-700.png b/docs/guide/java/wt-starting-700.png
new file mode 100644
index 0000000..c87a539
Binary files /dev/null and b/docs/guide/java/wt-starting-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-starting.png b/docs/guide/java/wt-starting.png
new file mode 100644
index 0000000..970805f
Binary files /dev/null and b/docs/guide/java/wt-starting.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-tree-jboss-sensors-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-tree-jboss-sensors-700.png b/docs/guide/java/wt-tree-jboss-sensors-700.png
new file mode 100644
index 0000000..3dfc7f2
Binary files /dev/null and b/docs/guide/java/wt-tree-jboss-sensors-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/java/wt-tree-jboss-sensors.png
----------------------------------------------------------------------
diff --git a/docs/guide/java/wt-tree-jboss-sensors.png b/docs/guide/java/wt-tree-jboss-sensors.png
new file mode 100644
index 0000000..4c44ea9
Binary files /dev/null and b/docs/guide/java/wt-tree-jboss-sensors.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/license/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/license/index.md b/docs/guide/license/index.md
deleted file mode 100644
index af33ed0..0000000
--- a/docs/guide/license/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-layout: guide-normal
-title: Brooklyn Licenses
-toc: /guide/toc.json
----
-
-## License
-
-Apache Brooklyn is released to the public as open source under the
-terms of the [Apache License, v2.0](license.html).
-
-Apache Brooklyn is currently undergoing Incubation at the Apache Software Foundation.
-
-
-## Trademark
-
-The Brooklyn name and logo are trademarks owned by the Apache Software Foundation.
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/license/license.md
----------------------------------------------------------------------
diff --git a/docs/guide/license/license.md b/docs/guide/license/license.md
deleted file mode 100644
index 6fe8339..0000000
--- a/docs/guide/license/license.md
+++ /dev/null
@@ -1,194 +0,0 @@
----
-layout: guide-normal
-title: License
-toc: /guide/toc.json
----
-
-Brooklyn is licensed to the public as open source under the
-terms of the [Apache License, v2.0](http://www.apache.org/licenses/LICENSE-2.0).
-You may not use this content except in compliance with the License.
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
-
-{% highlight text %}
-
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
- 1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
- 2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
- 3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
- 4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
- 5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
- 6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
- 7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
- 8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
- 9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/license/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/license/toc.json b/docs/guide/license/toc.json
deleted file mode 100644
index 384d368..0000000
--- a/docs/guide/license/toc.json
+++ /dev/null
@@ -1,4 +0,0 @@
-[
-{ "title": "Apache License v2.0",
- "file": "{{ site.path.guide }}/license/license.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/brooklyn-gpg-public-key.asc
----------------------------------------------------------------------
diff --git a/docs/guide/meta/brooklyn-gpg-public-key.asc b/docs/guide/meta/brooklyn-gpg-public-key.asc
deleted file mode 100644
index 3b515a4..0000000
--- a/docs/guide/meta/brooklyn-gpg-public-key.asc
+++ /dev/null
@@ -1,21 +0,0 @@
------BEGIN PGP PUBLIC KEY BLOCK-----
-Version: GnuPG/MacGPG2 v2.0.18 (Darwin)
-Comment: GPGTools - http://gpgtools.org
-
-mQENBFDsSLEBCAC2JxQHeXpL3oGN2IickcG9C49gkxIsws4hpasQModVipezrQi0
-9pLq4lkB01GgC2sfPH+XXE8rCpA9EL0e4wVA7JICz5AsLZAAJH91tKksL20tLMeU
-Yrbufaq1ga7ifk3JWhF4iwvkDMBKyCjrF173nI+2TwX2XfNTQpzoQGOL1bNvS4NZ
-AD9JeXGW2D996zHdSK+x3wVdY3cDECvVMuw61+5ytZrGNnyvaaWTl3lJUyydPXHQ
-5TXVtbQH5WgYCLPr4E95axJ0BoY8H+fEaG1Uax1a+xLumVWhiWNp7rMvmgcZXuJO
-fx+wXAIbRNlAHoJcdZ4NCReRxDIBQ+2HsU1zABEBAAG0bUJyb29rbHluIFByb2pl
-Y3QgKGJyb29rbHluLmlvKSAoS2V5IHVzZWQgdG8gYXV0aGVudGljYXRlIEJyb29r
-bHluIGFydGlmYWN0cykgPGJyb29rbHluLWRldkBncm91cHMuZ29vZ2xlLmNvbT6J
-AT8EEwECACkFAlDsSLECGy8FCQeGH4AHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIX
-gAAKCRANhinnSRLCsOdIB/4tUVShup2NHXJ9acCah8TuEN4GmN9dBiD9YsGW66SR
-/ptY0Gn9XExl2wbmQW+7TQg3QUGv8uffwYLtnMwnmCp/WwgE+uSnRmcENxa9GuTu
-PLlURKKGK0C9ljTAHwXtPcIYxPNN3BT4VB56ME1DTBRCgEvudaNSANs8/kT88kE2
-eMC7x0Uo3/P38Ob8XSOfR8c6G6nSz6jILcRBXZTPNNK4svyqF5XHIru65d3/0+mr
-bpfcDLcUQYms0MpPmO1RCHLZWwJLsPUIxNwGGnKJc8/RNEvQinK+Ap0cf+PGUQSX
-PhB6Z81ROFIVToEVZslgSiL+u4Tc7zXDfDQDY4HeLY2t
-=w/CG
------END PGP PUBLIC KEY BLOCK-----
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/contact.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/contact.include.md b/docs/guide/meta/contact.include.md
deleted file mode 100644
index e0d1e4b..0000000
--- a/docs/guide/meta/contact.include.md
+++ /dev/null
@@ -1,9 +0,0 @@
-
-Contact us on the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/).
-
-Additionally look for us on:
-
-* **IRC**: #brooklyncentral ([IRC??](/meta/irc.html))
-* **Twitter**: @brooklyncentral #brooklyncentral
-
-We'd love to hear from you!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/contact.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/contact.md b/docs/guide/meta/contact.md
deleted file mode 100644
index c318a1f..0000000
--- a/docs/guide/meta/contact.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: guide-normal
-title: Contact
-toc: /guide/toc.json
----
-
-{% readj contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/irc.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/irc.md b/docs/guide/meta/irc.md
deleted file mode 100644
index 9324bd2..0000000
--- a/docs/guide/meta/irc.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-layout: guide-normal
-title: IRC
-toc: /guide/toc.json
----
-
-IRC is a basic group chat system used by many open source projects to enable developers to
-collaborate and to help users communicate and support each other. Brooklyn has an IRC
-channel where users and developers hang out.
-
-## Getting Help On IRC
-
-When you connect to the Brooklyn IRC channel, say Hi and then ask your question. It may
-take a little while for someone to see and respond to your question. (Be
-patient if you don't get an instant answer - unless there's already a conversation
-happening folk will probably not have their eyes on the channel.)
-
-You may want to do other things while you wait, like reviewing the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
-lists to see if anyone has had the same issue before.
-
-## Brooklyn IRC Channel
-
-* **IRC Server:** irc.freenode.net
-* **Channel/Room:** #brooklyncentral
-* **Port:** 6667 (Default)
-
-If you are new to IRC, there is a web interface at [webchat.freenode.net](http://webchat.freenode.net/?channels=brooklyncentral)
-but you may prefer to checkout the [Wikipedia IRC article](http://en.wikipedia.org/wiki/IRC#Client_software)
-for an IRC application.
-
-You can find more information about using IRC at [irchelp.org](http://www.irchelp.org/).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/meta/toc.json b/docs/guide/meta/toc.json
deleted file mode 100644
index f01fa8e..0000000
--- a/docs/guide/meta/toc.json
+++ /dev/null
@@ -1,8 +0,0 @@
-[
-{ "title": "Versions",
- "file": "{{ site.path.guide }}/meta/versions.html" },
-{ "title": "Verify",
- "file": "{{ site.path.guide }}/meta/verify.html" },
-{ "title": "Contact",
- "file": "{{ site.path.guide }}/meta/contact.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/versions.md b/docs/guide/meta/versions.md
deleted file mode 100644
index 4ce1256..0000000
--- a/docs/guide/meta/versions.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-layout: guide-normal
-title: Versions
-toc: /guide/toc.json
----
-
-**TODO: page needs overhaul with separate new main site**
-
-
-<!--- display which version we are using, based on where it is written -->
-
-### Brooklyn v{{ site.brooklyn-version }}
-
-
-{% if site.server %}
-> **Server (debug) mode detected.**
-
-> *Links to other versions on this page and others will likely not work when running in server/debug mode.
-Files must be copied to the brooklyncentral.github.com repo for these links to resolve correctly.*
-
-> *Debug page generated {{ site.time }}*
-{% endif %}
-
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-<!--- snapshot version -->
-
- {% if site.path.guide == '' %}
-
-<!--- current version (served off root of site) is snapshot (unusual) -->
-
-This is the documentation for the current snapshot version of Brooklyn,
-generated {{ site.time | date_to_string }}.
-
- {% else %}
-
-<!--- archive docs -->
-
-This is the documentation for a snapshot version of Brooklyn,
-generated {{ site.time | date_to_string }}.
-
-[View current documentation here.](/meta/versions.html)
-
-
- {% endif %}
-
-NB: "Snapshot" means it is the code at a point in time,
-and that a reference to this version {{ site.brooklyn-version }}
-may resolve to different code at a different point in time.
-Where possible it is preferable to develop against a GA version
-rather than a shapshot.
-
-{% else %}
-<!--- not snapshot -->
-
- {% if site.path.guide == '' %}
-
-<!--- current version (served off root of site) -->
-
-This is the documentation for the latest stable version of Brooklyn,
-generated {{ site.time | date_to_string }}.
-Other versions with documentation available are listed below.
-
- {% else %}
-
-<!--- archive version -->
-
-This is the archived documentation for Brooklyn {{ site.brooklyn-version }}
-(generated {{ site.time }}, archived under {{ site.path.guide }}).
-
-[View current documentation here.](/meta/versions.html)
-
- {% endif %}
-{% endif %}
-
-
-### Version History
-
-* **[0.7.0-SNAPSHOT (master)](/v/0.7.0-SNAPSHOT)**: since 0.6.0, lots of work on yaml, persistence, policies, and more supported systems
-
-* **[0.7.0](/v/0.7.0-M1/)**: most recent milestone release
-
-* **[0.6.0](/v/0.6.0/)**: use of spec objects, chef and windows support, more clouds (Nov 2013)
-
-* **[0.5.0](/v/0.5.0/)**: includes new JS GUI and REST API, rebind/persistence support, cleaner model and naming conventions, more entities (May 2013)
-
-* **[0.4.0](/v/0.4.0/)**: initial public GA release of Brooklyn to Maven Central, supporting wide range of entities and examples (Jan 2013)
-
-Note: To prevent accidentally referring to out-of-date information,
-a banner is displayed when accessing specific versions from the archive.
-You may
-<a href="#" onclick="set_user_versions_all();">disable all warnings</a> or
-<a href="#" onclick="clear_user_versions();">re-enable all warnings</a>.
-
-
-### Versioning
-
-Brooklyn uses the [semantic versioning](http://semver.org/) guidelines. Releases will be numbered with the following format:
-
-`Brooklyn <major>.<minor>.<patch>`
-
-Breaking backward compatibility increments the `<major>` version.
-New additions without breaking backward compatibility ups the `<minor>` version.
-Bug fixes and misc changes bumps the `<patch>` version.
-New major and minor releases zero the less significant counters.
-
-Additionally, Brooklyn's release process include Snapshots, Milestones and Release Candidates.
-
-A Snapshot (`-SNAPSHOT`) is the bleeding edge. This will not be stable.
-
-Milestone versions (`-Mn`) are frozen snapshots. Some code features may be stable, but the documentation and examples may not be complete.
-
-A Release Candidate (`-rc.n`) is a just-about-ready version. Release candidates are tested against our acceptance criteria, and qualifying builds are promoted as final.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/misc/download.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/download.md b/docs/guide/misc/download.md
new file mode 100644
index 0000000..011d9f3
--- /dev/null
+++ b/docs/guide/misc/download.md
@@ -0,0 +1,170 @@
+---
+layout: guide-normal
+title: Downloads
+---
+{% include fields.md %}
+
+First time user? The [getting started]({{ site.path.guide }}/use/guide/quickstart/index.html) guide will walk you through downloading Brooklyn, setup of your `brooklyn.properties` and `catalog.xml` files, and then trying the [examples](#examples).
+
+## Download Version {{ site.brooklyn-version }}
+
+<table>
+ <tr>
+ <th style='text-align:left'>Download</th>
+ <th style='text-align:left'>File/Format</th>
+ <th>checksums <small><a href="/meta/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
+ </tr>
+ <tr>
+ <td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
+ <td style='text-align:left'><a href='{{ this_dist_url_zip }}' title='Download ZIP archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.zip</a></td>
+ <td><small><a href='{{ this_dist_url_zip }}.asc'>PGP</a>, <a href='{{ this_dist_url_zip }}.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'><a href='{{ this_dist_url_tgz }}' title='Download TGZ archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz</a></td>
+ <td ><small><a href='{{ this_dist_url_tgz }}.asc'>PGP</a>, <a href='{{ this_dist_url_tgz }}.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'>All Jar</td>
+ <td style='text-align:left'><a href='{{ this_alljar_url_jar }}' title='Download the ALL JAR'>brooklyn-all-{{ site.brooklyn-version }}-with-dependencies.jar</a></td>
+ <td><small><a href='{{ this_alljar_url_jar }}.asc'>PGP</a>, <a href='{{ this_alljar_url_jar }}.sha1'>SHA1</a></small></td>
+ </tr>
+ <tr>
+ <td style='text-align:left'>Apache Repo</td>
+ <td style='text-align:left'>
+ <a href='{{ this_anything_url_search }}' title='Search'><i>GUI</i></a>
+ —
+ <a href='{{ this_dist_url_list }}' title='List'><i>dir</i></a>
+ </td>
+ <td> — </td>
+ </tr>
+ <tr>
+ <td style='text-align:left'>Release Notes</td>
+ <td style='text-align:left'><a href='{{ site.path.guide }}/misc/release-notes.html'>{{ site.brooklyn-version }}</a></td>
+ <td> — </td>
+ </tr>
+</table>
+
+
+<a name="distro"></a>
+
+## The Distro
+
+The distribution archive contains Brooklyn as a standalone executable package.
+
+* [This version ZIP]({{ this_dist_url_zip }})
+* [This version TGZ]({{ this_dist_url_tgz }})
+* [Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-dist/)
+* [Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-dist/)
+
+Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-dist/) for stable releases
+and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-dist/) for snapshot versions.
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+**Please note**: You are reading the documentation for a snapshot version of Brooklyn.
+You should always confirm that the source and date for snapshot artifacts.
+{% endif %}
+
+
+<a name="alljar"></a>
+
+## The All Jar
+
+This is a single JAR containing all of Brooklyn and its dependencies, for developing Brooklyn into your own applications. If not using maven, just add it to your classpath.
+
+* [This version]({{ this_alljar_url_jar }})
+* [All Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-all/)
+* [All Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-all/)
+
+Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-all/) for stable releases
+and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-all/) for snapshot versions.
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+**Again**, check the source and date for SNAPSHOT JARs.
+{% endif %}
+
+## Release Notes
+
+Release notes can be found [here]({{ site.path.guide }}/start/release-notes.html).
+
+
+<a name="examples"></a>
+
+## Examples
+
+Examples can be found in the main Brooklyn codebase, in the `/examples` directory.
+
+A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html).
+
+
+<a name="maven"></a>
+
+## Maven
+
+If you use Maven, you can add Brooklyn with the following in your pom:
+
+<!-- the comment is included due to a jekyll/highlight bug which
+ removes indentation on the first line in a highlight block;
+ we want the actual XML indented so you can cut and paste into a pom.xml sensibly -->
+{% highlight xml %}
+<!-- include all Brooklyn items in our project -->
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.brooklyn</groupId>
+ <artifactId>brooklyn-all</artifactId>
+ <version>{{ site.brooklyn-version }}</version>
+ </dependency>
+ </dependencies>
+{% endhighlight %}
+
+`brooklyn-all` (used above) brings in all dependencies, including jclouds.
+If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``,
+and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``brooklyn-software-messaging``, or others
+(browse the full list [here]({{ this_anything_url_search }})).
+
+If you wish to use the Apache snapshot repo and/or Cloudsoft repositories,
+you can add some of the following sections:
+
+{% highlight xml %}
+<!-- include repos for snapshot items and other dependencies -->
+ <repositories>
+ <repository>
+ <id>apache-nexus-snapshots</id>
+ <name>Apache Nexus Snapshots</name>
+ <url>https://repository.apache.org/content/repositories/snapshots</url>
+ <releases> <enabled>false</enabled> </releases>
+ <snapshots> <enabled>true</enabled> </snapshots>
+ </repository>
+ <repository>
+ <id>cloudsoft-cloudfront-releases-repo</id>
+ <url>http://developers.cloudsoftcorp.com/maven/releases/</url>
+ </repository>
+ <repository>
+ <id>cloudsoft-cloudfront-snapshots-repo</id>
+ <url>http://developers.cloudsoftcorp.com/maven/snapshots/</url>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ <checksumPolicy>fail</checksumPolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+{% endhighlight %}
+
+{% if SNAPSHOT %}
+**Please note**: to use a snapshot version of Brooklyn, you must either have Brooklyn built locally
+or one of the additional snapshot repositories above.
+{% endif %}
+
+
+<a name="source"></a>
+
+## Source Code
+
+Full source is at [github.com/apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn).
+Information on working with the source is [here]({{ site.path.guide }}/dev/code).
+
+Alternatively you can download archives of the source directly:
+
+<a href="https://github.com/apache/incubator-brooklyn/tarball/master"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
+<a href="https://github.com/apache/incubator-brooklyn/zipball/master"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/misc/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/index.md b/docs/guide/misc/index.md
new file mode 100644
index 0000000..1f80f3f
--- /dev/null
+++ b/docs/guide/misc/index.md
@@ -0,0 +1,20 @@
+---
+# BROOKLYN_VERSION_BELOW
+title: Other 0.7.0-SNAPSHOT Resources
+layout: website-normal
+children:
+- { title: Javadoc, path: javadoc/ }
+- download.md
+- release-notes.md
+- known-issues.md
+- { path: ../dev/, title_in_menu: "Developer Guide" }
+- { path: /website/documentation/, title_in_menu: "All Documentation", menu_customization: { force_inactive: true } }
+---
+
+Further documentation specific to this version of Brooklyn includes:
+
+{% for item in page.menu reversed offset:1 reversed %}
+* [{{ item.title_in_menu }}]({{ item.url }})
+{% endfor %}
+
+Also see the [other versions]({{ path.guide }}/meta/versions.html) or [general documentation]({{ path.guide }}/documentation/).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/misc/javadoc/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/javadoc/index.md b/docs/guide/misc/javadoc/index.md
new file mode 100644
index 0000000..c44b6e3
--- /dev/null
+++ b/docs/guide/misc/javadoc/index.md
@@ -0,0 +1,11 @@
+---
+layout: guide-normal
+title: API Reference
+toc: ../../toc.json
+---
+
+*Javadoc is not available as part of this build.*
+
+Please see the [source code]({{site.path.guide}}/dev/code) to view javadoc.
+
+<!-- This page is normally overwritten by generated javadoc. -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/misc/known-issues.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/known-issues.md b/docs/guide/misc/known-issues.md
new file mode 100644
index 0000000..5514b13
--- /dev/null
+++ b/docs/guide/misc/known-issues.md
@@ -0,0 +1,27 @@
+---
+layout: guide-normal
+title: Known Issues
+---
+
+## Unable to Provision certain types of Debian VMs
+
+*Symptom*: Brooklyn fails to provision Debian VMs (e.g. in aws-ec2).
+
+*Cause*: `sudo` is not available on path, causing Brooklyn to fail to confirm that the VM is ssh'able.
+
+*Workaround*: Choose an image that does have sudo (see [wiki.debian.org/Cloud/AmazonEC2Image](http://wiki.debian.org/Cloud/AmazonEC2Image)).
+
+*Fix*: is [Pull #600](https://github.com/brooklyncentral/brooklyn/pull/600); you may also want to run with `brooklyn.location.jclouds.aws-ec2.user=root` if subsequent commands give permission errors.
+
+*Versions Affected*: 0.5.0-M2
+
+
+### Unable to Provision Ubuntu 8 VMs
+
+*Symptom: Brooklyn fails to provision Ubuntu 8 VMs (e.g. in aws-ec2) with the following error 'Cannot insert the iptables rule for port 22. Error: sudo: illegal option `-n''.
+
+*Cause: Ubuntu 8 is too old; the sudo command doesn't support the -n setting.
+
+*Workaround: Choose Ubuntu 10 or higher.
+
+*Versions Affected*: 0.5.0-M2
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/misc/release-notes.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/release-notes.md b/docs/guide/misc/release-notes.md
new file mode 100644
index 0000000..66a443a
--- /dev/null
+++ b/docs/guide/misc/release-notes.md
@@ -0,0 +1,52 @@
+---
+layout: guide-normal
+title: Release Notes
+---
+
+## Version {{ site.brooklyn-version }}
+
+TODO: breacrumbs {{ page.breadcrumb_paths }}.
+
+{% if SNAPSHOT %}
+**You are viewing a SNAPSHOT release (master branch), so this list is incomplete.**
+{% endif %}
+
+* Introduction
+* New Features
+* Backwards Compatibility
+* Community Activity
+
+### Introduction
+
+This version includes many big features,
+incorporating a lot of improvements and feedback from our community. Thank you!
+
+Thanks also go to Brooklyn's commercial users who have funded this development and
+made some major contributions.
+
+For more information, please visit [brooklyn.io](http://brooklyn.io).
+
+
+### New Features
+
+* A huge expansion of what can be done in YAML.
+
+* First-class Chef integration
+
+* New clouds: GCE, Softlayer
+
+* Networking
+
+* Docker support: see [clocker.io](clocker.io)
+
+
+### Backwards Compatibility
+
+* Persistence has been radically overhauled. In most cases the state files from previous versions are compatible,
+ but some items have had to change. For most users this should not be an issue as persistence in the previous version
+ was not working well in any case.
+
+
+### Community Activity
+
+Brooklyn has moved into the Apache Software Foundation.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
new file mode 100644
index 0000000..27da59f
--- /dev/null
+++ b/docs/guide/ops/index.md
@@ -0,0 +1,11 @@
+---
+title: Operations
+layout: website-normal
+children:
+- locations/index.md
+- locations/configuring.md
+- persistence/
+- webconsole/
+---
+
+{% include list-children.html %}
\ No newline at end of file
[03/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/brooklyn.properties
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/brooklyn.properties b/docs/guide/use/guide/quickstart/brooklyn.properties
deleted file mode 100644
index 08bb4a3..0000000
--- a/docs/guide/use/guide/quickstart/brooklyn.properties
+++ /dev/null
@@ -1,324 +0,0 @@
-#
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-#
-# This is Brooklyn's dot-properties file.
-# It should be located at "~/.brooklyn/brooklyn.properties" for automatic loading,
-# or can be specified as a CLI option with --localProperties /path/to/these.properties.
-
-################################## Welcome! ############################################
-
-# It's great to have you here.
-
-# Getting Started options have been pulled to the top. There's a formatting guide at the
-# very bottom.
-
-############################ Getting Started Options ####################################
-
-## GUI Security
-
-## NOTE: in production it is highly recommended to set this, as otherwise it will not require login,
-## not will it be encrypted (though for safety if security is not set it will only bind to loopback)
-
-## Edit the name(s) and passwords as appropriate to your system:
-
-# brooklyn.webconsole.security.users=admin,bob
-# brooklyn.webconsole.security.user.admin.password=password
-# brooklyn.webconsole.security.user.bob.password=bobsword
-
-## If you prefer to run with https (on port 8443 by default), uncomment this:
-
-# brooklyn.webconsole.security.https.required=true
-
-
-# By default we have AWS set up (but with invalid credentials!). Many, many other
-# providers are supported.
-
-## Amazon EC2 Credentials
-# These should be an "Access Key ID" and "Secret Access Key" for your account.
-# This is configured at https://console.aws.amazon.com/iam/home?#security_credential .
-
-brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
-
-# Beware of trailing spaces in your cloud credentials. This will cause unexpected
-# 401: unauthorized responses.
-
-## Using Other Clouds
-# 1. Cast your eyes down this document to find your preferred cloud in the Named Locations
-# section, and the examples.
-# 2. Uncomment the relevant line(s) for your provider.
-# 3. ADD -.identity and -.credential lines for your provider, similar to the AWS ones above,
-# replacing 'aws-ec2' with jcloud's id for your cloud.
-
-
-## Deploying to Localhost
-## see: info on locations at brooklyn.io
-#
-## ~/.ssh/id_rsa is Brooklyn's default location
-# brooklyn.location.localhost.privateKeyFile = ~/.ssh/id_rsa
-## Passphrases are supported, but not required
-# brooklyn.location.localhost.privateKeyPassphrase = s3cr3tpassphrase
-
-## Geoscaling Service - used for the Global Web Fabric demo
-## see: the global web example at brooklyn.io
-## https://www.geoscaling.com/dns2/
-## other services may take similar configuration similarly; or can usually be set in YAML
-# brooklyn.geoscaling.username = USERNAME
-# brooklyn.geoscaling.password = PASSWORD
-# brooklyn.geoscaling.primaryDomain = DOMAIN
-
-
-########################## Getting Started Complete! ###################################
-
-# That's it, although you may want to read through these options...
-
-################################ Brooklyn Options ########################################
-
-## Brooklyn Management Base Directory: specify where management data should be stored on this server;
-## ~/.brooklyn/ is the default but you could use something like /opt/brooklyn/state/
-## (provided this process has write permissions)
-# brooklyn.base.dir=~/.brooklyn/
-
-## Brooklyn On-Box Directory: specify where data should be stored on managed hosts;
-## for most locations a directory off home is the default (but using /tmp/brooklyn-user/ on localhost),
-## however you could specify something like /opt/brooklyn-managed-process/ (creation and permissions are handled)
-# onbox.base.dir=~/brooklyn-managed-process/
-
-## Additional security: Allow all - if you know what you are doing!
-## (Or you can also plug in e.g. LDAP security etc here)
-# brooklyn.webconsole.security.provider = brooklyn.rest.security.provider.AnyoneSecurityProvider
-
-## Optionally disallow deployment to localhost (or any other location)
-# brooklyn.location.localhost.enabled=false
-
-## Scripting Behaviour
-
-## keep scripts around after running them (usually in /tmp)
-# brooklyn.ssh.config.noDeleteAfterExec = true
-
-## Misc Cloud Settings
-## brooklyn will fail a node if the cloud machine doesn't come up, but you can tell it to retry:
-# brooklyn.location.jclouds.machineCreateAttempts = 3
-## many cloud machines don't have sufficient entropy for lots of encrypted networking, so fake it:
-# brooklyn.location.jclouds.installDevUrandom=true
-
-## Sets a minimium ram property for all jclouds locations. Recommended to avoid getting m1.micros on AWS!
-brooklyn.location.jclouds.minRam = 2048
-
-## When setting up a new cloud machine Brooklyn creates a user with the same name as the user running
-## Brooklyn on the management server, but you can force a different user here:
-# brooklyn.location.jclouds.user=brooklyn
-## And you can force a password or key (by default it will use the keys in ~/.ssh/id_rsa{,.pub}
-# brooklyn.location.jclouds.password=s3cr3t
-
-################################ Named Locations ########################################
-
-# Named locations appear in the web console. If using the command line or YAML it may be
-# just as easy to use the jclouds:<provider> locations and specify additional properties there.
-
-## Example: AWS Virginia using Rightscale 6.3 64bit Centos AMI and Large Instances
-# brooklyn.location.named.aws-va-centos-large = jclouds:aws-ec2:us-east-1
-# brooklyn.location.named.aws-va-centos-large.imageId=us-east-1/ami-7d7bfc14
-# brooklyn.location.named.aws-va-centos-large.user=brooklyn
-# brooklyn.location.named.aws-va-centos-large.minRam=4096
-
-## You can also nest these:
-# brooklyn.location.named.aws-acct-two = jclouds:aws-ec2
-# brooklyn.location.named.aws-acct-two.identity = AKA_ACCT_TWO
-# brooklyn.location.named.aws-acct-two.credential = <access-key-hex-digits>
-# brooklyn.location.named.aws-acct-two-singapore = named:aws-acct-two
-# brooklyn.location.named.aws-acct-two-singapore.region = ap-southeast-1
-# brooklyn.location.named.aws-acct-two-singapore.displayName = AWS Singapore (Acct Two)
-
-# For convenience some common defaults:
-brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
-brooklyn.location.named.aws-oregon = jclouds:aws-ec2:us-west-2
-brooklyn.location.named.aws-ireland = jclouds:aws-ec2:eu-west-1
-brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1
-
-## Google Compute
-## Note at present you have to create and download the P12 key from the Google "APIs & auth -> Registered Apps" interface,
-## then convert to PEM private key format using `openssl pkcs12 -in Certificates.p12 -out Certificates.pem -nodes`
-## then embed that on one line as the 'credential, replacing new lines with \n as below
-## (hopefully this will be improved in jclouds in the future)
-# brooklyn.location.jclouds.google-compute-engine.identity=1234567890-somet1mesArand0mU1Dhere@developer.gserviceaccount.com
-# brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN PRIVATE KEY----- \nMIIblahablahblah \nblahblahblah \n-----END PRIVATE KEY-----
-# brooklyn.location.named.Google\ US = jclouds:google-compute-engine
-# brooklyn.location.named.Google\ US.region=us-central1-a
-# brooklyn.location.named.Google\ EU = jclouds:google-compute-engine
-# brooklyn.location.named.Google\ EU.region=europe-west1-a
-## the following flags for GCE are recommended
-## specify the network to use - otherwise it creates new networks each time and you hit quotas pretty quickly
-## you may have to manually create this network AND enable a firewall rule EG tcp:1-65535;udp:1-65535;icmp
-## (fix for this is in progress)
-# brooklyn.location.jclouds.google-compute-engine.networkName=brooklyn-default-network
-## gce images have bad entropy, this ensures they have noisy /dev/random (even if the "randomness" is not quite as random)
-# brooklyn.location.jclouds.google-compute-engine.installDevUrandom=true
-## gce images often start with iptables turned on; turn it off
-# brooklyn.location.jclouds.google-compute-engine.stopIptables=true
-
-## HP Cloud - also Ubuntu 12.04 LTS
-## You specify your HP Credentials like this:
-# brooklyn.location.jclouds.hpcloud-compute.identity = projectname:username
-# brooklyn.location.jclouds.hpcloud-compute.credential = password
-## where username and password are the same as logging in to the web console, and
-## projectname can be found here: https://account.hpcloud.com/projects
-#�brooklyn.location.named.HP\ Cloud\ Arizona-1 = jclouds:hpcloud-compute:az-1.region-a.geo-1
-# brooklyn.location.named.HP\ Cloud\ Arizona-1.imageId = az-1.region-a.geo-1/75845
-# brooklyn.location.named.HP\ Cloud\ Arizona-1.user = ubuntu
-
-## Softlayer - need a key from the gui, under "administrative -> user administration -> api-access
-# brooklyn.location.jclouds.softlayer.identity=username
-# brooklyn.location.jclouds.softlayer.credential=<private-key-hex-digits>
-## locations
-# brooklyn.location.named.Softlayer\ Dallas=jclouds:softlayer:dal05
-# brooklyn.location.named.Softlayer\ Seattle=jclouds:softlayer:sea01
-# brooklyn.location.named.Softlayer\ Washington\ DC=jclouds:softlayer:wdc01
-# brooklyn.location.named.Softlayer\ Singapore\ 1=jclouds:softlayer:sng01
-# brooklyn.location.named.Softlayer\ Amsterdam\ 1=jclouds:softlayer:ams01
-
-
-## Brooklyn uses the jclouds multi-cloud library to access many clouds.
-## http://www.jclouds.org/documentation/reference/supported-providers/
-
-## Templates for many other clouds, but remember to add identity and credentials:
-
-# brooklyn.location.named.Bluelock = jclouds:bluelock-vcloud-zone01
-
-# brooklyn.location.named.CloudSigma\ Nevada = jclouds:cloudsigma-lvs
-# brooklyn.location.named.CloudSigma\ Zurich = jclouds:cloudsigma-zrh
-
-# brooklyn.location.named.ElasticHosts\ London = jclouds:elastichosts-lon-p
-# brooklyn.location.named.ElasticHosts\ Texas = jclouds:elastichosts-sat-p
-
-# brooklyn.location.named.GleSYS = jclouds:glesys
-
-# brooklyn.location.named.Go2Cloud = jclouds:go2cloud-jhb1
-
-# brooklyn.location.named.GoGrid = jclouds:gogrid
-
-# brooklyn.location.named.Green\ House\ Data = jclouds:greenhousedata-element-vcloud
-
-# brooklyn.location.named.Ninefold = jclouds:ninefold-compute
-
-# brooklyn.location.named.OpenHosting = jclouds:openhosting-east1
-
-# brooklyn.location.named.Rackspace\ Chicago\ (ord) = jclouds:rackspace-cloudservers-us:ORD
-# brooklyn.location.named.Rackspace\ Dallas\ (dfw) = jclouds:rackspace-cloudservers-us:DFW
-# brooklyn.location.named.Rackspace\ Hong\ Kong\ (hkg) = jclouds:rackspace-cloudservers-us:HKG
-# brooklyn.location.named.Rackspace\ Northern\ Virginia\ (iad) = jclouds:rackspace-cloudservers-us:IAD
-# brooklyn.location.named.Rackspace\ Sydney\ (syd) = jclouds:rackspace-cloudservers-us:SYD
-## for UK you will need a separate account with rackspace.co.uk
-# brooklyn.location.named.Rackspace\ London\ (lon) = jclouds:rackspace-cloudservers-uk
-
-## if you need to use Rackspace "first gen" API
-## (note the "next gen" api configured above seems to be faster)
-# brooklyn.location.jclouds.cloudservers-us.identity = YOURAPIKEY
-# brooklyn.location.jclouds.cloudservers-us.credential = YOURSECRETKEY
-# brooklyn.location.named.Rackspace\ US\ (First Gen) = jclouds:cloudservers-us
-## and as with next gen, first gen requires a separate acct for the UK:
-# brooklyn.location.jclouds.cloudservers-uk.identity = YOURAPIKEY
-# brooklyn.location.jclouds.cloudservers-uk.credential = YOURSECRETKEY
-# brooklyn.location.named.Rackspace\ UK\ (First Gen) = jclouds:cloudservers-uk
-
-# brooklyn.location.named.SeverLove = jclouds:serverlove-z1-man
-
-# brooklyn.location.named.SkaliCloud = jclouds:skalicloud-sdg-my
-
-# brooklyn.location.named.Stratogen = jclouds:stratogen-vcloud-mycloud
-
-# brooklyn.location.named.TryStack\ (Openstack) = jclouds:trystack-nova
-
-
-## Production pool of machines for my application (deploy to named:On-Prem\ Iron\ Example)
-# brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-# brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
-# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
-# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
-
-## Various Private Clouds
-
-## Example: OpenStack Nova
-
-## openstack identity and credential are random strings of letters and numbers (TBC - still the case?)
-# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:https://9.9.9.9:9999/v2.0/
-
-## OpenStack Nova access information can be downloaded from the openstack web interface; for example, as openrc.sh file
-# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:keystone-url
-# brooklyn.location.named.My\ OpenStack.identity=your-tenant-name:your-user-name
-# brooklyn.location.named.My\ OpenStack.credential=your-password
-# brooklyn.location.named.My\ OpenStack.endpoint=your-keystone-url
-
-## The ID of the image must be configured according to the local OpenStack settings
-## Use the command nova image-list to list all the available images
-## Use the command nova show <image-name> to get more details
-# brooklyn.location.named.My\ OpenStack.imageId=the-region-name/the-image-id
-
-## Virtual Machine flavors must match the ones created upfront according to the local OpenStack settings
-## Use the command nova flavor-list to list all the available options
-## Use the command nova flavor-show <flavor-name> to get more details
-# brooklyn.location.named.My\ OpenStack.hardwareId=the-region-name/the-flavor-id
-
-## (Optional) Configurations
-
-# brooklyn.location.named.My\ OpenStack.user=user-name-inside-the-instance
-
-## The keyPair must by created upfront. Both the following two options are required at the same time.
-# brooklyn.location.named.My\ OpenStack.keyPair=the-key-pair-name
-# brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/keypair.pem
-
-## Security groups must be created upfront (TBC - How to specify many security groups at one ?)
-# brooklyn.location.named.My\ OpenStack.securityGroups=universal
-
-# brooklyn.location.named.My\ OpenStack.openIptables=true
-# brooklyn.location.named.My\ OpenStack.selinux.disabled=true
-# brooklyn.location.named.My\ OpenStack.auto-create-floating-ips=true
-# brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false
-
-## cloudstack identity and credential are rather long random strings of letters and numbers
-## you generate this in the cloudstack gui, under accounts, then "view users", then "generate key"
-## use the "api key" as the identity and "secret key" as the credential
-# brooklyn.location.named.My\ Cloudstack=jclouds:cloudstack:http://9.9.9.9:9999/client/api/
-
-## abiquo identity and credential are your login username/passed
-# brooklyn.location.named.My\ Abiquo=jclouds:abiquo:http://demonstration.abiquo.com/api/
-
-############################### Formatting Guide #######################################
-
-! Both # and ! mark lines as comments
-# The follow syntax are ALL valid.
-# example_key example_value
-# example_key : example_value
-# example_key = example_value
-# example_key=example_value
-
-# The backslash below tells Brooklyn to continue reading the value onto the next line.
-# example_key = A very \
-# long string!
-# Note all white space before 'long...' is ignored. Also '!' is kept as part of the string
-
-
-# Keys with spaces should be escaped with backslashes.
-# This is useful for named locations, as the name displayed in Brooklyn's web
-# interface is derived from the key name.
-# key\ with\ spaces = some\ value
-
-# Encoding for .properties must be ISO-8859-1, aka Latin-1.
-# All non-latin1 characters must be entered using unicode escape characters
-# polish_pangram = P\u00F3jd\u017A\u017Ce, ki\u0144 \
-# t\u0119 chmurno\u015B\u0107 w g\u0142\u0105b flaszy!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/catalog.xml b/docs/guide/use/guide/quickstart/catalog.xml
deleted file mode 100644
index 7a4199e..0000000
--- a/docs/guide/use/guide/quickstart/catalog.xml
+++ /dev/null
@@ -1,23 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<catalog>
- <name>Brooklyn Demos</name>
-
-
- <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB">
- <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB">
- <description>Deploys a demonstration web application to JBoss clusters around the world</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
- </template>
-
- <classpath>
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-M2-incubating&e=jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-M2-incubating&e=jar</entry> <!-- BROOKLYN_VERSION -->
- </classpath>
-
-
-</catalog>
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png b/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
deleted file mode 100644
index b566b1a..0000000
Binary files a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
deleted file mode 100644
index 05e9b0c..0000000
Binary files a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png b/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
deleted file mode 100644
index c13fdd8..0000000
Binary files a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png b/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png
deleted file mode 100644
index ebb6f42..0000000
Binary files a/docs/guide/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/add-application-modal-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/add-application-modal-yaml.png b/docs/guide/use/guide/quickstart/images/add-application-modal-yaml.png
deleted file mode 100644
index c50b7ab..0000000
Binary files a/docs/guide/use/guide/quickstart/images/add-application-modal-yaml.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies-large.png b/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies-large.png
deleted file mode 100644
index 3d84477..0000000
Binary files a/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies.png b/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies.png
deleted file mode 100644
index 2f85328..0000000
Binary files a/docs/guide/use/guide/quickstart/images/jboss7-cluster-policies.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-db-activities-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-db-activities-large.png b/docs/guide/use/guide/quickstart/images/my-db-activities-large.png
deleted file mode 100644
index c214d9e..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-db-activities-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-db-activities.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-db-activities.png b/docs/guide/use/guide/quickstart/images/my-db-activities.png
deleted file mode 100644
index 0f2327c..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-db-activities.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web-cluster-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web-cluster-starting.png b/docs/guide/use/guide/quickstart/images/my-web-cluster-starting.png
deleted file mode 100644
index c389b0b..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web-cluster-starting.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png b/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png
deleted file mode 100644
index c9bdab6..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm.png b/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm.png
deleted file mode 100644
index 179b00a..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web-cluster-stop-confirm.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web-summary-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web-summary-large.png b/docs/guide/use/guide/quickstart/images/my-web-summary-large.png
deleted file mode 100644
index fc4bffe..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web-summary-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web-summary.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web-summary.png b/docs/guide/use/guide/quickstart/images/my-web-summary.png
deleted file mode 100644
index e85752f..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web-summary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/images/my-web.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/images/my-web.png b/docs/guide/use/guide/quickstart/images/my-web.png
deleted file mode 100644
index 2bd6ac3..0000000
Binary files a/docs/guide/use/guide/quickstart/images/my-web.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/index.md b/docs/guide/use/guide/quickstart/index.md
deleted file mode 100644
index 181779f..0000000
--- a/docs/guide/use/guide/quickstart/index.md
+++ /dev/null
@@ -1,221 +0,0 @@
----
-title: Getting Started
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
----
-
-{% include fields.md %}
-
-This guide will walk you through deploying an application to a public cloud.
-
-We will be deploying an example 3-tier web application, described using this blueprint:
-
-{% highlight yaml %}
-{% readj my-web-cluster.yaml %}
-{% endhighlight %}
-
-(This is written in YAML, following the [camp specification](https://www.oasis-open.org/committees/camp/). )
-
-
-## Install Brooklyn
-
-Download the [Brooklyn distribution]({{ this_dist_url_tgz }}) and expand it to your home directory ( `~/` ), or in a location of your choice. (Other [download options]({{site.path.guide}}/start/download.html) are available.)
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
-{% else %}
-Expand the `tar.gz` archive:
-{% endif %}
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-{% highlight bash %}
-$ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-timestamp-dist.tar.gz
-{% endhighlight %}
-{% else %}
-{% highlight bash %}
-$ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
-{% endhighlight %}
-{% endif %}
-
-This will create a `brooklyn-{{ site.brooklyn-version }}` folder.
-
-Note: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers.
-
-## 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.brooklyn-version }}
-$ BROOKLYN_DIR="$(pwd)"
-$ export PATH=$PATH:$BROOKLYN_DIR/bin/
-{% endhighlight %}
-
-We can do a quick test drive by launching Brooklyn:
-
-{% highlight bash %}
-$ brooklyn launch
-{% endhighlight %}
-
-Brooklyn will output the address of the management interface:
-
- INFO Starting brooklyn web-console on loopback interface because no security config is set
- INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []
-
-But before we really use Brooklyn, we need to configure security and locations.
-In particular, if you are running on a remote server, you'll notice that Brooklyn has
-bound only to the loopback device, not a public network interface, and you won't be able
-to access the server. This is for security reasons; you can override by passing `-b 0.0.0.0`,
-or once you have configured security it will automatically bind to all interfaces by default.
-
-Stop Brooklyn with ctrl-c, or in the web-browser (under "Help"), or with `kill`.
-(The PID is written to a file in the directory where you launch.)
-
-
-<a name="properties"></a>
-## Configuring Brooklyn with brooklyn.properties
-
-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;
-this file can be installed with:
-
-{% highlight bash %}
-$ mkdir ~/.brooklyn
-$ cd ~/.brooklyn
-$ wget {{brooklyn_properties_url_live}}
-{% endhighlight %}
-
-Open this file in a text editor and follow the instructions there. The main settings are summarized below:
-
-<a name="security"></a>
-## 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
-
-These settings require a restart to Brooklyn.
-
-
-<a name="location"></a>
-## 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 = <access-key-hex-digits>
- 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 = <private-key-hex-digits>
- 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}}/use/guide/locations/)
-to ensure that your Brooklyn can access your machine.
-
-Once updated, restart Brooklyn (or reload the properties within the web GUI).
-
-
-## Launching an Application in Brooklyn
-
-There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
-
-For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
-
-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.
-
-
-
-
-### Chose your Cloud / Location
-
-Edit the 'location' parameter in the YAML template (repeated below) to use the location you configured.
-
-For example, replace:
-{% highlight yaml %}
-location: location
-{% endhighlight %}
-
-with (one of):
-{% highlight yaml %}
-location: aws-ec2:us-east-1
-location: rackspace-cloudservers-us:ORD
-location: google-compute-engine:europe-west1-a
-location: localhost
-{% endhighlight %}
-
-**My Web Cluster Blueprint**
-
-{% highlight yaml %}
-{% readj my-web-cluster.yaml %}
-{% endhighlight %}
-
-Paste the modified YAML into the dialog and 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.
-
-
-
-
-## Monitoring and Managing Applications
-
-Click on the application name, or open the Applications tab.
-
-We can explore the management hierarchy of the application, which will show us the entities it is composed of.
-
- * My Web Cluster (A `BasicApplication`)
- * My DB (A `MySqlNode`)
- * My Web (A `ControlledDynamicWebAppCluster`)
- * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`)
- * NginxController (An `NginxController`)
-
-
-
-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.
-
-
-
-
-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.
-
-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.
-
-[](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.
-
-[](images/my-web-cluster-stop-confirm-large.png)
-
-
-### 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!
-
-Brooklyn's real power is in using Policies to automatically *manage* applications. There is also the (very useful) ability to store a catalog of application blueprints, ready to go.
-
-[Getting Started - Policies and Catalogs](policies-and-catalogs.html)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/my-web-cluster.yaml b/docs/guide/use/guide/quickstart/my-web-cluster.yaml
deleted file mode 100644
index bbafa00..0000000
--- a/docs/guide/use/guide/quickstart/my-web-cluster.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-name: My Web Cluster
-location: location
-services:
-
-- serviceType: 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.brooklyn-version }}/brooklyn-example-hello-world-sql-webapp-{{ site.brooklyn-version }}.war
- java.sysprops:
- brooklyn.example.db.url: >
- $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"),
- "visitors", "brooklyn", "br00k11n")
-
-- serviceType: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: My DB
- brooklyn.config:
- creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/policies-and-catalogs.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/policies-and-catalogs.md b/docs/guide/use/guide/quickstart/policies-and-catalogs.md
deleted file mode 100644
index 3412333..0000000
--- a/docs/guide/use/guide/quickstart/policies-and-catalogs.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: Getting Started - Policies and Catalogs
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
----
-
-{% include fields.md %}
-
-In the [previous step](index.html) we downloaded Brooklyn and used it to deploy an application to a cloud, but at its heart Brooklyn is a policy driven *management* plane.
-
-Here we will introduce Polices using a simple demo app, which we will load from a Service Catalog.
-
-## Service Catalogs
-
-Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
-
-{% highlight bash %}
-$ cd ~/.brooklyn
-$ wget {{site.url_root}}{{site.path.guide}}/use/guide/quickstart/catalog.xml
-
-$ brooklyn launch
-{% endhighlight %}
-
-Now when we open the web console, two applications are displayed from the catalog.
-
-Select the 'Demo Web Cluster with DB' and click 'Next'.
-
-[](add-application-catalog-web-cluster-with-db-large.png)
-
-Select the Location that Brooklyn should deploy to, and name your application:
-
-[](images/add-application-catalog-web-cluster-with-db-location-large.png)
-
-Click 'Finish' to launch the application as before.
-
-
-### Exploring and Testing Policies
-
-The Demo Web Cluster with DB application is pre-configured with two polices.
-
-The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy.
-
-Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster's Cluster of JBoss7Servers.
-
-You will see that the `AutoScalerPolicy` is running.
-
-[](images/jboss7-cluster-policies-large.png)
-
-
-This policy automatically scales the cluster up or down to be the right size for the cluster's current load. (One server is the minimum size allowed by the policy.)
-
-The loadbalancer's `targets` policy ensures that the loadbalancer is updated as the cluster size changes.
-
-Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint to create load on the cluster. (Download a [jmeter test plan](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).)
-
-As load is added, Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster. As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
-
-### Next
-
-The [Elastic Web Cluster Example]({{site.path.guide}}use/examples/webcluster/index.html) page
-details how to build this demo application from scratch in Java. It shows in more detail how Brooklyn can
-complement your application with policy driven management, and how applications can be
-run from the command line.
-
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/quickstart/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/quickstart/toc.json b/docs/guide/use/guide/quickstart/toc.json
deleted file mode 100644
index eee07d6..0000000
--- a/docs/guide/use/guide/quickstart/toc.json
+++ /dev/null
@@ -1,4 +0,0 @@
-[{ "title": "Download & Deploy",
- "file": "{{ site.path.guide }}/use/guide/quickstart/index.html" },
-{ "title": "Policies & Catalogs",
- "file": "{{ site.path.guide }}/use/guide/quickstart/policies-and-catalogs.html" }]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/toc.json b/docs/guide/use/guide/toc.json
deleted file mode 100644
index 93dc132..0000000
--- a/docs/guide/use/guide/toc.json
+++ /dev/null
@@ -1,25 +0,0 @@
-[
-{ "title": "Quick Start",
- "file": "{{ site.path.guide }}/use/guide/quickstart/index.html",
- "children": {% readj quickstart/toc.json %} },
-{ "title": "Defining Applications",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/basic-concepts.html",
- "children": {% readj defining-applications/toc.json %} },
-{ "title": "Management",
- "file": "{{ site.path.guide }}/use/guide/management/index.html" ,
- "children": {% readj management/toc.json %} },
-{ "title": "Persistence",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html" ,
- "children": {% readj persistence/toc.json %} },
-{ "title": "Locations",
- "file": "{{ site.path.guide }}/use/guide/locations/index.html" },
-{ "title": "Policies",
- "file": "{{ site.path.guide }}/use/guide/policies/index.html",
- "children": {% readj policies/toc.json %} },
-{ "title": "Custom Entities",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html",
- "children": {% readj entities/toc.json %} },
-{ "title": "Extras",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html",
- "children": {% readj extras/toc.json %} }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/index.md b/docs/guide/use/index.md
deleted file mode 100644
index df13613..0000000
--- a/docs/guide/use/index.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-layout: guide-normal
-title: Using Brooklyn
-toc: ../toc.json
----
-
-{% readj /guide/start/docs-summary.include.md %}
-
-Beyond this, [just come chat to us](contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/toc.json b/docs/guide/use/toc.json
deleted file mode 100644
index 3bc76f8..0000000
--- a/docs/guide/use/toc.json
+++ /dev/null
@@ -1,12 +0,0 @@
-[
-{ "title": "User Guide",
- "file": "{{ site.path.guide }}/use/guide/index.html",
- "children": {% readj guide/toc.json %} },
-{ "title": "Examples",
- "file": "{{ site.path.guide }}/use/examples/index.html",
- "children": {% readj examples/toc.json %} },
-{ "title": "API Reference (javadoc)",
- "file": "{{ site.path.guide }}/use/api/index.html" },
-{ "title": "Discuss",
- "file": "{{ site.path.guide }}/use/contact.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png
new file mode 100644
index 0000000..c2b48ba
Binary files /dev/null and b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png
new file mode 100644
index 0000000..78eb5c8
Binary files /dev/null and b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/catalog-maintenance.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/catalog-maintenance.md b/docs/guide/yaml/catalog-maintenance.md
new file mode 100644
index 0000000..edba8e8
--- /dev/null
+++ b/docs/guide/yaml/catalog-maintenance.md
@@ -0,0 +1,115 @@
+---
+title: Catalog Maintenance
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, catalog-maintenance]
+---
+
+In addition to deploying [YAML blueprints](creating-yaml.md) directly through the web console, it is possible
+to add YAML blueprints to the catalog via Brooklyn's REST API.
+
+The catalog is a collection of versioned blueprints, which can be deployed directly or referenced
+by other blueprints. Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section.
+
+For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application
+(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
+If just deploying via the REST API, then this is not necessary.
+
+<!--
+TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
+(and entity UI) or embed the catalog id + version in another YAML
+-->
+
+Let's take the following YAML as a starting point.
+
+{% highlight yaml %}
+location: localhost
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+We will convert it for adding to the catalog, such that it will usable through the
+'Create Application' dialog.
+
+The steps are therefore:
+
+* Add a brooklyn.catalog section to give metadata about the version etc. This is also used
+ when displaying the blueprint in the 'Add Application' dialog.
+* Remove the explicit location (as the user will typically select the location in the GUI).
+* Add a root element that extends `brooklyn.entity.Application`. As we don't require any
+ custom application-specific logic, we can use the `brooklyn.entity.basic.BasicApplication`
+ class. We can then add our MySqlNode as a child of the BasicApplication.
+ (When deploying via YAML at the REST API, this is not necessary as Brooklyn will do this
+ automatically).
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+
+name: MySQL Database
+services:
+- type: brooklyn.entity.basic.BasicApplication
+ brooklyn.children:
+ - type: brooklyn.entity.database.mysql.MySqlNode
+ brooklyn.config:
+ datastore.creation.script.url: classpath://visitors-creation-script.sql
+{% endhighlight %}
+
+<!--
+TODO: Add documentation to explain that the brooklyn.catalog section can contain a libraries array, each item pointing to
+an OSGi bundle where the code for the blueprint is hosted. Every type from the blueprint will be searched for in the
+libraries first and then on the standard Brooklyn classpath.*
+-->
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item. This ID is also passed to
+`UsageManager.UsageListener.onApplicationEvent` for metering purposes.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. These image files should be placed in the
+`conf` folder to make them available at runtime.
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+To add the blueprint to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+This will add the blueprint to the catalog as shown here:
+[](mysql-in-catalog.png)
+
+If you attempt to run the curl command a second time, you will receive an error stating `Updating existing catalog entries is forbidden`.
+To update the blueprint, you will need to change the version number in your yaml file before running the curl command
+again. This will create a second blueprint. You can then delete the old version via the REST API, using its ID and version
+as follows:
+
+{% highlight bash %}
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
+rebinding the catalog item is used to reconstruct the entity.
+
+<!--
+TODO: Add documentation about adding policies to the catalog, and explaining how to add items to
+the UI using the plus icon on the catalog tab*
+
+TODO: describe entity addition (this just covers app addition)
+
+TODO: describe how to use the web-console GUI
+-->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/about-chef.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/about-chef.md b/docs/guide/yaml/chef/about-chef.md
new file mode 100644
index 0000000..66207bc
--- /dev/null
+++ b/docs/guide/yaml/chef/about-chef.md
@@ -0,0 +1,50 @@
+---
+title: About Chef
+title_in_menu: About Chef
+layout: guide-normal
+---
+
+## What you need to know about Chef
+
+Chef works in two different modes, *server* and *solo*. *Server* is where the Chef client talks to a central server
+to retrieve information about its roles, policies and cookbooks (where a cookbook defines how to install and
+configure a particular piece of software). With *solo*, the client works in isolation, therefore its configuration
+and cookbooks must be supplied by another means.
+
+Chef *client* is the Chef agent. This is a Ruby application which is installed on each and every managed host. When
+invoked in server mode, it will contact the Chef server to check for updates to cookbooks and policy; it then "runs"
+the recipes in its run lists, to converge the machine to a known state. In solo mode, it reads the locally-maintained
+cookbooks and policies. The client may be run as a daemon that checks the server regularly, or it could merely be
+run manually when required.
+
+The *policy* is a set of rules on the Chef server. A client starts with a set of *attributes*, which could be as
+simple as its name and a recipe runlist, or which may involve a more complex set of attributes about how it is to be
+configured. The client then augments this with auto-detected metadata - a tool called `ohai` is run that collects
+detailed information about the host. Next, the policy on the server modifies these attributes - overriding some,
+setting defaults for others - to produce a final set of attributes. It is these which are the input to the recipes.
+Finally, the attributes are uploaded to the server where they are stored as metadata for the node, where they can be
+inspected and modified by the system operator.
+
+Also of interest is `knife`, which is the workstation toolkit for Chef. Typically this would be installed on the
+operation engineer's workstation, where it would be used to interact with the Chef server and clients. Of particular
+interest to us is the *bootstrap* operation, which is used for setting up new Chef clients - given a virtual machine,
+it will install the Chef client on it, configure it with enough information to find the Chef server and performs its
+first run, and then kicks off the Chef client for the first time.
+
+There is often a preconception about how a Chef client is bootstrapped; mistakenly, there is the belief that the
+`knife` tool configures the Chef server with information about the client, and the client finds out about itself from
+the server. This is not the case - the bootstrap operation does not involve `knife` talking to the server. Instead,
+`knife` packages up all of the required information and sends it to the client - the client will then introduce
+itself to the server, passing on its configuration.
+
+This diagram summarises the interaction between Brooklyn, the new node, and the various Chef tools. Note that there
+is no interaction between the AMP Server and the Chef Server.
+
+[](Chef.png)
+
+### How Brooklyn interacts with Chef
+
+Brooklyn understands both the *server* and *solo* modes of operation. Server mode utilises the `knife` toolkit, and
+therefore `knife` must be installed onto the AMP server and configured appropriately. Solo mode does not have any
+special requirements; when running in solo mode, Brooklyn will install and configure the Chef client over SSH, just
+like it does most other kinds of entities.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/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
new file mode 100644
index 0000000..9a7cc67
--- /dev/null
+++ b/docs/guide/yaml/chef/advanced-chef-integration.md
@@ -0,0 +1,48 @@
+---
+title: Advanced Chef Integration
+title_in_menu: Advanced Chef Integration
+layout: guide-normal
+---
+
+### Adding Sensors and Effectors
+
+Custom sensors and effectors can be added using an `entity.initializer` section in the YAML blueprint.
+
+One common pattern is to have sensors which extract information from Ohai.
+Another common pattern is to install a monitoring agent as part of the run list,
+configured to talk to a monitoring store, and then to add a sensor feed which reads data from that store.
+
+On the effector side, you can add SSH-based effectors in the usual way.
+You can also describe additional chef converge targets following the pattern set down in
+`ChefLifecycleEffectorTasks`, making use of conveniences in `ChefSoloTasks` and `ChefServerTasks`,
+or provide effectors which invoke network API's of the systems under management
+(for example to supply the common `executeScript` effector as on the standard `MySqlNode`).
+
+
+### Next Steps: Simpifying sensors and effectors, transferring files, and configuring ports
+
+The Brooklyn-Chef integration is work in progress, with a few open issues we'd still like to add.
+Much of the thinking for this is set forth in the [Google document](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8)
+indicated earlier. If you'd like to work with us to implement these, please let us know.
+
+
+## Reference
+
+A general schema for the supported YAML is below:
+
+```
+- type: chef:cookbook_name
+ cookbook_urls:
+ cookbook_name: url://for/cookbook.tgz
+ dependency1: url://for/dependency1.tgz
+ launch_run_list: [ "cookbook_name::start" ]
+ launch_attributes: # map of arguments to set in the chef node
+ service_name: cookbook_service
+ pid_file: /var/run/cookbook.pid
+```
+
+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;
+and then move on to the `DynamicToyMySqlEntiyChef` which starts to look at more sophisticated constructs.
+(Familiarity with BASH and basic Java blueprints may be useful at that stage.)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/chef-call-flow.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/chef-call-flow.png b/docs/guide/yaml/chef/chef-call-flow.png
new file mode 100644
index 0000000..d899de2
Binary files /dev/null and b/docs/guide/yaml/chef/chef-call-flow.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/creating-blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/creating-blueprints.md b/docs/guide/yaml/chef/creating-blueprints.md
new file mode 100644
index 0000000..b97f6d1
--- /dev/null
+++ b/docs/guide/yaml/chef/creating-blueprints.md
@@ -0,0 +1,103 @@
+---
+title: Creating Blueprints from Chef
+title_in_menu: Creating Blueprints from Chef
+layout: guide-normal
+---
+
+In a nutshell, a new Chef-based entity can be defined as a service by specifying
+`chef:cookbook_name` as the `service_type`, along with a collection of optional configuration.
+An illustrative example is below:
+
+{% highlight yaml %}
+{% readj example_yaml/mysql-chef-1.yaml %}
+{% endhighlight %}
+
+*This works without any installation: try it now, copying-and-pasting to the Brooklyn console.
+(Don't forget to add your preferred `location: some-cloud` to the spec.)*
+
+We'll now walk through the important constituent parts,
+and then proceed to describing things which can be done to simplify the deployment.
+
+
+### Cookbook Primary Name
+
+The first thing to note is the type definition:
+
+ - type: chef:mysql
+
+This indicates that the Chef entity should be used (`brooklyn.entity.chef.ChefEntity`)
+to interpret and pass the configuration,
+and that it should be parameterised with a `brooklyn.chef.cookbook.primary.name` of `mysql`.
+This is the cookbook namespace used by default for determining what to install and run.
+
+
+### Importing Cookbooks
+
+Next we specify which cookbooks are required and where they can be pulled from:
+
+ cookbook_urls:
+ mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+ openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+ build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+
+Here, specific versions are being downloaded from the canonical github repository.
+Any URL can be used, so long as it is resolvable on either the target machine or the
+Brooklyn server; this includes `file:` and `classpath:` URLs.
+
+The archive can be ZIP or TAR or TGZ.
+
+The structure of the archive must be that a single folder is off the root,
+and in that folder contains the usual Chef recipe and auxiliary files.
+For example, the archive might contain `mysql-master/recipes/server.rb`.
+Archives such as those above from github match this format.
+The name of that folder does not matter, as often they contain version information.
+When deployed, these will be renamed to match the short name (the key in the `cookbooks_url` map,
+for instance `mysql` or `openssl`).
+
+If Chef server is configured (see below), this section can be omitted.
+
+
+### Launch Run List and Attributes
+
+The next part is to specify the Chef run list and attributes to store when launching the entity:
+
+ launch_run_list:
+ - mysql::server
+
+ launch_attributes:
+ mysql:
+ server_root_password: p4ssw0rd
+ server_repl_password: p4ssw0rd
+ server_debian_password: p4ssw0rd
+
+For the `launch_run_list`, you can use either the YAML `- recipe` syntax or the JSON `[ "recipe" ]` syntax.
+
+The `launch_attributes` key takes a map which will be stored against the `node` object in Chef.
+Thus in this example, the parameter `node['mysql']['server_root_password']` required by the mysql blueprint
+is set as specified.
+
+You can of course set many other attributes in this manner, in addition to those that are required!
+
+
+### Simple Monitoring
+
+The final section determines how Brooklyn confirms that the service is up.
+Sophisticated solutions may install monitoring agents as part of the `launch_run_list`,
+with Brooklyn configured to read monitoring information to confirm the launch was successful.
+However for convenience, two common mechanisms are available out of the box:
+
+ #service_name: mysqld
+ pid_file: /var/run/mysqld/mysqld.pid
+
+If `service_name` is supplied, Brooklyn will check the return code of the `status` command
+run against that service, ensuring it is 0. (Note that this is not universally reliable,
+although it is the same mechanism which Chef typically uses to test status when determining
+whether to start a service. Some services, e.g. postgres, will return 0 even if the service
+is not running.)
+
+If a `pid_file` is supplied, Brooklyn will check whether a process with the PID specified in that
+file is running. This has been selected for mysql because it appears to be more portable:
+the service name varies among OS's: it is `mysqld` on CentOS but `mysql` on Ubuntu!
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml b/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
new file mode 100644
index 0000000..bdac530
--- /dev/null
+++ b/docs/guide/yaml/chef/example_yaml/mysql-chef-1.yaml
@@ -0,0 +1,24 @@
+name: chef-mysql-sample
+services:
+- type: chef:mysql
+
+ cookbook_urls:
+ # only needed for chef solo; URL can be local to brooklyn, or github, etc...
+ mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+ openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+ build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+
+ launch_run_list: [ "mysql::server" ]
+ launch_attributes:
+ mysql:
+ # these attrs are required by the mysql cookbook under node['mysql']
+ server_root_password: p4ssw0rd
+ server_repl_password: p4ssw0rd
+ server_debian_password: p4ssw0rd
+ # many others are attrs are supported by the cookbook and can be passed here...
+
+ # how to determine if the process is running and how to kill it
+ # (supported options are `service_name` and `pid_file`; normally you should just pick one.
+ # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
+ #service_name: mysqld
+ pid_file: /var/run/mysqld/mysqld.pid
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml b/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
new file mode 100644
index 0000000..ced2dbe
--- /dev/null
+++ b/docs/guide/yaml/chef/example_yaml/mysql-chef-2.yaml
@@ -0,0 +1,28 @@
+name: chef-mysql-sample
+services:
+- type: chef:mysql
+ id: db
+
+ cookbook_urls:
+ # only needed for chef solo; URL can be local to brooklyn, or github, etc...
+ mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
+ openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
+ build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
+
+ launch_run_list: [ "mysql::server" ]
+ launch_attributes:
+ mysql:
+ # these attrs are required by the mysql cookbook under node['mysql']
+ server_root_password: $brooklyn:component("db").config("mysql.password")
+ server_repl_password: $brooklyn:component("db").config("mysql.password")
+ server_debian_password: $brooklyn:component("db").config("mysql.password")
+ # many others are attrs are supported by the cookbook and can be passed here...
+
+ # how to determine if the process is running and how to kill it
+ # (supported options are `service_name` and `pid_file`; normally you should just pick one.
+ # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
+ #service_name: mysqld
+ pid_file: /var/run/mysqld/mysqld.pid
+
+brooklyn.config:
+ mysql.password: p4ssw0rd
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/index.md b/docs/guide/yaml/chef/index.md
new file mode 100644
index 0000000..2f47aa3
--- /dev/null
+++ b/docs/guide/yaml/chef/index.md
@@ -0,0 +1,18 @@
+---
+title: Chef in YAML Blueprints
+layout: website-normal
+children:
+- about-chef.md
+- creating-blueprints.md
+- writing-chef.md
+- advanced-chef-integration.md
+---
+
+This guide describes how Brooklyn entities can be easily created from Chef cookbooks.
+As of this writing (May 2014) some of the integration points are under active development,
+and comments are welcome.
+A plan for the full integration is online [here](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8).
+
+This guide assumes you are familiar with the basics of [creating YAML blueprints](creating-yaml.html).
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/chef/writing-chef.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/writing-chef.md b/docs/guide/yaml/chef/writing-chef.md
new file mode 100644
index 0000000..3fa9401
--- /dev/null
+++ b/docs/guide/yaml/chef/writing-chef.md
@@ -0,0 +1,79 @@
+---
+title: Writing Chef for Blueprints
+title_in_menu: Writing Chef for Blueprints
+layout: guide-normal
+---
+
+## Making it Simpler
+
+The example we've just seen shows how existing Chef cookbooks can be
+used as the basis for entities. If you're *writing* the Chef recipes,
+there are a few simple techniques we've established with the Chef community
+which make blueprints literally as simple as:
+
+ - type: chef:mysql
+ brooklyn.config:
+ mysql_password: p4ssw0rd
+ pid_file: /var/run/mysqld/mysqld.pid
+
+
+### Some Basic Conventions
+
+* **A `start` recipe**:
+ The first step is to provide a `start` recipe in `recipes/start.rb`;
+ if no `launch_run_list` is supplied, this is what will be invoked to launch the entity.
+ It can be as simple as a one-line file:
+
+ include_recipe 'mysql::server'
+
+* **Using `brooklyn.config`**:
+ All the `brooklyn.config` is passed to Chef as node attributes in the `node['brooklyn']['config']` namespace.
+ Thus if the required attributes in the mysql recipe are set to take a value set in
+ `node['brooklyn']['config']['mysql_password']`, you can dispense with the `launch_attributes` section.
+
+
+## Using Chef Server
+
+The examples so far have not required Chef Server, so they will work without any external
+Chef dependencies (besides the built-in install from `https://www.opscode.com/chef/install.sh`
+and the explicitly referenced cookbooks). If you use Chef Server, however, you'll want your
+managed nodes to be integrated with it. This is easy to set up, with a few options:
+
+If you have `knife` set up in your shell environment, the Brooklyn Chef support will use it
+by default. If the recipes are installed in your Chef server, you can go ahead and remove
+the `cookbooks_url` section!
+
+Use of `solo` or `knife` can be forced by setting the `chef_mode` flag (`brooklyn.chef.mode` config key)
+to either of those values. (It defaults to `autodetect`, which will use `knife` if it is on the path and satisfies
+sanity checks).
+
+If you want to specify a different configuration, there are a number of config keys you can use:
+
+* `brooklyn.chef.knife.executableFile`: this should be point to the knife binary to use
+* `brooklyn.chef.knife.configFile`: this should point to the knife configuration to use
+* `brooklyn.chef.knife.setupCommands`: an optional set of commands to run prior to invoking knife,
+ for example to run `rvm` to get the right ruby version on the Brooklyn server
+
+If you're interested in seeing the Chef REST API be supported directly (without knife),
+please let us know. We'd like to see this too, and we'll help you along the way!
+
+
+## Tips and Tricks
+
+To help you on your way writing Chef blueprints, here are a handful of pointers
+particularly useful in this context:
+
+* Configuration keys can be inherited from the top-level and accessed using `$brooklyn:component('id').config('key_name')`.
+ An example of this is shown in the `mysql-chef.yaml` sample recipe contained in the Brooklyn code base
+ and [here](example_yaml/mysql-chef-2.yaml) for convenience.
+ Here, `p4ssw0rd` is specified only once and then used for all the attributes required by the stock mysql cookbook.
+
+* Github tarball downloads! You'll have noticed these in the example already, but they are so useful we thought
+ we'd call them out again. Except when you're developing, we recommend using specific tagged versions rather than master.
+
+* The usual machine `provisioning.properties` are supported with Chef blueprints,
+ so you can set things like `minRam` and `osFamily`
+
+* To see more configuration options, and understand the ones presented here in more detail, see the javadoc or
+ the code for the class `ChefConfig` in the Brooklyn code base.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/clusters-and-policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/clusters-and-policies.md b/docs/guide/yaml/clusters-and-policies.md
new file mode 100644
index 0000000..e41115b
--- /dev/null
+++ b/docs/guide/yaml/clusters-and-policies.md
@@ -0,0 +1,42 @@
+---
+title: Clusters and Policies
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Now let's bring the concept of the "cluster" back in.
+We could wrap our appserver in the same `DynamicCluster` we used earlier,
+although then we'd need to define and configure the load balancer.
+But another blueprint, the `ControlledDynamicWebAppCluster`, does this for us.
+It takes the same `memberSpec`, so we can build a fully functional elastic 3-tier
+deployment of our `hello-world-sql` application as follows:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-clustered-w-db.yaml %}
+{% endhighlight %}
+
+This sets up Nginx as the controller by default, but that can be configured
+using the `controllerSpec` key. In fact, JBoss is the default appserver,
+and because configuration in Brooklyn is inherited by default,
+the same blueprint can be expressed more concisely as:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-clustered-w-db-concise.yaml %}
+{% endhighlight %}
+
+The other nicety supplied by the `ControlledDynamicWebAppCluster` blueprint is that
+it aggregates sensors from the appserver, so we have access to things like
+`webapp.reqs.perSec.windowed.perNode`.
+These are convenient for plugging in to policies!
+We can set up our blueprint to do autoscaling based on requests per second
+(keeping it in the range 10..100, with a maximum of 5 appserver nodes)
+as follows:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-policy.yaml %}
+{% endhighlight %}
+
+Use your favorite load-generation tool (`jmeter` is one good example) to send a huge
+volume of requests against the server and see the policies kick in to resize it.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/clusters.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/clusters.md b/docs/guide/yaml/clusters.md
new file mode 100644
index 0000000..fc519a2
--- /dev/null
+++ b/docs/guide/yaml/clusters.md
@@ -0,0 +1,34 @@
+---
+title: Clusters, Specs, and Composition
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+What if you want multiple machines?
+
+One way is just to repeat the `- type: brooklyn.entity.basic.EmptySoftwareProcess` block,
+but there's another way which will keep your powder [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself):
+
+{% highlight yaml %}
+{% readj example_yaml/cluster-vm.yaml %}
+{% endhighlight %}
+
+Here we've composed the previous blueprint introducing some new important concepts, the `DynamicCluster`
+the `$brooklyn` DSL, and the "entity-spec". Let's unpack these.
+
+The `DynamicCluster` creates a set of homogeneous instances.
+At design-time, you specify an initial size and the specification for the entity it should create.
+At runtime you can restart and stop these instances as a group (on the `DynamicCluster`) or refer to them
+individually. You can resize the cluster, attach enrichers which aggregate sensors across the cluster,
+and attach policies which, for example, replace failed members or resize the cluster dynamically.
+
+The specification is defined in the `memberSpec` key. As you can see it looks very much like the
+previous blueprint, with one extra line. Entries in the blueprint which start with `$brooklyn:`
+refer to the Brooklyn DSL and allow a small amount of logic to be embedded
+(if there's a lot of logic, it's recommended to write a blueprint YAML plugin or write the blueprint itself
+as a plugin, in Java or a JVM-supported language).
+
+In this case we want to indicate that the parameter to `memberSpec` is an entity specification
+(`EntitySpec` in the underlying type system); the `entitySpec` DSL command will do this for us.
+The example above thus gives us 5 VMs identical to the one we created in the previous section.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/configuring-vms.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/configuring-vms.md b/docs/guide/yaml/configuring-vms.md
new file mode 100644
index 0000000..db08f0b
--- /dev/null
+++ b/docs/guide/yaml/configuring-vms.md
@@ -0,0 +1,31 @@
+---
+title: Configuring VMs
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Another simple blueprint will just create a VM which you can use, without any software installed upon it:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-vm.yaml %}
+{% endhighlight %}
+
+
+*We've omitted the `location` section here and in many of the examples below;
+add the appropriate choice when you paste your YAML. Note that the `provisioning.properties` will be
+ignored if deploying to `localhost` or `byon` fixed-IP machines.*
+
+This will create a VM with the specified parameters in your choice of cloud.
+In the GUI (and in the REST API), the entity is called "VM",
+and the hostname and IP address(es) are reported as [sensors]({{ site.path.guide }}/use/guide/defining-applications/basic-concepts.html).
+There are many more `provisioning.properties` supported here,
+including:
+
+* a `user` to create (if not specified it creates the same username as `brooklyn` is running under)
+* a `password` for him or a `publicKeyFile` and `privateKeyFile` (defaulting to keys in `~/.ssh/id_rsa{.pub,}` and no password,
+ so if you have keys set up you can immediately ssh in!)
+* `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!)
+* and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp` for private clouds)
+
+For more information, see the javadoc on `JcloudsLocationConfig`.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/creating-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/creating-yaml.md b/docs/guide/yaml/creating-yaml.md
new file mode 100644
index 0000000..8b1b593
--- /dev/null
+++ b/docs/guide/yaml/creating-yaml.md
@@ -0,0 +1,75 @@
+---
+title: The Basic Structure
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+## A First Blueprint
+
+The easiest way to write a blueprint is as a YAML file.
+This follows the <a href="https://www.oasis-open.org/committees/camp/">OASIS CAMP</a> plan specification,
+with some extensions described below.
+(A [YAML reference](yaml-reference.html) has more information,
+and if the YAML doesn't yet do what you want,
+it's easy to add new extensions using your favorite JVM language.)
+
+### The Basic Structure
+
+Here's a very simple YAML blueprint plan, to explain the structure:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver.yaml %}
+{% endhighlight %}
+
+* The `name` is just for the benefit of us humans.
+
+* The `location` specifies where this should be deployed.
+ If you've [set up passwordless localhost SSH access]({{ site.path.guide }}/use/guide/locations/)
+ you can use `localhost` as above, but if not, just wait ten seconds for the next example.
+
+* The `services` block takes a list of the typed services we want to deploy.
+ This is the meat of the blueprint plan, as you'll see below.
+
+Finally, that clipboard in the corner lets you easily copy-and-paste into the web-console:
+simply [download and launch]({{ site.path.guide }}/use/guide/quickstart/) Brooklyn,
+then in the "Add Application" dialog at the web console
+(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/).
+There are several other ways to deploy, including `curl` and via the command-line,
+and you can configure https and security, and much more, as described [here](deploying-yaml.html).
+
+[](web-console-yaml.png)
+
+
+
+<!--
+TODO building up children entities
+
+-->
+
+<!--
+
+### Using Chef Recipes
+
+TODO
+
+-->
+
+
+### More Information
+
+Plenty of examples of blueprints exist in the Brooklyn codebase,
+so a good starting point is to [`git clone`]({{ site.path.guide }}/dev/code/index.html) it
+and search for `*.yaml` files therein.
+
+Brooklyn lived as a Java framework for many years before we felt confident
+to make a declarative front-end, so you can do pretty much anything you want to
+by dropping to the JVM. Information on that is available:
+* in the [user guide]({{site.path.guide}}/use/guide/entities/index.html),
+* through a [Maven archetype]({{site.path.guide}}/use/guide/defining-applications/archetype.html),
+* in the [codebase](https://github.com/apache/incubator-brooklyn),
+* and in plenty of [examples]({{site.path.guide}}/use/examples/index.html).
+
+You can also come talk to us, on IRC (#brooklyncentral on Freenode) or
+any of the usual [hailing frequencies]({{site.path.guide}}/meta/contact.html),
+as these documents are a work in progress.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/custom-entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/custom-entities.md b/docs/guide/yaml/custom-entities.md
new file mode 100644
index 0000000..8e9638d
--- /dev/null
+++ b/docs/guide/yaml/custom-entities.md
@@ -0,0 +1,107 @@
+---
+title: Custom Entities
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+So far we've covered how to configure and compose entities.
+There's a large library of blueprints available, but
+there are also times when you'll want to write your own.
+
+For complex use cases, you can write JVM, but for many common situations,
+some of the highly-configurable blueprints make it easy to write in YAML,
+including `bash` and Chef.
+
+
+### Vanilla Software using `bash`
+
+The following blueprint shows how a simple script can be embedded in the YAML
+(the `|` character is special YAML which makes it easier to insert multi-line text):
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat.yaml %}
+{% endhighlight %}
+
+This starts a simple `nc` listener on port 4321 which will respond `hello` to the first
+session which connects to it. Test it by running `telnet localhost 4321`.
+
+This is just a simple script, but it shows how any script can be easily embedded here,
+including a script to download and run other artifacts.
+Many artifacts are already packaged such that they can be downloaded and launched
+with a simple script, and `VanillaSoftwareProcess` can also be used for them.
+We can specify a `download.url` which downloads artifacts (unpacking TAR, TGZ, and ZIP archives)
+before running `launch.command` relative to where that file is installed (or unpacked),
+with `./start.sh` being the default `launch.command`.
+
+So if we create a file `/tmp/netcat-server.tgz` containing just `start.sh` in the root
+which consists of the two lines in the previous example,
+we can instead write our example as:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-file.yaml %}
+{% endhighlight %}
+
+The one requirement of the script is that it store the process ID (PID) in the file
+pointed to by `$PID_FILE`, hence the second line of the script.
+This is because Brooklyn wants to monitor the services under management.
+(There are other options; you can set `checkRunning.command` and `stop.command` instead,
+as documented on the Javadoc of the `VanillaSoftwareProcess` class,
+and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`.)
+
+And indeed, once you've run one `telnet` to the server, you'll see that the
+service has gone "on fire" in Brooklyn -- because the `nc` process has stopped.
+Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate
+action. A simple recovery here might just be to restart the process:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-restarter.yaml %}
+{% endhighlight %}
+
+Autonomic management in Brooklyn often follows the principle that complex behaviours emerge
+from composing simple policies.
+The blueprint above uses one policy to triggering a failure sensor when the service is down,
+and another responds to such failures by restarting the service.
+This makes it easy to configure various aspects, such as to delay to see if the service itself recovers
+(which here we've set to 15 seconds) or to bail out on multiple failures within a time window (which again we are not doing).
+Running with this blueprint, you'll see that the service shows as on fire for 15s after a `telnet`,
+before the policy restarts it.
+
+For an even more interesting way to test it, look at the blueprint defining
+[a netcat server and client](example_yaml/vanilla-bash-netcat-w-client.yaml).
+This uses `initializers` to define an effector to `sayHiNetcat` on the `Simple Pinger` client,
+using `env` variables to inject the `netcat-server` location and
+`parameters` to pass in per-effector data:
+
+ env:
+ TARGET_HOSTNAME: $brooklyn:component("netcat-server").attributeWhenReady("host.name")
+ brooklyn.initializers:
+ - type: brooklyn.entity.software.ssh.SshCommandEffector
+ brooklyn.config:
+ name: sayHiNetcat
+ description: Echo a small hello string to the netcat entity
+ command: |
+ echo $message | nc $TARGET_HOSTNAME 4321
+ parameters:
+ message:
+ description: The string to pass to netcat
+ defaultValue: hi netcat
+
+This blueprint also uses initializers to define sensors on the `netcat-server` entity
+so that the `$message` we passed above gets logged and reported back:
+
+ launch.command: |
+ echo hello | nc -l 4321 >> server-input &
+ echo $! > $PID_FILE
+ brooklyn.initializers:
+ - type: brooklyn.entity.software.ssh.SshCommandSensor
+ brooklyn.config:
+ name: output.last
+ command: tail -1 server-input
+
+This is still a simple example, but worth going through carefully.
+It shows many of the building blocks used in real-world blueprints,
+and how they can often be easily described and combined in Brooklyn YAML blueprints.
+Next, if you need to drive off-piste, or you want to write tests against these blueprints,
+have a look at, for example, `VanillaBashNetcatYamlTest.java` in the Brooklyn codebase,
+or follow the other references below.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-clustered-w-db-concise.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-clustered-w-db-concise.yaml b/docs/guide/yaml/example_yaml/appserver-clustered-w-db-concise.yaml
new file mode 100644
index 0000000..518f65a
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-clustered-w-db-concise.yaml
@@ -0,0 +1,15 @@
+name: appserver-clustered-w-db-concise
+services:
+- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ initialSize: 2
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: DB HelloWorld Visitors
+ brooklyn.config:
+ datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-clustered-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-clustered-w-db.yaml b/docs/guide/yaml/example_yaml/appserver-clustered-w-db.yaml
new file mode 100644
index 0000000..10592d8
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-clustered-w-db.yaml
@@ -0,0 +1,18 @@
+name: appserver-clustered-w-db
+services:
+- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ initialSize: 2
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: brooklyn.entity.webapp.jboss.JBoss7Server
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: DB HelloWorld Visitors
+ brooklyn.config:
+ datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-configured-in-config.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-configured-in-config.yaml b/docs/guide/yaml/example_yaml/appserver-configured-in-config.yaml
new file mode 100644
index 0000000..50c1873
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-configured-in-config.yaml
@@ -0,0 +1,6 @@
+name: appserver-configured-in-config
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080
[04/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml b/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml
deleted file mode 100644
index 50051db..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-name: Simple Netcat with Client
-
-location: localhost
-
-services:
-
-# the netcat server instance, running in listener mode (-l)
-- type: brooklyn.entity.basic.VanillaSoftwareProcess
- id: netcat-server
- name: Simple Netcat Server
- launch.command: |
- echo hello | nc -l 4321 >> server-input &
- echo $! > $PID_FILE
-
- brooklyn.policies:
- # restarter and
- - policyType: brooklyn.policy.ha.ServiceFailureDetector
- brooklyn.config:
- # wait 15s after service fails before propagating failure
- serviceFailedStabilizationDelay: 15s
- - policyType: brooklyn.policy.ha.ServiceRestarter
- brooklyn.config:
- # repeated failures in a time window can cause the restarter to abort,
- # propagating the failure; a time window of 0 will mean it always restarts!
- failOnRecurringFailuresInThisDuration: 0
-
- brooklyn.initializers:
- # two sensors, recording the data sent to this netcat server:
-
- - type: brooklyn.entity.software.ssh.SshCommandSensor
- brooklyn.config:
- name: output.last
- command: tail -1 server-input
-
- - type: brooklyn.entity.software.ssh.SshCommandSensor
- brooklyn.config:
- name: output.all
- command: cat server-input
-
-# a client to hit netcat
-- type: brooklyn.entity.basic.VanillaSoftwareProcess
- name: Simple Pinger
-
- # set the hostname of the netcat instance as an env var for the scripts
- env:
- TARGET_HOSTNAME: $brooklyn:component("netcat-server").attributeWhenReady("host.name")
-
- # start/check/stop are no-op
- launch.command: ""
- checkRunning.command: ""
- stop.command: ""
-
- brooklyn.initializers:
- # but there is a sample effector which runs nc in client mode
-
- - type: brooklyn.entity.software.ssh.SshCommandEffector
- brooklyn.config:
- name: sayHiNetcat
- description: Echo a small hello string to the netcat entity
- command: |
- echo $message | nc $TARGET_HOSTNAME 4321
- parameters:
- message:
- description: The string to pass to netcat
- defaultValue: hi netcat
-
-# and add an enricher at the root so all sensors from netcat-server are visible on the root
-brooklyn.enrichers:
-- enricherType: brooklyn.enricher.basic.Propagator
- brooklyn.config:
- enricher.producer: $brooklyn:component("netcat-server")
- enricher.propagating.propagatingAll: true
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat.yaml b/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat.yaml
deleted file mode 100644
index d4cb37b..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-name: Simple Netcat Server Example
-location: localhost
-services:
-- type: brooklyn.entity.basic.VanillaSoftwareProcess
- name: Simple Netcat Server
- launch.command: |
- echo hello | nc -l 4321 &
- echo $! > $PID_FILE
-
- # The following overrides demonstrate the use of a custom shell environment as well as
- # check-running and stop commands. These are optional; default behavior will "do the
- # right thing" with the pid file automatically.
-
- env: { CHECK_MARKER: "checkRunning", STOP_MARKER: "stop" }
- checkRunning.command: echo $CHECK_MARKER >> DATE && test -f "$PID_FILE" && ps -p `cat $PID_FILE` >/dev/null
- stop.command: echo $STOP_MARKER >> DATE && test -f "$PID_FILE" && { kill -9 `cat $PID_FILE`; rm /tmp/vanilla.pid; }
-
-# can also define download.url, in which case the launch command defaults to ./start.sh in that (archive) file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/examples.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/examples.md b/docs/guide/use/guide/defining-applications/examples.md
deleted file mode 100644
index 851d12b..0000000
--- a/docs/guide/use/guide/defining-applications/examples.md
+++ /dev/null
@@ -1,121 +0,0 @@
----
-title: Examples
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-** TODO: this examples page is deprecated;
-code is out-of-date, and better examples are described on the web site.
-need to figure out if this page should be kept at all
-(indeed if the "guide" is even still relevant)**
-
-
-### Integrating with a Maven project
-
-If you have a Maven-based project, integrate this XML fragment with your pom.xml:
-
-<!-- TODO this should import from the downloads page -->
-
-{% highlight xml %}
-<dependencies>
- <dependency>
- <groupId>io.brooklyn</groupId>
- <artifactId>brooklyn-all</artifactId>
- <version>0.7.0-M2-incubating</version> <!-- BROOKLYN_VERSION -->
- </dependency>
-</dependencies>
-
-<repository>
- <id>cloudsoft-releases</id>
- <url>http://developers.cloudsoftcorp.com/download/maven2/</url>
-</repository>
-<repository>
- <id>libs-snapshot-local</id>
- <url>http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/</url>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- <checksumPolicy>fail</checksumPolicy>
- </snapshots>
-</repository>
-{% endhighlight %}
-
-
-### Starting a Tomcat Server
-
-The code below starts a Tomcat server on the local machine.
-
-The ``main`` method defines the application, and passes it to the ``BrooklynLauncher`` to be managed.
-It is then started in a localhost location (other locations are shown in the next section).
-
-The Tomcat's configuration indicates that the given WAR should be deployed to the Tomcat server when it is started.
-
-{% highlight java %}
-{% readj example_files/tomcat_simple.java %}
-{% endhighlight %}
-
-The ``wars`` config is also supported (with config keys ``ROOT_WAR`` and ``NAMED_WARS`` the long-hand syntax);
-they accept EARs and other common archives, and can be described as files or as URLs (as Strings),
-with URLs supporting an optional ``classpath://org/acme/resources/xxx.war`` syntax.
-
-
-### Starting Tomcat in Amazon EC2
-
-To start a tomcat node or cluster in Amazon EC2, the application is identical to that for localhost.
-The only difference is the location supplied.
-
-The Brooklyn CLI can be used to launch the application in your choice of location, such as:
-
-{% highlight bash %}
-brooklyn launch --app TomcatServerApp --location localhost
-brooklyn launch --app TomcatServerApp --location aws-ec2:eu-west-1
-{% endhighlight %}
-
-
-### Starting a Tomcat Cluster with Nginx
-
-The code below starts a Tomcat cluster along with an Nginx instance, where each Tomcat server in the cluster is registered with the Nginx instance.
-
-{% highlight java %}
-{% readj example_files/tomcat_nginx.java %}
-{% endhighlight %}
-
-This creates a cluster that of Tomcat servers, along with an Nginx instance. The ``NginxController`` instance
-is notified whenever a member of the cluster joins or leaves; the entity is configured to look at the ``HTTP_PORT``
-attribute of that instance so that the Nginx configuration can be updated with the ip:port of the cluster member.
-
-<!---
-TODO things may need tidying (paragraphs, and/or eliminating any extra setConfig calls, though looks like these have gone)
--->
-
-
-Starting a Multi-location Tomcat Fabric
----------------------------------------
-
-<!---
-TODO this example should use several cloud providers, including Openshift, and use GeoDNS,
-and maybe a data store and/or messaging service; it is the last "most advanced" example
--->
-
-<!---
-FIXME Discuss above comment with Aled/Alex as it is contentious
--->
-
-The ``ControlledDynamicWebAppCluster`` entity used above can also be used with a DynamicFabric to start
-a web-cluster in each location.
-
-{% highlight java %}
-{% readj example_files/tomcat_multi-location.java %}
-{% endhighlight %}
-
-
-Examples Source
----------------
-
-Source code for (more up-to-date!) examples is available for download from GitHub. To retrieve the source, execute the following command:
-
- git clone git@github.com:apache/incubator-brooklyn.git
- cd incubator-brooklyn/examples
-
-You can also [browse the code](https://github.com/apache/incubator-brooklyn/tree/examples) on the web.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/service-state.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/service-state.md b/docs/guide/use/guide/defining-applications/service-state.md
deleted file mode 100644
index 32212bc..0000000
--- a/docs/guide/use/guide/defining-applications/service-state.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: Service State
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-Any entity can use the standard "service-up" and "service-state"
-sensors to inform other entities and the GUI about its status.
-
-In normal operation, entities should publish at least one "service not-up indicator",
-using the `ServiceNotUpLogic.updateNotUpIndicator` method. Each such indicator should have
-a unique name or input sensor. `Attributes.SERVICE_UP` will then be updated automatically
-when there are no not-up indicators.
-
-When there are transient problems that can be detected, to trigger `ON_FIRE` status
-entity code can similarly set `ServiceProblemsLogic.updateProblemsIndicator` with a unique namespace,
-and subsequently clear it when the problem goes away.
-These problems are reflected at runtime in the `SERVICE_PROBLEMS` sensor,
-allowing multiple problems to be tracked independently.
-
-When an entity is changing the expected state, e.g. starting or stopping,
-the expected state can be set using `ServiceStateLogic.setExpectedState`;
-this expected lifecycle state is considered together with `SERVICE_UP` and `SERVICE_PROBLEMS`
-to compute the actual state. By default the logic in `ComputeServiceState` is applied.
-
-For common entities, good out-of-the-box logic is applied, as follows:
-
-* For `SoftwareProcess` entities, lifecycle service state is updated by the framework
- and a service not-up indicator is linked to the driver `isRunning()` check.
-
-* For common parents, including `AbstractApplication` and `AbstractGroup` subclasses (including clusters, fabrics, etc),
- the default enrichers analyse children and members to set a not-up indicator
- (requiring at least one child or member who is up) and a problem indicator
- (if any children or members are on-fire).
- In some cases other quorum checks are preferable; this can be set e.g. by overriding
- the `UP_QUORUM_CHECK` or the `RUNNING_QUORUM_CHECK`, as follows:
-
- public static final ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(AbstractGroup.UP_QUORUM_CHECK,
- "Require all children and members to be up for this node to be up",
- QuorumChecks.all());
-
- Alternatively the `initEnrichers()` method can be overridden to specify a custom-configured
- enricher or set custom config key values (as done e.g. in `DynamicClusterImpl` so that
- zero children is permitted provided when the initial size is configured to be 0).
-
-
-For sample code to set and more information on these methods' behaviours,
-see javadoc in `ServiceStateLogic`,
-overrides of `AbstractEntity.initEnrichers()`
-and tests in `ServiceStateLogicTests`.
-
-<!-- TODO include more documentation, sample code (ideally extracted on the fly from test cases so we know it works!) -->
-
-
-## Notes on Advanced Use
-
-The enricher to derive `SERVICE_UP` and `SERVICE_STATE_ACTUAL` from the maps and expected state values discussed above
-is added by the `AbstractEntity.initEnrichers()` method.
-This method can be overridden -- or excluded altogether by by overriding `init()` --
-and can add enrichers created using the `ServiceStateLogic.newEnricherFromChildren()` method
-suitably customized using methods on the returned spec object, for instance to look only at members
-or specify a quorum function (from `QuorumChecks`).
-If different logic is required for computing `SERVICE_UP` and `SERVICE_STATE_ACTUAL`,
-use `ServiceStateLogic.newEnricherFromChildrenState()` and `ServiceStateLogic.newEnricherFromChildrenUp()`,
-noting that the first of these will replace the enricher added by the default `initEnrichers()`,
-whereas the second one runs with a different namespace (unique tag).
-For more information consult the javadoc on those classes.
-
-Entities can set `SERVICE_UP` and `SERVICE_STATE_ACTUAL` directly.
-Provided these entities never use the `SERVICE_NOT_UP_INDICATORS` and `SERVICE_PROBLEMS` map,
-the default enrichers will not override these values.
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/toc.json b/docs/guide/use/guide/defining-applications/toc.json
deleted file mode 100644
index b4eeeef..0000000
--- a/docs/guide/use/guide/defining-applications/toc.json
+++ /dev/null
@@ -1,19 +0,0 @@
-[{ "title": "Basic Concepts",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/basic-concepts.html" },
-{ "title": "Advanced Concepts",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/advanced-concepts.html" },
-{ "title": "Common Usage",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/common-usage.html" },
-{ "title": "YAML Blueprints",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/creating-yaml.html" },
-{ "title": "Chef Blueprints",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/chef-blueprints.html" },
-{ "title": "Deploying YAML",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/deploying-yaml.html" },
-{ "title": "YAML Reference",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/yaml-reference.html" },
-{ "title": "Service State",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/service-state.html" },
-{ "title": "Maven Archetype",
- "file": "{{ site.path.guide }}/use/guide/defining-applications/archetype.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/web-console-yaml-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/web-console-yaml-700.png b/docs/guide/use/guide/defining-applications/web-console-yaml-700.png
deleted file mode 100644
index d6a2249..0000000
Binary files a/docs/guide/use/guide/defining-applications/web-console-yaml-700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/web-console-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/web-console-yaml.png b/docs/guide/use/guide/defining-applications/web-console-yaml.png
deleted file mode 100644
index 3d65a99..0000000
Binary files a/docs/guide/use/guide/defining-applications/web-console-yaml.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/yaml-reference.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/yaml-reference.md b/docs/guide/use/guide/defining-applications/yaml-reference.md
deleted file mode 100644
index df19dd3..0000000
--- a/docs/guide/use/guide/defining-applications/yaml-reference.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-title: Broooklyn YAML Blueprint Reference
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-## Root Elements
-
-* `name`: human readable names
-* `services`: a list of `ServiceSpecification` elements
-* `location` (or `locations` taking a list): a `LocationSpecification` element as a string or a map
-
-
-## `ServiceSpecification` Elements
-
-Within the `services` block, a list of maps should be supplied, with each map
-defining a `ServiceSpecification`. Each `ServiceSpecification` should declare the
-service `type` (synonyms `serviceType` and `service_type`), indicating what type of
-service is being specified there. The following formats are supported for
-defining types:
-
-* `io.brooklyn.package.JavaEntityClass`
-* `java:io.brooklyn.package.JavaEntityClass`
-* *OSGi and YAML references are coming soon!* <!-- TODO -->
-
-A reference of some of the common service `type` instances used is included in a section below.
-
-Within the `ServiceSpecification`, other key-value pairs can be supplied to customize
-the entity being defined, with these being the most common:
-
-* `id`: an ID string, used to refer to this service
-
-* `location` (or `locations`): as defined in the root element
-
-* `brooklyn.config`: configuration key-value pairs passed to the service entity being created
-
-* `brooklyn.children`: a list of `ServiceSpecifications` which will be configured as children of this entity
-
-* `brooklyn.policies`: a list of policies, each as a map described with their `type` and their `brooklyn.config` as keys
-
-* `brooklyn.enrichers`: a list of enrichers, each as a map described with their `type` and their `brooklyn.config` as keys
-
-* `brooklyn.initializers`: a list of `EntityInitializer` instances to be constructed and run against the entity,
- each as a map described with their `type` and their `brooklyn.config` as keys.
- An `EntityInitiailzer` can perform arbitrary customization to an entity whilst it is being constructed,
- such as adding dynamic sensors and effectors. These classes must expose a public constructor taking
- a single `Map` where the `brooklyn.config` is passed in.
- Some common initializers are:
-
- * `brooklyn.entity.software.ssh.SshCommandEffector`: takes a `name` and `command`,
- and optionally a map of named `parameters` to their `description` and `defaultValue`,
- to define an effector with the given name implemented by the given SSH command
- (on an entity which as an ssh-able machine)
-
- * `brooklyn.entity.software.ssh.SshCommandSensor`: takes a `name` and `command`,
- and optionally a `period`, to create a sensor feed which populates the sensor with
- the given name by running the given command (on an entity which as an ssh-able machine)
-
-Entities, policies, and initializers may accept additional key-value pairs,
-usually documented in their documentation (e.g. javadoc), or in the case of Java
-often as static fields in the underlying Java class.
-Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
-these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
-(Undeclared config is only accepted in the `brooklyn.config` map.)
-
-
-## `LocationSpecification` Elements
-
-<!-- TODO - expand this, currently it's concise notes -->
-
-In brief, location specs are supplied as follows, either for the entire application (at the root)
-or for a specific `ServiceSpecification`:
-
- location:
- jclouds:aws-ec2:
- region: us-east-1
- identity: AKA_YOUR_ACCESS_KEY_ID
- credential: <access-key-hex-digits>
-
-Or in many cases it can be in-lined:
-
- location: localhost
- location: named:my_openstack
- location: aws-ec2:us-west-1
-
-For the first immediately, you'll need password-less ssh access to localhost.
-For the second, you'll need to define a named location in `brooklyn.properties`,
-using `brooklyn.location.named.my_openstack....` properties.
-For the third, you'll need to have the identity and credentials defined in
-`brooklyn.properties`, using `brooklyn.location.jclouds.aws-ec2....` properties.
-
-If specifying multiple locations, e.g. for a fabric:
-
- locations:
- - localhost
- - named:my_openstack
- - aws-ec2:us-east-2 # if credentials defined in `brooklyn.properties
- - jclouds:aws-ec2:
- region: us-east-1
- identity: AKA_YOUR_ACCESS_KEY_ID
- credential: <access-key-hex-digits>
-
-If you have pre-existing nodes, you can use the `byon` provider, either in this format:
-
- location:
- byon:
- user: root
- privateKeyFile: ~/.ssh/key.pem
- hosts:
- - 81.95.144.58
- - 81.95.144.59
- - brooklyn@159.253.144.139
- - brooklyn@159.253.144.140
-
-or:
-
- location:
- byon:
- user: root
- privateKeyFile: ~/.ssh/key.pem
- hosts: "{81.95.144.{58,59},brooklyn@159.253.144.{139-140}"
-
-You cannot use glob expansions with the list notation, nor can you specify per-host
-information apart from user within a single `byon` declaration.
-However you can combine locations using `multi`:
-
- location:
- multi:
- targets:
- - byon:
- user: root
- privateKeyFile: ~/.ssh/key.pem
- hosts:
- - 81.95.144.58
- - 81.95.144.59
- - byon:
- privateKeyFile: ~/.ssh/brooklyn_key.pem
- hosts: brooklyn@159.253.144{139-140}
-
-
-## DSL Commands
-
-Dependency injection other powerful references and types can be built up within the YAML using the
-concise DSL defined here:
-
-* `$brooklyn:component("ID")` refers to a Brooklyn component with the given ID; you can then access the following subfields:
- * `.attributeWhenReady("sensor")` will store a future which will be blocked when it is accessed,
- until the given `sensor` from the component `ID` has a "truthy" (i.e. non-trivial, non-empty, non-zero) value
- * `.config("key")` will insert the value set against the given key at this entity (or nearest ancestor);
- can be used to supply config at the root which is used in multiple places in the plan
-* `$brooklyn:component("scope", "ID")` is also supported, to limit scope to any of
- * `global`: looks for the `ID` anywhere in the plan
- * `child`: looks for the `ID` anywhere in the child only
- * `descendant`: looks for the `ID` anywhere in children or their descendants
- * `sibling`: looks for the `ID` anywhere among children of the parent entity
- * `parent`: returns the parent entity (ignores the `ID`)
- * `this`: returns this entity (ignores the `ID`)
-* `$brooklyn:formatString("pattern e.g. %s %s", "field 1", "field 2")` returns a future which creates the formatted string
- with the given parameters, where parameters may be strings *or* other tasks such as `attributeWhenReady`
-* `$brooklyn:literal("string")` returns the given string as a literal (suppressing any `$brooklyn:` expansion)
-* `$brooklyn:sensor("io.brooklyn.ContainingEntityClass", "sensor.name")` returns the strongly typed sensor defined in the given class
-* `$brooklyn:entitySpec(Map)` returns a new `ServiceSpecification` as defined by the given `Map`,
- but as an `EntitySpec` suitable for setting as the value of `ConfigKey<EntitySpec>` config items
- (such as `memberSpec` in `DynamicCluster`)
-
-These can be supplied either as strings or as lists and maps in YAML.
-
-
-## Some Powerful YAML Entities
-
-All entities support configuration via YAML, but these entities in particular
-have been designed for general purpose use from YAML. Consult the Javadoc for these
-elements for more information:
-
-* **Vanilla Software** in `VanillaSoftwareProcess`: makes it very easy to build entities
- which use `bash` commands to install and the PID to stop and restart
-* **Chef** in `ChefSoftwareProcess`: makes it easy to use Chef cookbooks to build entities,
- either with recipes following conventions or with configuration in the `ServiceSpecification`
- to use artibitrary recipes
-* `DynamicCluster`: provides resizable clusters given a `memberSpec` set with `$brooklyn.entitySpec(Map)` as described above
-* `DynamicFabric`: provides a set of homogeneous instances started in different locations,
- with an effector to `addLocation`, i.e. add a new instance in a given location, at runtime
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/entities/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/entities/index.md b/docs/guide/use/guide/entities/index.md
deleted file mode 100644
index f679611..0000000
--- a/docs/guide/use/guide/entities/index.md
+++ /dev/null
@@ -1,133 +0,0 @@
----
-title: Custom Entity Development
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, entities]
----
-
-This section details how to create new custom application components or groups as brooklyn entities.
-
-<a name="entity-lifestyle"></a>
-The Entity Lifecycle
---------------------
-
-- Importance of serialization, ref to How mananagement works
-- Parents and Membership (groups)
-
-<a name="implementation-classes"></a>
-What to Extend -- Implementation Classes
-----------------------------------------
-
-- entity implementation class hierarchy
-
- - ``SoftwareProcess`` as the main starting point for base entities (corresponding to software processes),
- and subclasses such as ``VanillaJavaApp``
- - ``DynamicCluster`` (multiple instances of the same entity in a location) and
- ``DynamicFabric`` (clusters in multiple location) for automatically creating many instances,
- supplied with an ``EntityFactory`` (e.g. ``BaseEntityFactory``) in the ``factory`` flag
- - abstract ``Group`` for collecting entities which are parented elsewhere in the hierachy
- - ``AbstractEntity`` if nothing else fits
-
-- traits (mixins, otherwise known as interfaces with statics) to define available config keys, sensors, and effectors;
- and conveniences e.g. ``StartableMethods.{start,stop}`` is useful for entities which implement ``Startable``
-
-- the ``Entities`` class provides some generic convenience methods; worth looking at it for any work you do
-
-A common lifecycle pattern is that the ``start`` effector (see more on effectors below) is invoked,
-often delegating either to a driver (for software processes) or children entities (for clusters etc).
-
-See ``JBoss7Server`` and ``MySqlNode`` for exemplars.
-
-
-<a name="configuration"></a>
-Configuration
--------------
-<!---
-TODO: why to use config?
--->
-
-- AttributeSensorAndConfigKey fields can be automatically converted for ``SoftwareProcess``.
- This is done in ``preStart()``. This must be done manually if required for other entities,
- often with ``ConfigToAttributes.apply(this)``.
-
-- Setting ports is a special challenge, and one which the ``AttributeSensorAndConfigKey`` is particularly helpful for,
- cf ``PortAttributeSensorAndConfigKey`` (a subclass),
- causing ports automatically get assigned from a range and compared with the target ``PortSupplied`` location.
-
- Syntax is as described in the PortRange interface. For example, "8080-8099,8800+" will try port 8080, try sequentially through 8099, then try from 8800 until all ports are exhausted.
-
- This is particularly useful on a contended machine (localhost!). Like ordinary configuration, the config is done by the user, and the actual port used is reported back as a sensor on the entity.
-
-<a name="implementing-sensors"></a>
-Implementing Sensors
---------------------
-
-- e.g. HTTP, JMX
-
-Sensors at base entities are often retrieved by feeds which poll the entity's corresponding instance in the real world.
-The ``SoftwareProcess`` provides a good example; by subclassing it and overriding the ``connectSensors()`` method
-you could wire some example sensors using the following:
-
-{% highlight java %}
-public void connectSensors() {
- super.connectSensors()
-
- httpFeed = HttpFeed.builder()
- .entity(this)
- .period(200)
- .baseUri(mgmtUrl)
- .poll(new HttpPollConfig<Boolean>(SERVICE_UP)
- .onSuccess(HttpValueFunctions.responseCodeEquals(200))
- .onError(Functions.constant(false)))
- .poll(new HttpPollConfig<Integer>(REQUEST_COUNT)
- .onSuccess(HttpValueFunctions.jsonContents("requestCount", Integer.class)))
- .build();
-}
-
-@Override
-protected void disconnectSensors() {
- super.disconnectSensors();
- if (httpFeed != null) httpFeed.stop();
-}
-{% endhighlight %}
-
-In this example (a simplified version of ``JBoss7Server``), the url returns metrics in JSON.
-We report the entity as up if we get back an http response code of 200, or down if any other response code or exception.
-We retrieve the request count from the response body, and convert it to an integer.
-
-Note the first line (``super.connectSensors()``); as one descends into specific convenience subclasses (such as for Java web-apps), the work done by the parent class's overridden methods may be relevant, and will want to be invoked or even added to a resulting list.
-
-For some sensors, and often at compound entities, the values are obtained by monitoring values of other sensors on the same (in the case of a rolling average) or different (in the case of the average of children nodes) entities. This is achieved by policies, described below.
-
-<a name="implementing-effectors"></a>
-Implementing Effectors
-----------------------
-
-The ``Entity`` interface defines the sensors and effectors available. The entity class provides
-wiring for the sensors, and the effector implementations. In simple cases it may be straightforward
-to capture the behaviour of the effectors in a simple methods.
-For example deploying a WAR to a cluster can be done as follows:
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-<!---
-TODO show an effector which recurses across children
--->
-
-For some entities, specifically base entities, the implementation of effectors might need other tools (such as SSH), and may vary by location, so having a single implementation is not appropriate.
-
-The problem of multiple inheritance (e.g. SSH functionality and entity inheritance) and multiple implementations (e.g. SSH versus Windows) is handled in brooklyn using delegates called _drivers_.
-
-In the implementations of ``JavaWebApp`` entities, the behaviour which the entity always does is captured in the entity class (for example, breaking deployment of multiple WARs into atomic actions), whereas implementations which is specific to a particular entity and driver (e.g. using scp to copy the WARs to the right place and install them, which of course is different among appservers, or using an HTTP or JMX management API, again where details vary between appservers) is captured in a driver class.
-
-Routines which are convenient for specific drivers can then be inherited in the driver class hierarchy. For example, when passing JMX environment variables to Java over SSH, ``JavaSoftwareProcessSshDriver`` extends ``AbstractSoftwareProcessSshDriver`` and parents ``JBoss7SshDriver``.
-
-<!---
-TODO more drivers such as jmx, etc are planned
--->
-
-<a name="testing"></a>
-Testing
--------
-
-* Run in a mock ``SimulatedLocation``, defining new metaclass methods to be able to start there and assert the correct behaviour when that is invoked
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/entities/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/entities/toc.json b/docs/guide/use/guide/entities/toc.json
deleted file mode 100644
index 69dbfb9..0000000
--- a/docs/guide/use/guide/entities/toc.json
+++ /dev/null
@@ -1,12 +0,0 @@
-[{ "title": "Entity Lifecycle",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#entity-lifestyle" },
-{ "title": "What to Extend",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#implementation-classes" },
-{ "title": "Configuration",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#configuration" },
-{ "title": "Implementing Sensors",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#implementing-sensors" },
-{ "title": "Implementing Effectors",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#implementing-effectors" },
-{ "title": "Testing",
- "file": "{{ site.path.guide }}/use/guide/entities/index.html#testing" }]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/extras/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/extras/index.md b/docs/guide/use/guide/extras/index.md
deleted file mode 100644
index 7136dd1..0000000
--- a/docs/guide/use/guide/extras/index.md
+++ /dev/null
@@ -1,160 +0,0 @@
----
-title: Systems Available Out-of-the-Box
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
----
-
-brooklyn comes bundled with support for a large number of systems and entities.
-
-*Some entities are in an early-access state, and documentation is incomplete. Please contact the Brooklyn Project for assistance and clarification.*
-<!---
-.. TODO fix
-.. TODO name entities
-.. TODO include the fully qualified name of the entity
--->
-
-<a name="web"></a>
-Web
----
-
-### Clusters and Interfaces
-
-The class ``ControlledDynamicWebAppCluster`` creates a load-balanced cluster of web servers.
-It defaults to Nginx and JBoss 7, but this is configurable with the ``controller`` or ``controllerSpec``, and
-the ``memberSpec`` configuration options.
-
-Most web app server processes, and some clusters and PaaS implementations,
-support the interface ``WebAppService`` which defines many sensors including requests per second.
-This allows app server metrics to interoperable across implementations in many cases.
-
-
-### JBoss Application Server
-
-Brooklyn supports JBoss 7 in the calss ``JBoss7Server``, with a wide range of
-monitoring.
-
-JBoss 6 is also supported using the different class ``JBoss6Server``.
-(The different implementation is needed due to major differences between 6 and 7,
-including switching from JMX to HTTP/JSON as the preferred metrics mechanism.)
-
-
-### Apache Tomcat
-
-Apache Tomcat is supported in the class ``TomcatServer``.
-(Note that this currently uses a legacy Brooklyn class hierarchy,
-and could benefit from being ported to the ``JavaSoftwareProcessSshDriver`` implementation.)
-
-
-### Nginx Load Balancer
-
-Nginx provides clustering support for several web/app servers.
-
-The install process downloads the sources for both the service and the sticky session module, configures them using GNI
-autoconf and compiles them. This requires gcc and autoconf to be installed. The install script also uses the yum package manager (if available) to install openssl-devel which is required to build the service. This will only work on RHEL or CentOS Linux systems, but the install process should proceed on a vanilla system with development tools available.
-
-On debian/ubuntu to build nginx you can get the required libraries with:
-``apt-get install zlib1g-dev libdigest-sha-perl libssl-dev``.
-(The entity install script will attempt to do this with sudo,
-but that may fail if sudo access is not available.)
-
-
-<a name="database"></a>
-Database
---------
-
-### MySQL
-
-MySQL is one of the most popular relational databases.
-Brooklyn supports setting up individual MySQL nodes with arbitrary configuration,
-which may be used to create multiple nodes using back-up and synchronization processes as desired.
-(If certain patterns for configuring multiple nodes become popular, these could be
-added as Brooklyn entities.)
-
-
-### Apache Derby
-
-*This entity is in the sandbox.*
-
-Brooklyn supports Apache Derby, a pure-Java SQL database. For setting up an instance of a server see ``DerbySetup``.
-
-
-<a name="nosql"></a>
-NoSQL
------
-
-*The NoSQL entities may not be complete.*
-
-### Redis
-
-Redis is a distributed key-value store, supporting master/slave replication of a store as a clustered cache. This gives
-a series of read-only slaves and a single read-write master, which propagates to the slaves with eventual consistency.
-
-
-### MongoDB
-
-
-### Cassandra
-
-
-### CouchBase
-
-
-<a name="messaging"></a>
-Messaging
----------
-
-### Qpid
-
-
-Qpid support provides a JMS broker, running over AMQP. This exposes JMS queues and topics as entities as well.
-See ``QpidSetup`` for instantiating a broker.
-
-### ActiveMQ
-
-
-ActiveMQ support provides a JMS broker. This exposes JMS queues and topics as entities as well. See ``ActiveMQSetup`` for
-instantiating a broker.
-
-### RabbitMQ
-
-
-<a name="downstream-projects"></a>
-Downstream Projects
--------------------
-
-Downstream projects include those below.
-
-### Apache Whirr
-
-https://github.com/brooklyncentral/brooklyn-whirr
-
-Whirr allows running a variety of services on cloud providers and on localhost. This is done by providing a ``recipe`` which describes what services to launch. You can find an example of how Brooklyn integrates with Whirr [here](/use/examples/whirrhadoop/index.html#custom-whirr-recipe).
-
-### OpenShift
-
-https://github.com/cloudsoft/brooklyn-openshift
-
-### CloudFoundry
-
-https://github.com/cloudsoft/brooklyn-cloudfoundry and https://github.com/cloudsoft/brooklyn-cloudfoundry
-
-### MPI
-
-https://github.com/cloudsoft/brooklyn-openmpi
-
-### Waratek
-
-https://github.com/cloudsoft/brooklyn-waratek
-
-### MapR
-
-https://github.com/cloudsoft/brooklyn-mapr
-
-### Cloudera CDH
-
-https://github.com/cloudsoft/brooklyn-cdh
-
-### Drupal and Wordpress
-
-https://github.com/cloudsoft/brooklyn-social-apps
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/extras/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/extras/toc.json b/docs/guide/use/guide/extras/toc.json
deleted file mode 100644
index 3a4f11f..0000000
--- a/docs/guide/use/guide/extras/toc.json
+++ /dev/null
@@ -1,11 +0,0 @@
-[{ "title": "Web",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html#web" },
-{ "title": "Database",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html#database" },
-{ "title": "NoSQL",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html#nosql" },
-{ "title": "Messaging",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html#messaging" },
-{ "title": "Provisioning",
- "file": "{{ site.path.guide }}/use/guide/extras/index.html#provisioning" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/guide_toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/guide_toc.json b/docs/guide/use/guide/guide_toc.json
deleted file mode 100644
index 889353e..0000000
--- a/docs/guide/use/guide/guide_toc.json
+++ /dev/null
@@ -1,25 +0,0 @@
-[
-{ "title": "Start",
- "file": "{{ site.path.guide }}/start/index.html" },
-
-{ "title": "User Guide",
- "file": "{{ site.path.guide }}/use/guide/index.html",
- "children": {% readj toc.json %} },
-{ "title": "Elsewhere",
- "file": "{{ site.path.guide }}/start/index.html",
- "children": [
-
-{ "title": "Examples",
- "file": "{{ site.path.guide }}/use/examples/index.html",
- "children": {% readj /guide/use/examples/toc.json %} },
-{ "title": "API Reference",
- "file": "{{ site.path.guide }}/use/api/index.html" },
-
-{ "title": "Contributing",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "children": {% readj /guide/dev/toc.json %} },
-{ "title": "License",
- "file": "{{ site.path.guide }}/license/index.html" }
-]}
-
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/index.md b/docs/guide/use/guide/index.md
deleted file mode 100644
index 655d401..0000000
--- a/docs/guide/use/guide/index.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-layout: guide-normal
-title: User Guide
-toc: guide_toc.json
-categories: use
----
-
-## Table of Contents
-
-{% capture ugtocs %}{% readj toc.json %}{% endcapture %}
-{% jsonball ugtoc from var ugtocs %}
-
-<div id="ug_toc_lists">
-<ul>
-{% for x in ugtoc %}
- <li><a class='toc' href="{{ x.file }}">{{ x.title }}</a></li>
- {% if x.children %}
- <ul>
- {% for x2 in x.children %}
- <li><a class='toc' href="{{ x2.file }}">{{ x2.title }}</a></li>
- {% if x2.children %}
- <ul>
- {% for x3 in x2.children %}
- <li><a class='toc' href="{{ x3.file }}">{{ x3.title }}</a></li>
- {% endfor %}
- </ul>
- {% endif %}
- {% endfor %}
- </ul>
- {% endif %}
-{% endfor %}
-</ul>
-</div>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/locations/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/locations/index.md b/docs/guide/use/guide/locations/index.md
deleted file mode 100644
index c2eff2f..0000000
--- a/docs/guide/use/guide/locations/index.md
+++ /dev/null
@@ -1,104 +0,0 @@
----
-title: Locations
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
-
----
-
-Locations are the environments to which Brooklyn deploys applications.
-These can be clouds (public or private), fixed infrastructure environments, or your laptop.
-
-Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`.
-
-## Setting up an SSH key
-
-While some locations can be accessed using *user:password* credentials it is more common to use authentication keys.
-
-To use keyfile based authentication, Brooklyn requires that the management machine has an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`.
-
-If you do not already have an SSH key installed, create a new id_rsa key:
-
-{% highlight bash %}
-$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
-{% endhighlight %}
-
-If you wish to use an existing key SSH, or an SSH key
-that has a passphrase, or a location other than `~/.ssh`, you can specify this in
-`brooklyn.properties` using `brooklyn.location.localhost.privateKeyFile` and
-`brooklyn.location.localhost.privateKeyPassphrase`.
-
-## Localhost
-
-Brooklyn can access localhost if there is an SSH key on the machine and if the SSH key has been added to the list of `authorized_keys` on that machine.
-
-{% highlight bash %}
-# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
-$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
-{% endhighlight %}
-
-MacOS user? In addition to the above, enable 'Remote Login' in System Preferences >
- Sharing.
-
-
-## Cloud Endpoints (via jclouds)
-
-[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/) is available on jclouds.apache.org.
-
-Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key on the management machine.
-
-Some clouds provide both API keys and SSH keys. In this case add only the API credentials to `brooklyn.properties`. (jclouds will transparently use the API credentials to setup access using the management machine's SSH key.)
-
-### Example: AWS Virginia Large Centos
-
-{% highlight bash %}
-## Snippet from ~/.brooklyn/brooklyn.properties.
-
-# Provide jclouds with AWS API credentials.
-brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
-
-# Name this location 'AWS Virginia Large Centos' and wire to AWS US-East-1
-brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2:us-east-1
-
-# (Using the same name) specify image, user and minimum ram size (ie instance size)
-brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
-brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
-brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096
-
-
-{% endhighlight %}
-
-This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line as: `AWS\ Virginia\ Large\ Centos`.
-
-See the Getting Started [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties) for more examples of using cloud endpoints.
-
-
-## Fixed Infrastructure
-
-Bringing your own nodes (BYON) to Brooklyn is straightforward.
-
-You will need the IP addresses of the nodes and the access credentials. Both SSH and password based login are supported.
-
-### Example: On-Prem Iron
-
-{% highlight bash %}
-## Snippet from ~/.brooklyn/brooklyn.properties.
-
-# Use the byon prefix, and provide the IP addresss (or IP ranges)
-brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
-brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
-brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
-
-{% endhighlight %}
-
-
-## Advanced Options
-
-Unusual provider? 'Featureful' API? Brooklyn can cope.
-
-[This spreadsheet](https://docs.google.com/a/cloudsoftcorp.com/spreadsheet/ccc?key=0Avy7Tdf2EOIqdGQzSlNiT2M0V19SejBScDhSdzMtT2c) provides explanation, guidance, and examples for the majority of location options.
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/locations/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/locations/toc.json b/docs/guide/use/guide/locations/toc.json
deleted file mode 100644
index 0637a08..0000000
--- a/docs/guide/use/guide/locations/toc.json
+++ /dev/null
@@ -1 +0,0 @@
-[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/management/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/index.md b/docs/guide/use/guide/management/index.md
deleted file mode 100644
index 8d86776..0000000
--- a/docs/guide/use/guide/management/index.md
+++ /dev/null
@@ -1,383 +0,0 @@
----
-title: Runtime Management
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
-
----
-<a name="introduction"></a>
-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.
-
-There are several ways to launch applications with brooklyn, and useful configuration options,
-as well as a debug-view web console.
-This chapter describes these high-level runtime concepts, then proceeds to present more
-detailed information on the underlying implementation of management within brooklyn.
-
-
-<a name="startup-config"></a>
-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.
-
-
-
-<a name="cli"></a>
-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)] <command> [<args>]
-
-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 <command>' 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.
-
-
-<a name="console"></a>
-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.
-
-<!-- FIXME Update to use new construction pattern, rather than calling app's constructor -->
-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:
-
-[](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.
-
-[](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.
-
-
-
-<a name="observation-other"></a>
-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 does not yet expose a REST API. This was to allow the APi to be designed to align with emerging standards.
-
-Selected management operations are possible remotely using links exposed by the GUI (after authenticating with the GUI).
-
-### Logging
-
-Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including java.util.logging, log4j, and logback.
-
-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.
-
-
-<!---
-
-<a name="distributed-management"></a>
-Distributed Management
-----------------------
-
-TODO Describe how and when objects become "live", pushed out to other nodes.
--->
-
-<!---
-
-<a name="resilience"></a>
-Resilience
-----------
-TODO
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
--->
-
-
-<a name="key-apis"></a>
-Key APIs
---------
-<!---
-TODO - brief overview of 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)
-
-
-<!---
-TODO - describe how to simply configure logging slf4j
--->
-<a name="sensors-and-effectors"></a>
-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<String> 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.
-
-<!---
-TODO probably say about events now, quick reference about SubscriptionManager (either here or in next section on management context)
-TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as reader won't need to know too much detail of sensor types to understand policies... though perhaps saying some is right. (Talking about JSON is almost certainly overkill...)
--->
-
-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".
-
-<!---
-TODO check classes above; is this much detail needed here?
--->
-
-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.
-<!---
-TODO , etc., example
--->
-
-### 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.*
-<!---
-TODO
--->
-
-### 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<Void> 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/a7a317bf/docs/guide/use/guide/management/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/toc.json b/docs/guide/use/guide/management/toc.json
deleted file mode 100644
index e30d160..0000000
--- a/docs/guide/use/guide/management/toc.json
+++ /dev/null
@@ -1,18 +0,0 @@
-[{ "title": "Introduction",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#introduction" },
-{ "title": "Startup Configuration",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#startup-config" },
-{ "title": "Command Line Interface",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#cli" },
-{ "title": "Management Web Console",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#console" },
-{ "title": "Observation APIs",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#observation-other" },
-{ "title": "Distributed Management",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#distributed-management" },
-{ "title": "Resilience",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#resilience" },
-{ "title": "Key APIs",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#key-apis" },
-{ "title": "Sensors and Effectors",
- "file": "{{ site.path.guide }}/use/guide/management/index.html#sensors-and-effectors" }]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/management/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/webconsole-dashboard-w400.png b/docs/guide/use/guide/management/webconsole-dashboard-w400.png
deleted file mode 100644
index 6364dc5..0000000
Binary files a/docs/guide/use/guide/management/webconsole-dashboard-w400.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/management/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/webconsole-dashboard.png b/docs/guide/use/guide/management/webconsole-dashboard.png
deleted file mode 100644
index cac5567..0000000
Binary files a/docs/guide/use/guide/management/webconsole-dashboard.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/management/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/webconsole-detail-w400.png b/docs/guide/use/guide/management/webconsole-detail-w400.png
deleted file mode 100644
index b372e55..0000000
Binary files a/docs/guide/use/guide/management/webconsole-detail-w400.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/management/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/management/webconsole-detail.png b/docs/guide/use/guide/management/webconsole-detail.png
deleted file mode 100644
index 17829cd..0000000
Binary files a/docs/guide/use/guide/management/webconsole-detail.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/persistence/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/persistence/index.md b/docs/guide/use/guide/persistence/index.md
deleted file mode 100644
index 1e9054a..0000000
--- a/docs/guide/use/guide/persistence/index.md
+++ /dev/null
@@ -1,260 +0,0 @@
----
-title: Persistence
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
-
----
-<a name="introduction"></a>
-Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted,
-or so that a high availability standby server can take over.
-
-Brooklyn can persist its state to one of two places: the file system, or to an Object Store
-of your choice.
-
-<a name="command-line-options"></a>
-Command Line Options
---------------------
-
-To configure brooklyn, the relevant command line options are:
-
-* `--persist` <persistence mode>
- The persistence mode.
-* `--persistenceDir` <persistence dir>
- The directory to read/write persisted state (or container name if using an object store).
-* `--persistenceLocation` <persistence location>
- The location spec for an object store to read/write persisted state.
-
-For the persistence mode, the possible values are:
-
-* `disabled` means that no state will be persisted or read; when Brooklyn stops all state is lost.
-* `rebind` means that it will read existing state, and recreate entities, locations and policies
- from that. If there is no existing state, startup will fail.
-* `clean` means that any existing state will be deleted, and Brooklyn will be started afresh.
-* `auto` means Brooklyn will rebind if there is any existing state, or will start afresh if
- there is no state.
-
-
-<a name="file-based-persistence"></a>
-File-based Persistence
-----------------------
-
-To persist to the file system, start brooklyn with:
-
-{% highlight bash %}
-brooklyn launch --persist auto --persistenceDir /path/to/myPersistenceDir
-{% endhighlight %}
-
-an
-If there is already data at `/path/to/myPersistenceDir`, then a backup of the directory will
-be made. This will have a name like `/path/to/myPersistenceDir.20140701-142101345.bak`.
-
-The state is written to the given path. The file structure under that path is:
-
-* `./entities/`
-* `./locations/`
-* `./policies/`
-* `./enrichers/`
-
-In each of those directories, an XML file will be created per item - for example a file per
-entity in ./entities/. This file will capture all of the state - for example, an
-entity's: id; display name; type; config; attributes; tags; relationships to locations, child
-entities, group membership, policies and enrichers; and dynamically added effectors and sensors.
-
-
-<a name="object-store-persistence"></a>
-Object Store Persistence
-------------------------
-
-Brooklyn can persist its state to any Object Store API that jclouds supports including
-S3, Swift and Azure. This gives access to any compatible Object Store product or cloud provider
-including AWS-S3, SoftLayer, Rackspace, HP and Microsoft Azure.
-
-To configure the Object Store, add the credentials to `~/.brooklyn/brooklyn.properties` such as:
-
-{% highlight properties %}
-brooklyn.location.named.aws-s3-eu-west-1:aws-s3:eu-west-1
-brooklyn.location.named.aws-s3-eu-west-1.identity=ABCDEFGHIJKLMNOPQRSTU
-brooklyn.location.named.aws-s3-eu-west-1.credential=abcdefghijklmnopqrstuvwxyz1234567890ab/c
-{% endhighlight %}
-
-or:
-
-{% highlight properties %}
-brooklyn.location.named.softlayer-swift-ams01=jclouds:swift:https://ams01.objectstorage.softlayer.net/auth/v1.0
-brooklyn.location.named.softlayer-swift-ams01.identity=ABCDEFGHIJKLM:myname
-brooklyn.location.named.softlayer-swift-ams01.credential=abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz12
-{% endhighlight %}
-
-Start Brooklyn pointing at this target object store, e.g.:
-
-{% highlight bash %}
-brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLocation named:softlayer-swift-ams01
-{% endhighlight %}
-
-
-<a name="rebind"></a>
-Rebind
-------
-
-When Brooklyn starts up pointing at existing state, it will recreate the entities, locations
-and policies based on that persisted state.
-
-Once all have been created, Brooklyn will "manage" the entities. This will bind to the
-underlying entities under management to update the each entity's sensors (e.g. to poll over
-HTTP or JMX). This new state will be reported in the web-console and can also trigger
-any registered policies.
-
-
-<a name="handling-rebind-failures"></a>
-Handling Rebind Failures
-------------------------
-If rebind were to fail for any reason, details of the underlying failures will be reported
-in the brooklyn.debug.log. There are several approaches to resolving problems.
-
-<a name="rebind-failures-determine-underlying-cause"></a>
-### Determine Underlying Cause
-
-The problems reported in brooklyn.debug.log will indicate where the problem lies - which
-entities, locations or policies, and in what way it failed.
-
-<a name="rebind-failures-ignore-errors"></a>
-### Ignore Errors
-
-The `~/.brooklyn/brooklyn.properties` has several configuration options:
-
-{% highlight properties %}
-rebind.failureMode.danglingRef=continue
-rebind.failureMode.loadPolicy=continue
-rebind.failureMode.addPolicy=continue
-rebind.failureMode.rebind=fail_at_end
-{% endhighlight %}
-
-For each of these configuration options, the possible values are:
-
-* `fail_fast`: stop rebind immediately upon errors; do not try to rebind other entities
-* `fail_at_end`: continue rebinding all entities, but then fail so that all errors
- encountered are reported
-* `continue`: log a warning, but ignore the error to continue rebinding. Depending on the
- type of error, this can cause serious problems later (e.g. if the state of an entity
- was entirely missing, then all its children would be orphaned).
-
-The meaning of the configuration options is:
-
-* `rebind.failureMode.dangingRef`: if there is a reference to an entity, location or policy
- that is missing... whether to continue (discarding the reference) or fail.
-* `rebind.failureMode.loadPolicy`: if there is an error instantiate or reconstituting the
- state of a policy or enricher... whether to continue (discarding the policy or enricher)
- or fail.
-* `rebind.failureMode.addPolicy`: if there is an error re-adding the policy or enricher to
- its associated entity... whether to continue (discarding the policy or enricher)
- or fail.
-* `rebind.failureMode.rebind`: any errors on rebind not covered by the more specific error cases described above.
-
-
-<a name="rebind-failures-seek-help"></a>
-### Seek Help
-
-Help can be found at `dev@brooklyn.incubator.apache.org`, where folk will be able to investigate
-issues and suggest work-arounds.
-
-By sharing the persisted state (with credentials removed), Brooklyn developers will be able to
-reproduce and debug the problem.
-
-
-<a name="rebind-failures-determine-fix-up-the-state"></a>
-### Fix-up the State
-
-The state of each entity, location, policy and enricher is persisted in XML.
-It is thus human readable and editable.
-
-After first taking a backup of the state, it is possible to modify the state. For example,
-an offending entity could be removed, or references to that entity removed, or its XML
-could be fixed to remove the problem.
-
-
-### Fixing with Groovy Scripts
-
-The final (powerful and dangerous!) tool is to execute Groovy code on the running Brooklyn
-instance. If authorized, the REST api allows arbitrary Groovy scripts to be passed in and
-executed. This allows the state of entities to be modified (and thus fixed) at runtime.
-
-If used, it is strongly recommended that Groovy scripts are run against a disconnected Brooklyn
-instance. After fixing the entities, locations and/or policies, the Brooklyn instance's
-new persisted state can be copied and used to fix the production instance.
-
-
-<a name="high-availability"></a>
-High Availability
------------------
-
-Brooklyn will automatically run in HA mode if multiple Brooklyn instances are started
-pointing at the same persistence store. One Brooklyn node (e.g. the first one started)
-is elected as HA master: all *write operations* against Brooklyn entities, such as creating
-an application or invoking an effector, should be directed to the master.
-
-Once one node is running as `MASTER`, other nodes start in either `STANDBY` or `HOT_STANDBY` mode:
-
-* In `STANDBY` mode, a Brooklyn instance will monitor the master and will be a candidate
- to become `MASTER` should the master fail. Standby nodes do *not* attempt to rebind
- until they are elected master, so the state of existing entities is not available at
- the standby node. However a standby server consumes very little resource until it is
- promoted.
-
-* In `HOT_STANDBY` mode, a Brooklyn instance will read and make available the live state of
- entities. Thus a hot-standby node is available as a read-only copy.
- As with the standby node, if a hot-standby node detects that the master fails,
- it will be a candidate for promotion to master.
-
-To explicitly specify what HA mode a node should be in, the following CLI options are available
-for the parameter `--highAvailability`:
-
-* `disabled`: management node works in isolation; it will not cooperate with any other standby/master nodes in management plane
-* `auto`: will look for other management nodes, and will allocate itself as standby or master based on other nodes' states
-* `master`: will startup as master; if there is already a master then fails immediately
-* `standby`: will start up as lukewarm standby; if there is not already a master then fails immediately
-* `hot_standby`: will start up as hot standby; if there is not already a master then fails immediately
-
-The REST API offers live detection and control of the HA mode,
-including setting priority to control which nodes will be promoted on master failure:
-
-* `/server/ha/state`: Returns the HA state of a management node (GET),
- or changes the state (POST)
-* `/server/ha/states`: Returns the HA states and detail for all nodes in a management plane
-* `/server/ha/priority`: Returns the HA node priority for MASTER failover (GET),
- or sets that priority (POST)
-
-
-<a name="writing-persistable-code"></a>
-Writing Persistable Code
-------------------------
-The most common problem on rebind is that custom entity code has not been written in a way
-that can be persisted and/or rebound.
-
-The rule of thumb when implementing new entities, locations and policies is that all state
-must be persistable. All state must be stored as config or as attributes, and must be
-serializable (e.g. avoid the use of anonymous inner classes).
-
-Below is a guide for when implementing an entity in Java (or any other JVM language):
-
-* Don't store state in artibrary fields - the field will not be persisted (this is a design
- decision, because Brooklyn cannot intercept the field being written to, so cannot know
- when to persist).
-* Store runtime state as attributes.
-* Ensure values can be serialized. This (currently) uses xstream, which means it does not
- need to implement `Serializable`. However, if declaring your own classes that are to be
- persisted as state of the entity then declare them as static (or top-level) classes
- rather than anonymous inner classes or non-static inner classes.
-* By extending `SoftwareProcess`, entities get a lot of the rebind logic for free. For
- example, the default `rebind()` method will call `connectSensors()`.
-* If necessary, implement rebind. The `entity.rebind()` is called automatically by the
- Brooklyn framework on rebind, after configuring the entity's config/attributes but before
- the entity is managed.
- Note that `init()` will not be called on rebind.
-* For special cases, it is possible to call `entity.requestPerist()` which will trigger
- asynchronous persistence of the entity.
-
-For locations, policies and enrichers they (currently) do not have attributes. However,
-config is persisted automatically. Normally the state of a policy or enricher is transient -
-on rebind it starts afresh, for example with monitoring the performance or health metrics
-rather than relying on the persisted values.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/persistence/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/persistence/toc.json b/docs/guide/use/guide/persistence/toc.json
deleted file mode 100644
index 6cf8767..0000000
--- a/docs/guide/use/guide/persistence/toc.json
+++ /dev/null
@@ -1,16 +0,0 @@
-[{ "title": "Introduction",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#introduction" },
-{ "title": "Command Line Options",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#command-line-options" },
-{ "title": "File-based Persistence",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#file-based-persistence" },
-{ "title": "Object Store Persistence",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#object-store-persistence" },
-{ "title": "Rebind",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#rebind" },
-{ "title": "Handling Rebind Failures",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#handling-rebind-failures" },
-{ "title": "High Availability",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#high-availability" },
-{ "title": "Writing Persistable Code",
- "file": "{{ site.path.guide }}/use/guide/persistence/index.html#writing-persistable-code" }]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/policies/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/policies/index.md b/docs/guide/use/guide/policies/index.md
deleted file mode 100644
index c1be5cb..0000000
--- a/docs/guide/use/guide/policies/index.md
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: Policies
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide]
-
----
-<a name="introduction"></a>
-
-Policies perform the active management enabled by Brooklyn.
-They can subscribe to entity sensors and be triggered by them or they can run periodically.
-
-<!---
-TODO, clarify below, memebers of what?
--->
-Policies can add subscriptions to sensors on any entity. Normally a policy will subscribe to its related entity, to the child entities, and/or those entities which are members.
-
-When a policy runs it can:
-
-* perform calculations,
-* look up other values,
-* invoke efectors (management policies) or,
-* cause the entity associated with the policy to emit sensor values (enricher policies).
-
-Entities can have zero or more ``Policy`` instances attached to them.
-
-<a name="writing-policies"></a>
-Writing Policies
-----------------
-
-### Sample Policy
-
-<!---
-TODO
--->
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-### Best Practice
-
-The following recommendations should be considered when designing policies:
-
-#### Management should take place as "low" as possible in the hierarchy
-* place management responsibility in policies at the entity, as much as possible ideally management should take run as a policy on the relevant entity
-
-* place escalated management responsibility at the parent entity. Where this is impractical, perhaps because two aspects of an entity are best handled in two different places, ensure that the separation of responsibilities is documented and there is a group membership relationship between secondary/aspect managers.
-
-
-#### Policies should be small and composable
-<!--
-TODO Requires Content
--->
-
-e.g. one policy which takes a sensor and emits a different, enriched sensor, and a second policy which responds to the enriched sensor of the first (e.g. a policy detects a process is maxed out and emits a TOO_HOT sensor; a second policy responds to this by scaling up the VM where it is running, requesting more CPU)
-#### Where a policy cannot resolve a situation at an entity, the issue should be escalated to a manager with a compatible policy.
-
-Typically escalation will go to the entity parent, and then cascade up.
-e.g. if the earlier VM CPU cannot be increased, the TOO_HOT event may go to the parent, a cluster entity, which attempts to balance. If the cluster cannot balance, then to another policy which attempts to scale out the cluster, and should the cluster be unable to scale, to a third policy which emits TOO_HOT for the cluster.
-
-#### Management escalation should be carefully designed so that policies are not incompatible
-
-Order policies carefully, and mark sensors as "handled" (or potentially "swallow" them locally), so that subsequent policies and parent entities do not take superfluous (or contradictory) corrective action.
-
-
-For this release, some of the mechanisms for implementing the above practices are still being developed.
-
-### Implementation Classes
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-- extend ``AbstractPolicy``, or override an existing policy
-
-
-<a name="off-the-shelf-policies"></a>
-Off-the-Shelf Policies
-----------------------
-
-Policies are highly reusable as their inputs, thresholds and targets are customizable.
-
-### Management Policies
-- Resizer Policy
-
- Increases or decreases the size of a Resizable entity based on an aggregate sensor value, the current size of the entity, and customized high/low watermarks.
-
- A Resizer policy can take any sensor as a metric, have its watermarks tuned live, and target any resizable entity - be it an application server managing how many instances it handles, or a tier managing global capacity.
-
- e.g. if the average request per second across a cluster of Tomcat servers goes over the high watermark, it will resize the cluster to bring the average back to within the watermarks.
-
-<!---
-TODO - list some
-TODO - describe how they can be customised (briefly mention sensors)
--->
-
-
-### Enricher Policies
-
-* Delta
-
- Converts absolute sensor values into a delta.
-
-
-* Time-weighted Delta
-
- Converts absolute sensor values into a delta/second.
-
-* Rolling Mean
-
- Converts the last *N* sensor values into a mean.
-
-* Rolling Time-window Mean
-
- Converts the last *N* seconds of sensor values into a weighted mean.
-
-* Custom Aggregating
-
- Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc.
-
-<a name="implementing-policies"></a>
-Implementing Policies
----------------------
-
-<!---
-TODO
--->
-
-*This section is not yet complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-Please see the class* ``brooklyn.policy.Policy`` *and implementations.
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/policies/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/policies/toc.json b/docs/guide/use/guide/policies/toc.json
deleted file mode 100644
index 1de7334..0000000
--- a/docs/guide/use/guide/policies/toc.json
+++ /dev/null
@@ -1,8 +0,0 @@
-[{ "title": "Introduction",
- "file": "{{ site.path.guide }}/use/guide/policies/index.html#introduction" },
-{ "title": "Writing Policies",
- "file": "{{ site.path.guide }}/use/guide/policies/index.html#writing-policies" },
-{ "title": "Off-the-Shelf Policies",
- "file": "{{ site.path.guide }}/use/guide/policies/index.html#off-the-shelf-policies" },
-{ "title": "Implementing Policies",
- "file": "{{ site.path.guide }}/use/guide/policies/index.html#implementing-policies" }]
[12/13] incubator-brooklyn git commit: change version in imported
docs to M2
Posted by he...@apache.org.
change version in imported docs to M2
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/5382bc9d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/5382bc9d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/5382bc9d
Branch: refs/heads/0.7.0-M2-incubating-docs
Commit: 5382bc9dc183277dcf1aaf0d0f8b372e83a36d10
Parents: a7a317b
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Jan 9 16:05:10 2015 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Jan 9 16:05:10 2015 +0000
----------------------------------------------------------------------
docs/_build/build.sh | 4 ++--
docs/_build/config-guide-version.yml | 4 ++--
docs/_build/make-javadoc.sh | 2 +-
docs/_config.yml | 2 +-
docs/_extra/simple_java_examples/examples.md | 2 +-
docs/guide/misc/index.md | 2 +-
docs/guide/start/catalog.xml | 4 ++--
docs/index.md | 2 +-
8 files changed, 11 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/_build/build.sh
----------------------------------------------------------------------
diff --git a/docs/_build/build.sh b/docs/_build/build.sh
index 69b2bfa..743d02e 100755
--- a/docs/_build/build.sh
+++ b/docs/_build/build.sh
@@ -21,7 +21,7 @@ function help() {
echo "* website-root : to build the website only, in the root"
echo "* guide-latest : to build the guide only, in /v/latest/"
# BROOKLYN_VERSION_BELOW
- echo "* guide-version : to build the guide only, in the versioned namespace /v/0.7.0-SNAPSHOT/"
+ echo "* guide-version : to build the guide only, in the versioned namespace /v/0.7.0-M2-incubating/"
echo "* test-guide-root : to build the guide only, in the root (for testing)"
echo "* test-both : to build the website to root and guide to /v/latest/ (for testing)"
echo "* test-both-sub : to build the website to /sub/ and guide to /sub/v/latest/ (for testing)"
@@ -65,7 +65,7 @@ function parse_mode() {
# Mac bash defaults to v3 not v4, so can't use assoc arrays :(
DIRS_TO_MOVE[0]=guide
# BROOKLYN_VERSION_BELOW
- DIRS_TO_MOVE_TARGET[0]=v/0.7.0-SNAPSHOT
+ DIRS_TO_MOVE_TARGET[0]=v/0.7.0-M2-incubating
DIRS_TO_MOVE[1]=style
DIRS_TO_MOVE_TARGET[1]=${DIRS_TO_MOVE_TARGET[0]}/style
INSTALL_RSYNC_OPTIONS=""
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/_build/config-guide-version.yml
----------------------------------------------------------------------
diff --git a/docs/_build/config-guide-version.yml b/docs/_build/config-guide-version.yml
index 640f22f..49a6d7a 100644
--- a/docs/_build/config-guide-version.yml
+++ b/docs/_build/config-guide-version.yml
@@ -1,6 +1,6 @@
path:
# BROOKLYN_VERSION_BELOW
- guide: /v/0.7.0-SNAPSHOT
+ guide: /v/0.7.0-M2-incubating
# BROOKLYN_VERSION_BELOW
- style: /v/0.7.0-SNAPSHOT/style
+ style: /v/0.7.0-M2-incubating/style
website: ""
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/_build/make-javadoc.sh
----------------------------------------------------------------------
diff --git a/docs/_build/make-javadoc.sh b/docs/_build/make-javadoc.sh
index ccc1772..b1e61ad 100755
--- a/docs/_build/make-javadoc.sh
+++ b/docs/_build/make-javadoc.sh
@@ -20,7 +20,7 @@ rm -rf target/$JAVADOC_TARGET1_SUBPATH/
export DATESTAMP=`date "+%Y-%m-%d"`
# BROOKLYN_VERSION_BELOW
-export BROOKLYN_JAVADOC_CLASSPATH=../../usage/all/target/brooklyn-all-0.7.0-SNAPSHOT-with-dependencies.jar
+export BROOKLYN_JAVADOC_CLASSPATH=../../usage/all/target/brooklyn-all-0.7.0-M2-incubating-with-dependencies.jar
echo "building javadoc at $DATESTAMP from:
$SOURCE_PATHS"
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/_config.yml
----------------------------------------------------------------------
diff --git a/docs/_config.yml b/docs/_config.yml
index 8e36167..7c9c358 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -43,7 +43,7 @@ exclude: ['/Gemfile*','/README.md']
brooklyn-stable-version: 0.7.0-M2
-brooklyn-version: 0.7.0-SNAPSHOT # BROOKLYN_VERSION
+brooklyn-version: 0.7.0-M2-incubating # BROOKLYN_VERSION
brooklyn-snapshot-git-branch: master # if line above is SNAPSHOT this should point to corresponding git branch (e.g. master, 0.4)
# This is auto-detected, but you can override it if needed.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/_extra/simple_java_examples/examples.md
----------------------------------------------------------------------
diff --git a/docs/_extra/simple_java_examples/examples.md b/docs/_extra/simple_java_examples/examples.md
index 330b6d3..851d12b 100644
--- a/docs/_extra/simple_java_examples/examples.md
+++ b/docs/_extra/simple_java_examples/examples.md
@@ -22,7 +22,7 @@ If you have a Maven-based project, integrate this XML fragment with your pom.xml
<dependency>
<groupId>io.brooklyn</groupId>
<artifactId>brooklyn-all</artifactId>
- <version>0.7.0-SNAPSHOT</version> <!-- BROOKLYN_VERSION -->
+ <version>0.7.0-M2-incubating</version> <!-- BROOKLYN_VERSION -->
</dependency>
</dependencies>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/guide/misc/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/misc/index.md b/docs/guide/misc/index.md
index 1f80f3f..8bb1e0f 100644
--- a/docs/guide/misc/index.md
+++ b/docs/guide/misc/index.md
@@ -1,6 +1,6 @@
---
# BROOKLYN_VERSION_BELOW
-title: Other 0.7.0-SNAPSHOT Resources
+title: Other 0.7.0-M2-incubating Resources
layout: website-normal
children:
- { title: Javadoc, path: javadoc/ }
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/guide/start/catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/start/catalog.xml b/docs/guide/start/catalog.xml
index 6cff554..a440543 100644
--- a/docs/guide/start/catalog.xml
+++ b/docs/guide/start/catalog.xml
@@ -13,8 +13,8 @@
</template>
<classpath>
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-M2-incubating&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-M2-incubating&e=jar</entry> <!-- BROOKLYN_VERSION -->
</classpath>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5382bc9d/docs/index.md
----------------------------------------------------------------------
diff --git a/docs/index.md b/docs/index.md
index 5d2c44b..a6a4da4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,7 @@ title: Brooklyn Website and Docs (dev build)
Consider looking at:
* <a href="{{ site.path.website }}/">the brooklyn website</a>
-* <a href="{{ site.path.guide }}/">the brooklyn user guide (version 0.7.0-SNAPSHOT) <!-- BROOKLYN_VERSION --></a>
+* <a href="{{ site.path.guide }}/">the brooklyn user guide (version 0.7.0-M2-incubating) <!-- BROOKLYN_VERSION --></a>
Also see the file <code>README.md</code> in this directory.
[06/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.include.md b/docs/guide/start/index.include.md
deleted file mode 100644
index 3dfafb4..0000000
--- a/docs/guide/start/index.include.md
+++ /dev/null
@@ -1,50 +0,0 @@
-## What is Brooklyn?
-
-**brooklyn** is a library that simplifies application deployment and management.
-
-For **deployment**, it is designed to tie in with other tools,
-giving single-click deploy and adding the concepts of
-manageable clusters and fabrics:
-
-* many common software entities available out-of-the-box
-* integrates with [Apache Whirr](http://whirr.apache.org)
- to deploy well-known services such as Hadoop and elasticsearch
- (or use POBS, plain-old-bash-scripts)
-* use PaaS's such as OpenShift, alongside self-built clusters, for maximum flexibility
-
-Brooklyn makes roll-out an integral part of the DevOps chain,
-as code which can be version-controlled and programmatically tested,
-and portable across many clouds or fixed IP machines,
-using [jclouds](http://jclouds.org) --
-or just hitting ``localhost`` for quick dev/test.
-
-Brooklyn's main emphasis is post-deployment, **managing** an application once it is live:
-management policies are an integral part of the deployment descriptor,
-and at runtime policies have access to all aspects of the deployment.
-They are aware of the deployment topology (hierarchical) and
-locations (machines, PaaSes, and jurisdictions),
-as well as scripts, instrumentation, and operational goals and constraints.
-This means they're all set, once the application is launched,
-to keep the application running optimally,
-based on whatever *optimally* means in that context.
-
-These deployment patterns and management policies are expressed as Java (and Groovy) classes,
-open-sourced here and giving you full control over what you want to happen.
-More importantly, however, this code can be shared, improved, and extended.
-
-We're still near the beginning of figuring this out:
-[join us to make it better]({{site.path.guide}}/meta/contact.html).
-
-
-## To Get Started
-
-* See the [developer's walkthrough]({{site.path.guide}}/start/walkthrough/index.html) for a quick tour
-* Check out the [examples]({{site.path.guide}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
-* Jump in to the [user guide]({{site.path.guide}}/use/guide/) describing the
- [concepts]({{site.path.guide}}/use/guide/defining-applications/basic-concepts.html)
- and including a [tutorial]({{site.path.guide}}/use/guide/quickstart/)
-* Or dive straight in to the code, either [reading]({{site.path.guide}}/dev/code/) about it
- or [gitting](http://github.com/apache/incubator-brooklyn/) it
-
-If you like it, or if you have ideas how it could be better,
-[join the discussion]({{site.path.guide}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.md b/docs/guide/start/index.md
index eda9390..4967dd7 100644
--- a/docs/guide/start/index.md
+++ b/docs/guide/start/index.md
@@ -1,8 +1,13 @@
---
layout: guide-normal
-title: Overview
-toc: /guide/toc.json
-categories: [start]
+title: Getting Started
+menu_parent: ../index.md
+children:
+- running.md
+- config.md
+- blueprints.md
+- managing.md
+- policies.md
---
-{% readj index.include.md %}
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/known-issues.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/known-issues.md b/docs/guide/start/known-issues.md
deleted file mode 100644
index 65c4986..0000000
--- a/docs/guide/start/known-issues.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-layout: guide-normal
-title: Known Issues
-toc: ../toc.json
----
-
-## Unable to Provision certain types of Debian VMs
-
-*Symptom*: Brooklyn fails to provision Debian VMs (e.g. in aws-ec2).
-
-*Cause*: `sudo` is not available on path, causing Brooklyn to fail to confirm that the VM is ssh'able.
-
-*Workaround*: Choose an image that does have sudo (see [wiki.debian.org/Cloud/AmazonEC2Image](http://wiki.debian.org/Cloud/AmazonEC2Image)).
-
-*Fix*: is [Pull #600](https://github.com/brooklyncentral/brooklyn/pull/600); you may also want to run with `brooklyn.location.jclouds.aws-ec2.user=root` if subsequent commands give permission errors.
-
-*Versions Affected*: 0.5.0-M2
-
-
-### Unable to Provision Ubuntu 8 VMs
-
-*Symptom: Brooklyn fails to provision Ubuntu 8 VMs (e.g. in aws-ec2) with the following error 'Cannot insert the iptables rule for port 22. Error: sudo: illegal option `-n''.
-
-*Cause: Ubuntu 8 is too old; the sudo command doesn't support the -n setting.
-
-*Workaround: Choose Ubuntu 10 or higher.
-
-*Versions Affected*: 0.5.0-M2
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/managing.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/managing.md b/docs/guide/start/managing.md
new file mode 100644
index 0000000..44645f7
--- /dev/null
+++ b/docs/guide/start/managing.md
@@ -0,0 +1,40 @@
+---
+title: Monitoring and Managing Applications
+title_in_menu: Monitoring and Managing Applications
+layout: guide-normal
+menu_parent: index.md
+---
+
+Click on the application name, or open the Applications tab.
+
+We can explore the management hierarchy of the application, which will show us the entities it is composed of.
+
+ * My Web Cluster (A `BasicApplication`)
+ * My DB (A `MySqlNode`)
+ * My Web (A `ControlledDynamicWebAppCluster`)
+ * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`)
+ * NginxController (An `NginxController`)
+
+
+
+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.
+
+
+
+
+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.
+
+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.
+
+[](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.
+
+[](images/my-web-cluster-stop-confirm-large.png)
+
+### Next
+
+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/a7a317bf/docs/guide/start/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/policies.md b/docs/guide/start/policies.md
new file mode 100644
index 0000000..1b665df
--- /dev/null
+++ b/docs/guide/start/policies.md
@@ -0,0 +1,36 @@
+---
+title: Getting Started - Policies
+title_in_menu: Policies
+layout: guide-normal
+---
+
+### Exploring and Testing Policies
+
+The Demo Web Cluster with DB application is pre-configured with two polices.
+
+The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy.
+
+Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster's Cluster of JBoss7Servers.
+
+You will see that the `AutoScalerPolicy` is running.
+
+[](images/jboss7-cluster-policies-large.png)
+
+
+This policy automatically scales the cluster up or down to be the right size for the cluster's current load. (One server is the minimum size allowed by the policy.)
+
+The loadbalancer's `targets` policy ensures that the loadbalancer is updated as the cluster size changes.
+
+Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint to create load on the cluster. (Download a [jmeter test plan](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).)
+
+As load is added, Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster. As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
+
+### Next
+
+This guide has given a quick overview to writing blueprints for applications, deploying applications, and
+managing them. Next, learn more about any of:
+
+* [Writing blueprints with YAML](../yaml/)
+* [Writing blueprints with Java](../java/)
+* [Operating Brooklyn](../ops/)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/release-notes.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/release-notes.md b/docs/guide/start/release-notes.md
deleted file mode 100644
index 44f5bb7..0000000
--- a/docs/guide/start/release-notes.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-layout: guide-normal
-title: Release Notes
-toc: ../toc.json
----
-
-## Brooklyn Version ({{ site.brooklyn-version }})
-
-{% if SNAPSHOT %}
-**You are viewing a SNAPSHOT release (master branch), so this list is incomplete.**
-{% endif %}
-
-* Introduction
-* New Features
-* Backwards Compatibility
-* Community Activity
-
-### Introduction
-
-This version includes many big features,
-incorporating a lot of improvements and feedback from our community. Thank you!
-
-Thanks also go to Brooklyn's commercial users who have funded this development and
-made some major contributions.
-
-For more information, please visit [brooklyn.io](http://brooklyn.io).
-
-
-### New Features
-
-* A huge expansion of what can be done in YAML.
-
-* First-class Chef integration
-
-* New clouds: GCE, Softlayer
-
-* Networking
-
-* Docker support: see [clocker.io](clocker.io)
-
-
-### Backwards Compatibility
-
-* Persistence has been radically overhauled. In most cases the state files from previous versions are compatible,
- but some items have had to change. For most users this should not be an issue as persistence in the previous version
- was not working well in any case.
-
-
-### Community Activity
-
-Brooklyn has moved into the Apache Software Foundation.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/running.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/running.md b/docs/guide/start/running.md
new file mode 100644
index 0000000..db6d525
--- /dev/null
+++ b/docs/guide/start/running.md
@@ -0,0 +1,104 @@
+---
+title: Running Brooklyn
+title_in_menu: Running Brooklyn
+layout: guide-normal
+menu_parent: index.md
+---
+
+This guide will walk you through deploying an example 3-tier web application to a public cloud.
+
+This tutorial assumes that you are using Linux or Mac OSX.
+
+## Install Brooklyn
+
+Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download.html).
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
+{% else %}
+Expand the `tar.gz` archive:
+{% endif %}
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+{% highlight bash %}
+$ tar -zxf brooklyn-dist-{{ site.data.brooklyn.version }}-timestamp-dist.tar.gz
+{% endhighlight %}
+{% else %}
+{% highlight bash %}
+$ tar -zxf brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz
+{% endhighlight %}
+{% endif %}
+
+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:
+
+<pre>
+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)?
+</pre>
+
+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 }}/use/guide/locations/) may be
+useful.
+
+
+
+
+## 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:
+
+{% highlight bash %}
+$ brooklyn launch
+{% endhighlight %}
+
+Brooklyn will output the address of the management interface:
+
+
+`INFO Starting brooklyn web-console on loopback interface because no security config is set`
+
+`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.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/start/toc.json b/docs/guide/start/toc.json
deleted file mode 100644
index 532ce68..0000000
--- a/docs/guide/start/toc.json
+++ /dev/null
@@ -1,10 +0,0 @@
-[
-{ "title": "Overview",
- "file": "{{ site.path.guide }}/index.html" },
-{ "title": "Walkthrough",
- "file": "{{ site.path.guide }}/start/walkthrough/index.html" },
-{ "title": "Download",
- "file": "{{ site.path.guide }}/start/download.html" },
-{ "title": "Documentation",
- "file": "{{ site.path.guide }}/start/docs-summary.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/video.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/video.md b/docs/guide/start/video.md
deleted file mode 100644
index c45dd4c..0000000
--- a/docs/guide/start/video.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: guide-normal
-title: Video
-toc: ../toc.json
----
-
-TODO
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/index.md b/docs/guide/start/walkthrough/index.md
deleted file mode 100644
index d96e611..0000000
--- a/docs/guide/start/walkthrough/index.md
+++ /dev/null
@@ -1,240 +0,0 @@
----
-layout: guide-normal
-title: Walkthrough
-toc: /guide/toc.json
----
-{% include fields.md %}
-
-## Intro
-
-Brooklyn makes it easy to describe the structure and management of sophisticated distributed applications,
-and then it makes it easy to launch them in a cloud, with on-going automated management.
-
-This walkthrough will set up a sample application which you can use as foundation for creating your own applications.
-
-The sample application is a three tier web service, composed of:
-
-* an Nginx load-balancer
-* a cluster of JBoss appservers
-* a MySQL database
-
-
-## Download the Sample Project
-
-If you'd like to follow these steps on your machine, you can use Maven to
-download the Brooklyn quickstart archetype and setup a `brooklyn-sample` directory and project.
-Maven will automatically download Brooklyn and all dependencies.
-You can of course follow this walkthrough without installing it on your machine ... yet!
-
-{% if SNAPSHOT %}
-
-{% highlight bash %}
-$ export BROOKLYN_VERSION=0.7.0-M2-incubating
-$ mvn archetype:generate \
- -DarchetypeGroupId=io.brooklyn \
- -DarchetypeArtifactId=brooklyn-archetype-quickstart \
- -DarchetypeVersion=${BROOKLYN_VERSION} \
- -DarchetypeCatalog=https://oss.sonatype.org/content/repositories/snapshots/archetype-catalog.xml \
- -DgroupId=com.acme.sample \
- -DartifactId=brooklyn-sample \
- -Dversion=0.1.0-SNAPSHOT \
- -Dpackage=com.acme.sample.brooklyn \
- --batch-mode
-$ cd brooklyn-sample
-{% endhighlight %}
-
-*Note*: As this is a snapshot version of Brooklyn, the code above includes a `-DarchetypeCatalog` specification.
-This can be omitted for release versions, or if you already have a local `mvn install` of Brooklyn installed as described [here]({{site.path.guide}}/dev/code/index.html).
-
-{% else %}
-
-{% highlight bash %}
-$ export BROOKLYN_VERSION=0.7.0-M2-incubating
-$ mvn archetype:generate \
- -DarchetypeGroupId=io.brooklyn \
- -DarchetypeArtifactId=brooklyn-archetype-quickstart \
- -DarchetypeVersion=${BROOKLYN_VERSION} \
- -DgroupId=com.acme.sample \
- -DartifactId=brooklyn-sample \
- -Dversion=0.1.0-SNAPSHOT \
- -Dpackage=com.acme.sample.brooklyn
-$ cd brooklyn-sample
-{% endhighlight %}
-
-{% endif %}
-
-## Define your Application Blueprint
-
-An application blueprint is defined as a Java class, as follows:
-
-{% highlight java %}
-public class ClusterWebServerDatabaseSample extends AbstractApplication {
- @Override
- public void init() {
- MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class));
- ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class));
- }
-}
-{% endhighlight %}
-
-The file `ClusterWebServerDatabaseSample.java` in `src/main/java/com/acme/sample/brooklyn/sample/app/`
-provides a template to follow.
-
-
-## Deploying the Application
-
-If you have not already done so, follow the section in the
-[Getting Started Guide]({{site.path.guide}}/use/guide/quickstart/index.html) to create a `brooklyn.properties`
-file containing credentials for your preferred cloud provider.
-
-To launch this application, build the project and run the `start.sh` script in the resulting assembly:
-
-{% highlight bash %}
-$ mvn clean assembly:assembly
-
-$ cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/
-
-$ ./start.sh launch \
- --app com.acme.sample.brooklyn.sample.app.ClusterWebServerDatabaseSample \
- --location jclouds:aws-ec2:eu-west-1
-{% endhighlight %}
-
-(Amazon is used in this walkthrough, but lots of targets are supported,
-including `--location localhost`, fixed IP addresses, and
-everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute.)
-
-Your console will inform you that it has started a Brooklyn console at [http://localhost:8081](http://localhost:8081)
-
-[](wt-starting.png)
-
-The management console provides a view on to the entities that launched,
-including the hierarchy (appservers grouped into a cluster) and their locations.
-
-Brooklyn collects information from these entities ("sensors"),
-aggregates these for clusters and other groups (using "enrichers"),
-and exposes operations ("effectors") that can be performed on entities.
-
-[](wt-tree-jboss-sensors.png)
-
-
-## Topology, Dependencies, and Management Policies
-
-Of course in the real world, application deployments are more interesting;
-they do things and need configuration. For instance you might need to:
-
-* specify a WAR file
-* initialize the database
-* tell the webapp servers where to find the database
-
-Let's show how these are done using Brooklyn.
-We assume the WAR file and the database init script are accessible
-on the classpath, but a range of URL formats is supported.
-The "dependent inter-process configuration" -- giving the database's URL
-to the webapps -- we'll do here with a JVM system property,
-but you're free to use any mechanism you wish.
-
-Under the covers, ``attributeWhenReady`` is monitoring a sensor from MySQL
-and generating a string to pass to the webapp software processes; ``formatString``
-is a similar utility that returns a string once all of its parts have been resolved.
-Due to the use of futures, the Brooklyn webapp entities will automatically
-block "at the last moment" when the value is needed
-(but after e.g. the VMs have been provisioned, to speed things up).
-
-{% highlight java %}
-public class ClusterWebServerDatabaseSample extends AbstractApplication {
- @Override
- public void init() {
- MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
- .configure(MySqlNode.CREATION_SCRIPT_URL, "classpath://visitors-database-setup.sql"));
-
- ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
- .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
- .configure("httpPort", "8080+")
- .configure("war", WAR_PATH)
- .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"),
- formatString("jdbc:%s%s?user=%s\\&password=%s",
- attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
- }
-}
-{% endhighlight %}
-
-We now see our app at the Nginx URL:
-
-[](wt-deployed-application.png)
-
-Finally, we'll bring in some active management: we're going to monitor requests per second,
-and scale out if this exceeds 100 up to a maximum of 5 servers.
-This is a naively simple policy, but it shows Brooklyn's real metier,
-running management policies for applications whose topology it knows.
-
-{% highlight java %}
- web.getCluster().addPolicy(AutoScalerPolicy.builder().
- metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
- sizeRange(1, 5).
- metricRange(10, 100).
- build());
-{% endhighlight %}
-
-*Policies* in Brooklyn typically subscribe to sensors, perform some computation, and if necessary invoke effectors on entities. This is where the ability to group entities
-becomes very useful -- policies can be attached to group entities, and groups themselves can be hierarchical. It's also handy that often Brooklyn creates the entities,
-so it knows what the hierarchy is.
-
-Under the covers, this ``AutoScalerPolicy`` attaches to any ``Resizable`` entity (exposing a ``resize`` effector), and monitors a specified sensor (or function) attempting to keep it within healthy limits. A separate policy operates at the ``Controlled`` cluster to ensure the load-balancer is updated as the pool of web servers expands and contracts.
-
-Fire up a JMeter session (or other load testing tool) and blast the Nginx address. The auto-scaler policy will scale up the cluster.
-
-## What Next?
-
-In addition to the sample project created by the archetype, with its README and
-`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example,
-described [in detail here]({{site.path.guide}}/use/examples/webcluster).
-
-For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS.
-Brooklyn supports some of these out-of-the-box, including a wide-range of tools which it can use Whirr to provision, such as Hadoop.
-But if you have something you don't see,
-[let us know]({{site.path.guide}}/meta/contact.html) --
-we want to work with you to
-[write a new entity]({{site.path.guide}}/dev/code/entity.html) or
-[policy]({{site.path.guide}}/dev/code/policy.html)
-and [contribute it]({{site.path.guide}}/dev/how-to-contrib.html).
-
-
-<!--
-
-Alternatively you can just add a ``main`` method to the application class as follows:
-
-{% highlight java %}
- public static void main(String[] argv) {
- List<String> args = Lists.newArrayList(argv);
- String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
- String location = CommandLineUtil.getCommandLineOption(args, "--location", DEFAULT_LOCATION);
-
- BrooklynServerDetails server = BrooklynLauncher.newLauncher()
- .webconsolePort(port)
- .launch();
-
- Location loc = server.getManagementContext().getLocationRegistry().resolve(location);
-
- StartableApplication app = new WebClusterDatabaseExample()
- .appDisplayName("Brooklyn WebApp Cluster with Database example")
- .manage(server.getManagementContext());
-
- app.start(ImmutableList.of(loc));
-
- Entities.dumpInfo(app);
- }
-{% endhighlight %}
-
-Compile and run this with the [``brooklyn-all`` jar]({{site.path.guide}}/start/download.html) on the classpath,
-pointing at your favourite WAR on your filesystem.
-(If the ``import`` packages aren't picked up correctly,
-you can cheat by looking at [the file in Github](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/src/main/java/brooklyn/demo/WebClusterDatabaseExample.java);
-and you'll find a sample WAR which uses the database as configured above
-[here](https://http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/).)
- TODO example webapp url
-
-If you want to adventure beyond ``localhost`` (the default),
-simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``)
-with credentials set up as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config).
-
--->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-deployed-application-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-deployed-application-700.png b/docs/guide/start/walkthrough/wt-deployed-application-700.png
deleted file mode 100644
index 7ef90d9..0000000
Binary files a/docs/guide/start/walkthrough/wt-deployed-application-700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-deployed-application.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-deployed-application.png b/docs/guide/start/walkthrough/wt-deployed-application.png
deleted file mode 100644
index 751402e..0000000
Binary files a/docs/guide/start/walkthrough/wt-deployed-application.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-starting-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-starting-700.png b/docs/guide/start/walkthrough/wt-starting-700.png
deleted file mode 100644
index c87a539..0000000
Binary files a/docs/guide/start/walkthrough/wt-starting-700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-starting.png b/docs/guide/start/walkthrough/wt-starting.png
deleted file mode 100644
index 970805f..0000000
Binary files a/docs/guide/start/walkthrough/wt-starting.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png b/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png
deleted file mode 100644
index 3dfc7f2..0000000
Binary files a/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png b/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png
deleted file mode 100644
index 4c44ea9..0000000
Binary files a/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/toc-menu.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc-menu.json b/docs/guide/toc-menu.json
deleted file mode 100644
index 6c1e3c3..0000000
--- a/docs/guide/toc-menu.json
+++ /dev/null
@@ -1,20 +0,0 @@
-[
-{ "title": "Overview",
- "file": "{{ site.path.guide }}/index.html" },
-{ "title": "Download",
- "file": "{{ site.path.guide }}/start/download.html" },
-{ "title": "Getting Started",
- "file": "{{ site.path.guide }}/use/guide/quickstart/index.html" },
-{ "title": "Walkthrough",
- "file": "{{ site.path.guide }}/start/walkthrough/index.html" },
-{ "title": "User Guide",
- "file": "{{ site.path.guide }}/use/guide/index.html",
- "children": {% readj use/guide/toc.json %} },
-{ "title": "Examples",
- "file": "{{ site.path.guide }}/use/examples/index.html",
- "children": {% readj use/examples/toc.json %} },
-{ "title": "Contributing",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "exclude": true,
- "children": {% readj dev/toc.json %} }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc.json b/docs/guide/toc.json
deleted file mode 100644
index 07d4c5c..0000000
--- a/docs/guide/toc.json
+++ /dev/null
@@ -1,21 +0,0 @@
-[
-{ "title": "Start",
- "file": "{{ site.path.guide }}/start/index.html",
- "exclude": true,
- "children": {% readj start/toc.json %} },
-{ "title": "Using brooklyn",
- "file": "{{ site.path.guide }}/use/index.html",
- "children": {% readj use/toc.json %} },
-{ "title": "Contributing",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "exclude": true,
- "children": {% readj dev/toc.json %} },
-{ "title": "License",
- "file": "{{ site.path.guide }}/license/index.html",
- "exclude": true,
- "children": {% readj license/toc.json %} },
-{ "title": "Meta",
- "file": "{{ site.path.guide }}/meta/versions.html",
- "exclude": true,
- "children": {% readj meta/toc.json %} }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/api/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/api/index.md b/docs/guide/use/api/index.md
deleted file mode 100644
index c44b6e3..0000000
--- a/docs/guide/use/api/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-layout: guide-normal
-title: API Reference
-toc: ../../toc.json
----
-
-*Javadoc is not available as part of this build.*
-
-Please see the [source code]({{site.path.guide}}/dev/code) to view javadoc.
-
-<!-- This page is normally overwritten by generated javadoc. -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/contact.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/contact.md b/docs/guide/use/contact.md
deleted file mode 100644
index 622cf0a..0000000
--- a/docs/guide/use/contact.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: guide-normal
-title: Contact
-toc: ../toc.json
----
-
-{% readj ../meta/contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/before-begin.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/before-begin.include.md b/docs/guide/use/examples/before-begin.include.md
deleted file mode 100644
index e05f9f1..0000000
--- a/docs/guide/use/examples/before-begin.include.md
+++ /dev/null
@@ -1,56 +0,0 @@
-{% 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/a7a317bf/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
deleted file mode 100644
index c34217f..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
deleted file mode 100644
index f47226a..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/console-map-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map-w700.png b/docs/guide/use/examples/global-web-fabric/console-map-w700.png
deleted file mode 100644
index af353a9..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-map-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/console-map.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map.png b/docs/guide/use/examples/global-web-fabric/console-map.png
deleted file mode 100644
index cd0f811..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-map.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
deleted file mode 100644
index 33c811d..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
deleted file mode 100644
index 4e743e3..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/examples/global-web-fabric/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/index.md b/docs/guide/use/examples/global-web-fabric/index.md
deleted file mode 100644
index b59eae0..0000000
--- a/docs/guide/use/examples/global-web-fabric/index.md
+++ /dev/null
@@ -1,378 +0,0 @@
----
-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:
-
-[](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:
-
-[](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:
-
-[](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/a7a317bf/docs/guide/use/examples/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/index.md b/docs/guide/use/examples/index.md
deleted file mode 100644
index f55643f..0000000
--- a/docs/guide/use/examples/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/messaging/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/messaging/index.md b/docs/guide/use/examples/messaging/index.md
deleted file mode 100644
index c3c2254..0000000
--- a/docs/guide/use/examples/messaging/index.md
+++ /dev/null
@@ -1,181 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/nosql-cassandra/cassandra.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/nosql-cassandra/cassandra.include.md b/docs/guide/use/examples/nosql-cassandra/cassandra.include.md
deleted file mode 100644
index 56319f8..0000000
--- a/docs/guide/use/examples/nosql-cassandra/cassandra.include.md
+++ /dev/null
@@ -1,282 +0,0 @@
-
-{% 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/a7a317bf/docs/guide/use/examples/nosql-cassandra/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/nosql-cassandra/index.md b/docs/guide/use/examples/nosql-cassandra/index.md
deleted file mode 100644
index 88c1dce..0000000
--- a/docs/guide/use/examples/nosql-cassandra/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/simple-web-cluster.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/simple-web-cluster.md b/docs/guide/use/examples/simple-web-cluster.md
deleted file mode 100644
index cd2b659..0000000
--- a/docs/guide/use/examples/simple-web-cluster.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/toc.json b/docs/guide/use/examples/toc.json
deleted file mode 100644
index 4bca3a1..0000000
--- a/docs/guide/use/examples/toc.json
+++ /dev/null
@@ -1,13 +0,0 @@
-[
-{ "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/a7a317bf/docs/guide/use/examples/webcluster.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/webcluster.md b/docs/guide/use/examples/webcluster.md
deleted file mode 100644
index cd2b659..0000000
--- a/docs/guide/use/examples/webcluster.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/webcluster/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/webcluster/index.md b/docs/guide/use/examples/webcluster/index.md
deleted file mode 100644
index 1fd80dd..0000000
--- a/docs/guide/use/examples/webcluster/index.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-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/a7a317bf/docs/guide/use/examples/webcluster/webcluster.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/webcluster/webcluster.include.md b/docs/guide/use/examples/webcluster/webcluster.include.md
deleted file mode 100644
index e135998..0000000
--- a/docs/guide/use/examples/webcluster/webcluster.include.md
+++ /dev/null
@@ -1,124 +0,0 @@
-
-{% 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/a7a317bf/docs/guide/use/guide/defining-applications/Chef.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/Chef.png b/docs/guide/use/guide/defining-applications/Chef.png
deleted file mode 100644
index d899de2..0000000
Binary files a/docs/guide/use/guide/defining-applications/Chef.png and /dev/null differ
[05/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/advanced-concepts.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/advanced-concepts.md b/docs/guide/use/guide/defining-applications/advanced-concepts.md
deleted file mode 100644
index 25b73ca..0000000
--- a/docs/guide/use/guide/defining-applications/advanced-concepts.md
+++ /dev/null
@@ -1,137 +0,0 @@
----
-title: Advanced Concepts
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-Lifecycle and ManagementContext
--------------------------------
-
-Under-the-covers, at heart of the brooklyn management plane is the ``ManagementContext``.
-This is started automatically when using launching an application using the brooklyn CLI. For programmatic use, see
-``BrooklynLauncher.newLauncher().launch()``.
-
-A Brooklyn deployment consists of many entities in a hierarchical tree, with the privileged *application* entity at the top level.
-
-An application entity (``Application`` class) is responsible for starting the deployment of all its child entities (i.e. the entire entity tree under its ownership).
-
-An ``Application``'s ``start()`` method begins provisioning the child entities of the application (and their entities, recursively).
-
-Provisioning of entities typically happens in parallel automatically,
-although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is visible in the [web-based management console]({{site.path.guide}}/use/guide/management/index.html#console).
-
-Customized provisioning can be useful where two starting entities depend on each other. For example, it is often necessary to delay start of one entity until another entity reaches a certain state, and to supply run-time information about the latter to the former.
-
-<!-- TODO ambiguous language; need a better description of the "manage" lifecycle -->
-When new entities are created, the entity is wired up to an application by giving it a parent. The entity is then explicitly "managed", which allows other entities to discover it.
-
-Typically a Brooklyn deployment has a single management context which records:
-
-* all entities under management that are reachable by the application(s) via the parent-child relationships,
-* the state associated with each entity,
-* subscribers (listeners) to sensor events arising from the entities,
-* active tasks (jobs) associated with any the entity,
-* which Brooklyn management node is mastering (managing) each entity.
-
-<!-- TODO Distributed brooklyn not yet supported; needs clarification in docs -->
-
-In a multi-location deployment, management operates in all regions, with brooklyn entity instances being mastered in the relevant region.
-
-When management is distributed a Brooklyn deployment may consist of multiple Brooklyn management nodes each with a ``ManagementContext`` instance.
-
-<!-- TODO - Clarify the following statements.
-The management context entity forms part of the management plane.
-The management plane is responsible for the distribution of the ``Entity`` instances across multiple machines and multiple locations,
-tracking the transfer of events (subscriptions) between ``Entity`` instances, and the execution of tasks (often initiated by management policies).
--->
-
-<a name="dependent"></a>
-Dependent Configuration
------------------------
-
-Under the covers Brooklyn has a sophisticated sensor event and subscription model, but conveniences around this model make it very simple to express cross-entity dependencies. Consider the example where Tomcat instances need to know the URL of a database (or a set of URLs to connect to a Monterey processing fabric, or other entities)
-
-{% highlight java %}
-setConfiguration(UsesJava.JAVA_OPTIONS, ImmutableMap.of("mysql.url",
- attributeWhenReady(mysql, MySqlNode.MY_SQL_URL) ))
-{% endhighlight %}
-
-The ``attributeWhenReady(Entity, Sensor)`` call (a static method on the class ``DependentConfiguration``)
-causes the configuration value to be set when that given entity's attribue is ready.
-In the example, ``attributeWhenReady()`` causes the JVM system property ``mysql.url`` to be set to the value of the ``MySqlNode.MY_SQL_URL`` sensor from ``mysql`` when that value is ready. As soon as the database URL is announced by the MySql entity, the configuration value will be available to the Tomcat cluster.
-
-By default "ready" means being *set* (non-null) and, if appropriate, *non-empty* (for collections and strings) or *non-zero* (for numbers). Formally the interpretation of ready is that of "Groovy truth" defined by an ``asBoolean()`` method on the class and in the Groovy language extensions.
-
-You can customize "readiness" by supplying a ``Predicate`` (Google common) or ``Closure`` (Groovy) in a third parameter.
-This evaluates candidate values reported by the sensor until one is found to be ``true``.
-For example, passing ``{ it.size()>=3 }`` as the readiness argument would require at least three management plane URLs.
-
-More information on this can be found in the javadoc for ``DependentConfiguration``,
-along with a few other methods such as ``valueWhenAttributeReady`` which allow post-processing of an attribute value.
-
-Note that if the value of ``CONFIG_KEY`` passed to ``Entity.getConfig`` is a Closure or Task (such as returned by ``attributeWhenReady``),
-the first access of ``Entity.getConfig(CONFIG_KEY)`` will block until the task completes.
-Typically this does the right thing, blocking when necessary to generate the right start-up sequence
-without the developer having to think through the order, but it can take some getting used to.
-Be careful not to request config information until really necessary (or to use non-blocking "raw" mechanisms),
-and in complicated situations be ready to attend to circular dependencies.
-The management console gives useful information for understanding what is happening and resolving the cycle.
-
-Location
---------
-<!-- TODO, Clarify is how geographical location works.
--->
-
-Entities can be provisioned/started in the location of your choice. Brooklyn transparently uses [jclouds](http://www.jclouds.org) to support different cloud providers and to support BYON (Bring Your Own Nodes).
-
-The implementation of an entity (e.g. Tomcat) is agnostic about where it will be installed/started. When writing the application definition specify the location or list of possible locations (``Location`` instances) for hosting the entity.
-
-``Location`` instances represent where they run and indicate how that location (resource or service) can be accessed.
-
-For example, a ``JBoss7Server`` will usually be running in an ``SshMachineLocation``, which contains the credentials and address for sshing to the machine. A cluster of such servers may be running in a ``MachineProvisioningLocation``, capable of creating new ``SshMachineLocation`` instances as required.
-
-<!-- TODO, incorporate the following.
-
-The idea is that you could specify the location as AWS and also supply an image id. You could configure the Tomcat entity accordingly: specify the path if the image already has Tomcat installed, or specify that Tomcat must be downloaded/installed. Entities typically use _drivers_ (such as SSH-based) to install, start, and interact with their corresponding real-world instance.
--->
-
-Policies
---------
-Policies perform the active management enabled by Brooklyn. Entities can have zero or more ``Policy`` instances attached to them.
-
-Policies can subscribe to sensors from entities or run periodically, and
-when they run they can perform calculations, look up other values, and if deemed necessary invoke effectors or emit sensor values from the entity with which they are associated.
-
-Execution
----------
-
-All processing, whether an effector invocation or a policy cycle, are tracked as ***tasks***. This allows several important capabilities:
-
-* active and historic processing can be observed by operators
-* the invocation context is available in the thread, to check entitlement (permissions) and maintain a
-hierarchical causal chain even when operations are run in parallel
-* processing can be managed across multiple management nodes
-
-Some executions create new entities, which can then have tasks associated with them, and the system will record, for example, that a start efector on the new entity is a task associated with that entity, with that task
-created by a task associated with a different entity.
-
-The execution of a typical overall start-up sequence is shown below:
-
-[](brooklyn-flow-websequencediagrams.com.png)
-
-
-## Integration
-
-One vital aspect of Brooklyn is its ability to communicate with the systems it starts. This is abstracted using a ***driver*** facility in Brooklyn, where a
-driver describes how a process or service can be installed and managed using a particular technology.
-
-For example, a ``TomcatServer`` may implement start and other effectors using a ``TomcatSshDriver`` which inherits from ``JavaSoftwareProcessSshDriver`` (for JVM and JMX start confguration), inheriting from ``AbstractSoftwareProcessSshDriver``
-(for SSH scripting support).
-
-Particularly for sensors, some technologies are used so frequently that they are
-packaged as ***feeds*** which can discover their configuration (including from drivers). These include JMX and HTTP (see ``JmxFeed`` and ``HttpFeed``).
-
-Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems. See: [Extras]({{site.path.guide}}/use/guide/extras/index.html).
-
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/archetype.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/archetype.md b/docs/guide/use/guide/defining-applications/archetype.md
deleted file mode 100644
index 4894af7..0000000
--- a/docs/guide/use/guide/defining-applications/archetype.md
+++ /dev/null
@@ -1,64 +0,0 @@
----
-title: Common Usage
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-### Maven Archetype
-
-Brooklyn includes a maven archetype, which can be used to create the project structure for a new application.
-
-This can be done interactively using:
-{% highlight bash %}
-$ mvn archetype:generate
-{% endhighlight %}
-
-The user will be prompted for the archetype to use (i.e. group "io.brooklyn"
-and artifact "brooklyn-archetype-quickstart"), as well as options for the project
-to be created.
-
-Alternatively, all options can be supplied at the command line. For example,
-if creating a project named "autobrick" for "com.acme":
-
-{% highlight bash %}
-$ mvn archetype:generate \
- -DarchetypeGroupId=io.brooklyn \
- -DarchetypeArtifactId=brooklyn-archetype-quickstart \
- -DarchetypeVersion={{ site.brooklyn-version }} \
- -DgroupId=com.acme -DartifactId=autobrick \
- -Dversion=0.1.0-SNAPSHOT \
- -DpackageName=com.acme.autobrick \
- -DinteractiveMode=false
-{% endhighlight %}
-
-This will create a directory with the artifact name (e.g. "autobrick" in the example above).
-Note that if run from a directory containing a pom, it will also modify that pom to add this as a module!
-
-The project will contain an example app. You can run this, and also replace it with your own
-application code.
-
-To build, run the commands:
-
-{% highlight bash %}
-$ cd autobrick
-$ mvn clean install assembly:assembly
-{% endhighlight %}
-
-The assembly command will build a complete standalone distribution archive in `target/autobrick-0.1.0-SNAPSHOT-dist.tar.gz`,
-suitable for redistribution and containing `./start.sh` in the root.
-
-An unpacked equivalent is placed in `target/autobrick-0.1.0-SNAPSHOT-dist`,
-thus you can run the single-node sample locally with:
-
-{% highlight bash %}
-$ cd target/autobrick-0.1.0-SNAPSHOT-dist/autobrick-0.1.0-SNAPSHOT/
-$ ./start.sh launch --single
-{% endhighlight %}
-
-This `start.sh` script has all of the same options as the default `brooklyn` script,
-including `./start.sh help` and the `--location` argument for `launch`,
-with a couple of extra `launch` options for the sample blueprints in the archetype project:
-
-- `./start.sh launch --single` will launch a single app-server instance
-- `./start.sh launch --cluster` will launch a cluster of app-servers
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/basic-concepts.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/basic-concepts.md b/docs/guide/use/guide/defining-applications/basic-concepts.md
deleted file mode 100644
index c9f6645..0000000
--- a/docs/guide/use/guide/defining-applications/basic-concepts.md
+++ /dev/null
@@ -1,95 +0,0 @@
----
-title: Basic Concepts
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-This introduces brooklyn and describes how it simplifies the deployment and management of big applications. It is
-intended for people who are using brooklyn-supported application components (such as web/app servers, data stores)
-to be able to use brooklyn to easily start their application in multiple locations with off-the-shelf management
-policies.
-
-Entities
---------
-
-The central concept in a Brooklyn deployment is that of an ***entity***.
-An entity represents a resource under management, either *base* entities (individual machines or software processes)
-or logical collections of these entities.
-
-Fundamental to the processing model is the capability of entities to be the *parent* of other entities (the mechanism by which collections are formed),
-with every entity having a single parent entity, up to the privileged top-level ***application*** entity.
-
-Entities are code, so they can be extended, overridden, and modified. Entities can have events, operations, and processing logic associated with them, and it is through this mechanism that the active management is delivered.
-
-The main responsibilities of an entity are:
-
-- Provisioning the entity in the given location or locations
-- Holding configuration and state (attributes) for the entity
-- Reporting monitoring data (sensors) about the status of the entity
-- Exposing operations (effectors) that can be performed on the entity
-- Hosting management policies and tasks related to the entity
-
-
-Application, Parent and Membership
--------------------------------------
-
-All entities have a ***parent*** entity, which creates and manages it, with one important exception: *applications*.
-Application entities are the top-level entities created and managed externally, manually or programmatically.
-
-Applications are typically defined in Brooklyn as an ***application descriptor***.
-This is a Java class specifying the entities which make up the application,
-by extending the class ``AbstractApplication``, and specifying how these entities should be configured and managed.
-
-All entities, including applications, can be the parent of other entities.
-This means that the "child" is typically started, configured, and managed by the parent.
-For example, an application may be the parent of a web cluster; that cluster in turn is the parent of web server processes.
-In the management console, this is represented hierarchically in a tree view.
-
-A parallel concept is that of ***membership***: in addition to one fixed parent,
-and entity may be a ***member*** of any number of special entities called ***groups***.
-Membership of a group can be used for whatever purpose is required;
-for example, it can be used to manage a collection of entities together for one purpose
-(e.g. wide-area load-balancing between locations) even though they may have been
-created by different parents (e.g. a multi-tier stack within a location).
-
-
-Configuration, Sensors and Effectors
-------------------------------------
-
-### Configuration
-
-All entities contain a map of config information. This can contain arbitrary values, typically keyed under static ``ConfigKey`` fields on the ``Entity`` sub-class. These values are inherited, so setting a configuration value at the
-application level will make it available in all entities underneath unless it is overridden.
-
-Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its ``start()`` method is invoked), so config values must be set before this occurs.
-
-Configuration values can be specified in a configuration file (``~/.brooklyn/brooklyn.properties``)
-to apply universally, and/or programmatically to a specific entity and its descendants
-by calling `.configure(KEY, VALUE)` in the entity spec when creating it.
-There is also an ``entity.setConfig(KEY, VALUE)`` method.
-
-Additionally, many common configuration parameters are available as "flags" which can be supplied as Strings when constructing
-then entity, in the form
-``EntitySpec.create˙(MyEntity.class).configure("config1", "value1").configure("config2", "value2")``.
-
-Documentation of the flags available for individual entities can normally be found in the javadocs.
-The ``@SetFromFlag`` annotations on ``ConfigKey`` static field definitions
-in the entity's interface is the recommended mechanism for exposing configuration options.
-
-
-### Sensors and Effectors
-
-***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the ``Entity`` subclass.
-
-Sensors can be updated by the entity or associated tasks, and sensors from an entity can be subscribed to by its parent or other entities to track changes in an entity's activity.
-
-Effectors can be invoked by an entity's parent remotely, and the invoker is able to track the execution of that effector. Effectors can be invoked by other entities, but use this functionality with care to prevent too many managers!
-
-An entity consists of a Java interface (used when interacting with the entity) and a Java class. For resilience. it is recommended to store
-the entity's state in attributes (see `getAttribute(AttributeKey)``). If internal fields can be used then the data will be lost on brooklyn
-restart, and may cause problems if the entity is to be moved to a different brooklyn management node.
-
-Next: [Advanced Concepts]({{site.path.guide}}/use/guide/defining-applications/advanced-concepts.html).
-See also: [Management > Sensors and Effectors]({{site.path.guide}}/use/guide/management/index.html#sensors-and-effectors).
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com-w400.png b/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com-w400.png
deleted file mode 100644
index c2b48ba..0000000
Binary files a/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com-w400.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com.png b/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com.png
deleted file mode 100644
index 78eb5c8..0000000
Binary files a/docs/guide/use/guide/defining-applications/brooklyn-flow-websequencediagrams.com.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/chef-blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/chef-blueprints.md b/docs/guide/use/guide/defining-applications/chef-blueprints.md
deleted file mode 100644
index 4f9612a..0000000
--- a/docs/guide/use/guide/defining-applications/chef-blueprints.md
+++ /dev/null
@@ -1,277 +0,0 @@
----
-title: Using Chef in YAML Blueprints
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-This guide describes how Brooklyn entities can be easily created from Chef cookbooks.
-As of this writing (May 2014) some of the integration points are under active development,
-and comments are welcome.
-A plan for the full integration is online [here](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8).
-
-This guide assumes you are familiar with the basics of [creating YAML blueprints](creating-yaml.html).
-
-
-## What you need to know about Chef
-
-Chef works in two different modes, *server* and *solo*. *Server* is where the Chef client talks to a central server
-to retrieve information about its roles, policies and cookbooks (where a cookbook defines how to install and
-configure a particular piece of software). With *solo*, the client works in isolation, therefore its configuration
-and cookbooks must be supplied by another means.
-
-Chef *client* is the Chef agent. This is a Ruby application which is installed on each and every managed host. When
-invoked in server mode, it will contact the Chef server to check for updates to cookbooks and policy; it then "runs"
-the recipes in its run lists, to converge the machine to a known state. In solo mode, it reads the locally-maintained
-cookbooks and policies. The client may be run as a daemon that checks the server regularly, or it could merely be
-run manually when required.
-
-The *policy* is a set of rules on the Chef server. A client starts with a set of *attributes*, which could be as
-simple as its name and a recipe runlist, or which may involve a more complex set of attributes about how it is to be
-configured. The client then augments this with auto-detected metadata - a tool called `ohai` is run that collects
-detailed information about the host. Next, the policy on the server modifies these attributes - overriding some,
-setting defaults for others - to produce a final set of attributes. It is these which are the input to the recipes.
-Finally, the attributes are uploaded to the server where they are stored as metadata for the node, where they can be
-inspected and modified by the system operator.
-
-Also of interest is `knife`, which is the workstation toolkit for Chef. Typically this would be installed on the
-operation engineer's workstation, where it would be used to interact with the Chef server and clients. Of particular
-interest to us is the *bootstrap* operation, which is used for setting up new Chef clients - given a virtual machine,
-it will install the Chef client on it, configure it with enough information to find the Chef server and performs its
-first run, and then kicks off the Chef client for the first time.
-
-There is often a preconception about how a Chef client is bootstrapped; mistakenly, there is the belief that the
-`knife` tool configures the Chef server with information about the client, and the client finds out about itself from
-the server. This is not the case - the bootstrap operation does not involve `knife` talking to the server. Instead,
-`knife` packages up all of the required information and sends it to the client - the client will then introduce
-itself to the server, passing on its configuration.
-
-This diagram summarises the interaction between Brooklyn, the new node, and the various Chef tools. Note that there
-is no interaction between the AMP Server and the Chef Server.
-
-[](Chef.png)
-
-### How Brooklyn interacts with Chef
-
-Brooklyn understands both the *server* and *solo* modes of operation. Server mode utilises the `knife` toolkit, and
-therefore `knife` must be installed onto the AMP server and configured appropriately. Solo mode does not have any
-special requirements; when running in solo mode, Brooklyn will install and configure the Chef client over SSH, just
-like it does most other kinds of entities.
-
-
-## Creating Blueprints from Chef
-
-In a nutshell, a new Chef-based entity can be defined as a service by specifying
-`chef:cookbook_name` as the `service_type`, along with a collection of optional configuration.
-An illustrative example is below:
-
-{% highlight yaml %}
-{% readj example_yaml/mysql-chef-1.yaml %}
-{% endhighlight %}
-
-*This works without any installation: try it now, copying-and-pasting to the Brooklyn console.
-(Don't forget to add your preferred `location: some-cloud` to the spec.)*
-
-We'll now walk through the important constituent parts,
-and then proceed to describing things which can be done to simplify the deployment.
-
-
-### Cookbook Primary Name
-
-The first thing to note is the type definition:
-
- - type: chef:mysql
-
-This indicates that the Chef entity should be used (`brooklyn.entity.chef.ChefEntity`)
-to interpret and pass the configuration,
-and that it should be parameterised with a `brooklyn.chef.cookbook.primary.name` of `mysql`.
-This is the cookbook namespace used by default for determining what to install and run.
-
-
-### Importing Cookbooks
-
-Next we specify which cookbooks are required and where they can be pulled from:
-
- cookbook_urls:
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
-Here, specific versions are being downloaded from the canonical github repository.
-Any URL can be used, so long as it is resolvable on either the target machine or the
-Brooklyn server; this includes `file:` and `classpath:` URLs.
-
-The archive can be ZIP or TAR or TGZ.
-
-The structure of the archive must be that a single folder is off the root,
-and in that folder contains the usual Chef recipe and auxiliary files.
-For example, the archive might contain `mysql-master/recipes/server.rb`.
-Archives such as those above from github match this format.
-The name of that folder does not matter, as often they contain version information.
-When deployed, these will be renamed to match the short name (the key in the `cookbooks_url` map,
-for instance `mysql` or `openssl`).
-
-If Chef server is configured (see below), this section can be omitted.
-
-
-### Launch Run List and Attributes
-
-The next part is to specify the Chef run list and attributes to store when launching the entity:
-
- launch_run_list:
- - mysql::server
-
- launch_attributes:
- mysql:
- server_root_password: p4ssw0rd
- server_repl_password: p4ssw0rd
- server_debian_password: p4ssw0rd
-
-For the `launch_run_list`, you can use either the YAML `- recipe` syntax or the JSON `[ "recipe" ]` syntax.
-
-The `launch_attributes` key takes a map which will be stored against the `node` object in Chef.
-Thus in this example, the parameter `node['mysql']['server_root_password']` required by the mysql blueprint
-is set as specified.
-
-You can of course set many other attributes in this manner, in addition to those that are required!
-
-
-### Simple Monitoring
-
-The final section determines how Brooklyn confirms that the service is up.
-Sophisticated solutions may install monitoring agents as part of the `launch_run_list`,
-with Brooklyn configured to read monitoring information to confirm the launch was successful.
-However for convenience, two common mechanisms are available out of the box:
-
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
-
-If `service_name` is supplied, Brooklyn will check the return code of the `status` command
-run against that service, ensuring it is 0. (Note that this is not universally reliable,
-although it is the same mechanism which Chef typically uses to test status when determining
-whether to start a service. Some services, e.g. postgres, will return 0 even if the service
-is not running.)
-
-If a `pid_file` is supplied, Brooklyn will check whether a process with the PID specified in that
-file is running. This has been selected for mysql because it appears to be more portable:
-the service name varies among OS's: it is `mysqld` on CentOS but `mysql` on Ubuntu!
-
-
-## Making it Simpler: Writing Chef for Blueprints
-
-The example we've just seen shows how existing Chef cookbooks can be
-used as the basis for entities. If you're *writing* the Chef recipes,
-there are a few simple techniques we've established with the Chef community
-which make blueprints literally as simple as:
-
- - type: chef:mysql
- brooklyn.config:
- mysql_password: p4ssw0rd
- pid_file: /var/run/mysqld/mysqld.pid
-
-
-### Some Basic Conventions
-
-* **A `start` recipe**:
- The first step is to provide a `start` recipe in `recipes/start.rb`;
- if no `launch_run_list` is supplied, this is what will be invoked to launch the entity.
- It can be as simple as a one-line file:
-
- include_recipe 'mysql::server'
-
-* **Using `brooklyn.config`**:
- All the `brooklyn.config` is passed to Chef as node attributes in the `node['brooklyn']['config']` namespace.
- Thus if the required attributes in the mysql recipe are set to take a value set in
- `node['brooklyn']['config']['mysql_password']`, you can dispense with the `launch_attributes` section.
-
-
-## Using Chef Server
-
-The examples so far have not required Chef Server, so they will work without any external
-Chef dependencies (besides the built-in install from `https://www.opscode.com/chef/install.sh`
-and the explicitly referenced cookbooks). If you use Chef Server, however, you'll want your
-managed nodes to be integrated with it. This is easy to set up, with a few options:
-
-If you have `knife` set up in your shell environment, the Brooklyn Chef support will use it
-by default. If the recipes are installed in your Chef server, you can go ahead and remove
-the `cookbooks_url` section!
-
-Use of `solo` or `knife` can be forced by setting the `chef_mode` flag (`brooklyn.chef.mode` config key)
-to either of those values. (It defaults to `autodetect`, which will use `knife` if it is on the path and satisfies
-sanity checks).
-
-If you want to specify a different configuration, there are a number of config keys you can use:
-
-* `brooklyn.chef.knife.executableFile`: this should be point to the knife binary to use
-* `brooklyn.chef.knife.configFile`: this should point to the knife configuration to use
-* `brooklyn.chef.knife.setupCommands`: an optional set of commands to run prior to invoking knife,
- for example to run `rvm` to get the right ruby version on the Brooklyn server
-
-If you're interested in seeing the Chef REST API be supported directly (without knife),
-please let us know. We'd like to see this too, and we'll help you along the way!
-
-
-## Tips and Tricks
-
-To help you on your way writing Chef blueprints, here are a handful of pointers
-particularly useful in this context:
-
-* Configuration keys can be inherited from the top-level and accessed using `$brooklyn:component('id').config('key_name')`.
- An example of this is shown in the `mysql-chef.yaml` sample recipe contained in the Brooklyn code base
- and [here](example_yaml/mysql-chef-2.yaml) for convenience.
- Here, `p4ssw0rd` is specified only once and then used for all the attributes required by the stock mysql cookbook.
-
-* Github tarball downloads! You'll have noticed these in the example already, but they are so useful we thought
- we'd call them out again. Except when you're developing, we recommend using specific tagged versions rather than master.
-
-* The usual machine `provisioning.properties` are supported with Chef blueprints,
- so you can set things like `minRam` and `osFamily`
-
-* To see more configuration options, and understand the ones presented here in more detail, see the javadoc or
- the code for the class `ChefConfig` in the Brooklyn code base.
-
-
-## Advanced Chef Integration
-
-### Adding Sensors and Effectors
-
-Custom sensors and effectors can be added using an `entity.initializer` section in the YAML blueprint.
-
-One common pattern is to have sensors which extract information from Ohai.
-Another common pattern is to install a monitoring agent as part of the run list,
-configured to talk to a monitoring store, and then to add a sensor feed which reads data from that store.
-
-On the effector side, you can add SSH-based effectors in the usual way.
-You can also describe additional chef converge targets following the pattern set down in
-`ChefLifecycleEffectorTasks`, making use of conveniences in `ChefSoloTasks` and `ChefServerTasks`,
-or provide effectors which invoke network API's of the systems under management
-(for example to supply the common `executeScript` effector as on the standard `MySqlNode`).
-
-
-### Next Steps: Simpifying sensors and effectors, transferring files, and configuring ports
-
-The Brooklyn-Chef integration is work in progress, with a few open issues we'd still like to add.
-Much of the thinking for this is set forth in the [Google document](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8)
-indicated earlier. If you'd like to work with us to implement these, please let us know.
-
-
-## Reference
-
-A general schema for the supported YAML is below:
-
-```
-- type: chef:cookbook_name
- cookbook_urls:
- cookbook_name: url://for/cookbook.tgz
- dependency1: url://for/dependency1.tgz
- launch_run_list: [ "cookbook_name::start" ]
- launch_attributes: # map of arguments to set in the chef node
- service_name: cookbook_service
- pid_file: /var/run/cookbook.pid
-```
-
-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;
-and then move on to the `DynamicToyMySqlEntiyChef` which starts to look at more sophisticated constructs.
-(Familiarity with BASH and basic Java blueprints may be useful at that stage.)
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/common-usage.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/common-usage.md b/docs/guide/use/guide/defining-applications/common-usage.md
deleted file mode 100644
index a3beed6..0000000
--- a/docs/guide/use/guide/defining-applications/common-usage.md
+++ /dev/null
@@ -1,145 +0,0 @@
----
-title: Common Usage
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-### 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``):
-
-- *Cluster* - a homogeneous collection of entities
-- *Fabric* - a multi-location collection of entities, with one per location; often used with a cluster per location
-- *Stack* - heterogeneous (mixed types of children)
-- *Application* - user's entry point
-
-<!---
-TODO
--->
-
-- *entity spec* defines an entity, so that one or more such entities can be created; often used by clusters/groups to define how to instantiate new children.
-- *entity factories* are often used by clusters/groups to define how to instantiate new children.
-- *traits* (mixins) providing certain capabilities, such as Resizable and Balanceable
-- *Resizable* entities can re-sized dynamically, to increase/decrease the number of child entities.
-- *Movable* entities can be migrated between *balanceable containers*.
-- *Balanceable containers* can contain *movable* entities, where each contained entity is normally associated with
- a piece of work within that container.
-
-### Off-the-Shelf Entities
-
-brooklyn includes a selection of entities already available for use in applications,
-including appropriate sensors and effectors, and in some cases include Cluster and Fabric variants.
-(These are also useful as templates for writing new entities.)
-
-These include:
-
-- **Web**: Tomcat, JBoss, Jetty (external), Play (external); nginx; GeoScaling
-- **Data**: MySQL, Redis, MongoDB, Infinispan, GemFire (external)
-- **Containers**: Karaf
-- **Messaging**: ActiveMQ, Qpid, Rabbit MQ
-- **PaaS**: Cloud Foundry, Stackato; OpenShift
-
-
-### <a id="locations"></a> Off-the-Shelf Locations
-
-<a id="locations"></a>
-
-Brooklyn supports deploying to any machine which admits SSH access, as well as to
-a huge variety of external and on-premise clouds. You can also connect to services,
-or use whatever technique for deployment suits you best (such as Xebia Overthere, in development!).
-
-Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the following:
-
-{% highlight bash %}
-# use this key for localhost (this is the default, although if you have a passphrase you must set it)
-brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa
-
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-
-# use a special key when connecting to public clouds, and a particularly special one for AWS
-brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa
-
-# AWS credentials (when deploying to location jclouds:aws-ec2)
-brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
-brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-
-# credentials for 'geoscaling' service
-brooklyn.geoscaling.username=cloudsoft
-brooklyn.geoscaling.password=xxx
-{% endhighlight %}
-
-These can also be set as environment variables (in the shell) or system properties (java command line).
-(There are also ``BROOKLYN_JCLOUDS_PRIVATE_KEY_FILE`` variants accepted.)
-
-For any jclouds provider you will typically need to set ``identity`` and ``credential``
-in the ``brooklyn.location.jclouds.provider`` namespace.
-
-To deploy to sets of machines with known IP's, assuming you have the credentials,
-use the syntax ``byon:(hosts="user@10.9.1.1,user@10.9.1.2,user@10.9.1.3")``
-(this requires your default private key to have access;
-see the ``prod1`` example below for specifying other credentials).
-
-A wide range of other fields is available, because in the real world sometimes things do get complicated.
-The following is supported from the configuration file (with whatever customization you might want available in code):
-
-- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
- ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``, or other places
- where ``privateKeyFile`` is valid). If you don't like keys, you can just use a plain old ``password``.
-
-- Hardware requirements such as ``minRam`` and ``minCores`` can be supplied, or a ``hardwareId`` (jclouds only)
-
-- Specific Secury Groups can be specified using `securityGroups`, if you want to reuse set of existing ones (jclouds only)
-
-- Specific KeyPair can be specified using `keyPair`, if you want to reuse an existing keypair (jclouds only).
-
-- Specific VM images can be specified using ``imageId`` or ``imageNameRegex`` (jclouds only)
-
-- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"`` (jclouds only)
-
-- A ``user`` can be specified, with the property that -- in a jclouds world -- the user will be *created* on the machine,
- with admin rights, authorizing the relevant public key (corresponding to the private key, or as described below).
- Login for the root account will be disabled, as will login by password if a public key is supplied.
- (This is skipped if ``user`` is the ``root`` or other initial login user.)
-
-- You can specify the user account to use to login to jclouds initially with the ``loginUser`` property.
- Typically this is auto-detected by jclouds
- (often ``root``, or ``ubuntu`` or ``ec2-user`` for known Ubuntu or Amazon Linux images),
- but the strategy isn't foolproof, particularly in some private cloud setups. (jclouds only). In some cases, you may need to specify a `loginUser.privateKeyFile` if the image you are using doesn't allow ssh password login.
-
-- Public keys can be specified using ``publicKeyFile``,
- although these can usually be omitted if they follow the common pattern of being
- the private key file with the suffix ``.pub`` appended.
- (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
- or might not even have, the private key of the ``root`` user in order to log in.)
-
-- You can specify the number of attempts Brooklyn should make to create
- machines with ``machineCreateAttempts`` (jclouds only). This is useful for
- working around the rare occasions in which cloud providers give machines that
- are dead on arrival.
-
-You can also define named locations for commonly used groups of properties,
-with the syntax ``brooklyn.location.named.your-group-name.``
-followed by the relevant properties.
-These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment location.
-
-Some more advanced examples showing the syntax and properties above are as follows:
-
-{% highlight bash %}
-# Production pool of machines for my application (deploy to named:prod1)
-brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-brooklyn.location.named.prod1.user=produser1
-brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
-brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
-
-# AWS using my company's credentials and image standard, then labelling images so others know they're mine
-brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
-brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU
-brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
-brooklyn.location.named.company-jungle.imageId=ami-12345
-brooklyn.location.named.company-jungle.minRam=2048
-brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
-brooklyn.location.named.company-jungle.machineCreateAttempts=2
-{% endhighlight %}
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/creating-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/creating-yaml.md b/docs/guide/use/guide/defining-applications/creating-yaml.md
deleted file mode 100644
index 3cbd532..0000000
--- a/docs/guide/use/guide/defining-applications/creating-yaml.md
+++ /dev/null
@@ -1,417 +0,0 @@
----
-title: Writing YAML Blueprints
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-## A First Blueprint
-
-The easiest way to write a blueprint is as a YAML file.
-This follows the <a href="https://www.oasis-open.org/committees/camp/">OASIS CAMP</a> plan specification,
-with some extensions described below.
-(A [YAML reference](yaml-reference.html) has more information,
-and if the YAML doesn't yet do what you want,
-it's easy to add new extensions using your favorite JVM language.)
-
-### The Basic Structure
-
-Here's a very simple YAML blueprint plan, to explain the structure:
-
-{% highlight yaml %}
-{% readj example_yaml/simple-appserver.yaml %}
-{% endhighlight %}
-
-* The `name` is just for the benefit of us humans.
-
-* The `location` specifies where this should be deployed.
- If you've [set up passwordless localhost SSH access]({{ site.path.guide }}/use/guide/locations/)
- you can use `localhost` as above, but if not, just wait ten seconds for the next example.
-
-* The `services` block takes a list of the typed services we want to deploy.
- This is the meat of the blueprint plan, as you'll see below.
-
-Finally, that clipboard in the corner lets you easily copy-and-paste into the web-console:
-simply [download and launch]({{ site.path.guide }}/use/guide/quickstart/) Brooklyn,
-then in the "Add Application" dialog at the web console
-(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/).
-There are several other ways to deploy, including `curl` and via the command-line,
-and you can configure https and security, and much more, as described [here](deploying-yaml.html).
-
-[](web-console-yaml.png)
-
-
-### Setting Locations
-
-Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience for testing.
-With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and cloud platforms are supported.
-The following example is for Amazon EC2:
-
-{% highlight yaml %}
-{% readj example_yaml/simple-appserver-with-location.yaml %}
-{% endhighlight %}
-
-(You'll need to replace the `identity` and `credential` with the
-"Access Key ID" and "Secret Access Key" for your account,
-as configured in the [AWS Console](https://console.aws.amazon.com/iam/home?#security_credential).)
-
-Other popular public clouds include `softlayer`, `google-compute-engine`, and `rackspace-cloudservers-us`.
-Private cloud systems including `openstack-nova` and `cloudstack` are also supported,
-although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/`
-(or `client/api/` in the case of CloudStack) instead of the `region`.
-
-You can also specify pre-existing servers to use -- "bring-your-own-nodes".
-These can be a global pool or specific to a service.
-Both styles are shown here (though normally only one will be selected,
-<!-- TODO see #1377, currently it is *parent* location which is preferred typically -->
-depending on the blueprint):
-
-{% highlight yaml %}
-{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
-{% endhighlight %}
-
-You'll also note in this example that we've used JSON-style notation in the second `location` block.
-YAML supports this, and sometimes that makes more readable plans.
-(Although in this case a simple `location: localhost` is equivalent and even more succinct, but this is a tutorial.)
-
-For more information see the Locations section of the [YAML reference](yaml-reference.html)
-and in the [User's Guide]({{ site.path.guide }}/use/guide/locations/).
-Another good reference is the [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties),
-which if you install in `~/.brooklyn/brooklyn.properties` and edit with your credentials,
-allows you to refer to clouds simply as `location: jclouds:aws-ec2:eu-west-1` or
-set up "named locations" you can use as `location: named:my_cloudstack`.
-
-
-## Configuring VMs
-
-Another simple blueprint will just create a VM which you can use, without any software installed upon it:
-
-{% highlight yaml %}
-{% readj example_yaml/simple-vm.yaml %}
-{% endhighlight %}
-
-
-*We've omitted the `location` section here and in many of the examples below;
-add the appropriate choice when you paste your YAML. Note that the `provisioning.properties` will be
-ignored if deploying to `localhost` or `byon` fixed-IP machines.*
-
-This will create a VM with the specified parameters in your choice of cloud.
-In the GUI (and in the REST API), the entity is called "VM",
-and the hostname and IP address(es) are reported as [sensors]({{ site.path.guide }}/use/guide/defining-applications/basic-concepts.html).
-There are many more `provisioning.properties` supported here,
-including:
-
-* a `user` to create (if not specified it creates the same username as `brooklyn` is running under)
-* a `password` for him or a `publicKeyFile` and `privateKeyFile` (defaulting to keys in `~/.ssh/id_rsa{.pub,}` and no password,
- so if you have keys set up you can immediately ssh in!)
-* `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!)
-* and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp` for private clouds)
-
-For more information, see the javadoc on `JcloudsLocationConfig`.
-
-
-### Clusters, Specs, and Composition
-
-What if you want multiple machines?
-
-One way is just to repeat the `- type: brooklyn.entity.basic.EmptySoftwareProcess` block,
-but there's another way which will keep your powder [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself):
-
-{% highlight yaml %}
-{% readj example_yaml/cluster-vm.yaml %}
-{% endhighlight %}
-
-Here we've composed the previous blueprint introducing some new important concepts, the `DynamicCluster`
-the `$brooklyn` DSL, and the "entity-spec". Let's unpack these.
-
-The `DynamicCluster` creates a set of homogeneous instances.
-At design-time, you specify an initial size and the specification for the entity it should create.
-At runtime you can restart and stop these instances as a group (on the `DynamicCluster`) or refer to them
-individually. You can resize the cluster, attach enrichers which aggregate sensors across the cluster,
-and attach policies which, for example, replace failed members or resize the cluster dynamically.
-
-The specification is defined in the `memberSpec` key. As you can see it looks very much like the
-previous blueprint, with one extra line. Entries in the blueprint which start with `$brooklyn:`
-refer to the Brooklyn DSL and allow a small amount of logic to be embedded
-(if there's a lot of logic, it's recommended to write a blueprint YAML plugin or write the blueprint itself
-as a plugin, in Java or a JVM-supported language).
-
-In this case we want to indicate that the parameter to `memberSpec` is an entity specification
-(`EntitySpec` in the underlying type system); the `entitySpec` DSL command will do this for us.
-The example above thus gives us 5 VMs identical to the one we created in the previous section.
-
-
-## A Bigger Blueprint
-
-We've seen the configuration of machines and how to build up clusters.
-Now let's return to our app-server example and explore how more interesting
-services can be configured, composed, and combined.
-
-Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html)
-covering clusters, sensors, effectors and more,
-if you're the kind of person who likes to learn more about concepts before seeing them in action.
-
-
-### Service Configuration
-
-We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured.yaml %}
-{% endhighlight %}
-
-(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.)
-
-When this is deployed, you can see management information in the Brooklyn Web Console,
-including a link to the deployed application (downloaded to the target machine from the `hello-world` URL),
-running on port 8080.
-
-**Top tip**: If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080;
-the actual port will be reported as a sensor by Brooklyn.
-
-It's also worth indicating an alternate, more formal syntax.
-Not all configuration on entities is supported at the top level of the service specification
-(only those which are defined as "flags" in the underlying blueprint,
-e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
-All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not
-explicitly defined, by placing it into a `brooklyn.config` section:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured-in-config.yaml %}
-{% endhighlight %}
-
-
-
-### Multiple Services and Dependency Injection
-
-If you explored the `hello-world-sql` application we just deployed,
-you'll have noticed it tries to access a database.
-And it fails, because we have not set one up. Let's do that now:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db.yaml %}
-{% endhighlight %}
-
-Here there are a few things going on:
-
-* We've added a second service, which will be the database;
- you'll note the database has been configured to run a custom setup script
-* We've injected the URL of the second service into the appserver as a Java system property
- (so our app knows where to find the database)
-
-**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
-All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
-
-There are as many ways to do dependency injection as there are developers,
-it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
-but to support the various mechanisms people might need to do, for whatever reasons.
-(We each have our opinions about what works well, of course;
-the one thing we do want to call out is that being able to dynamically update
-the injection is useful in a modern agile application -- so we are definitively **not**
-recommending this Java system property approach ... but it is an easy one to demo!)
-
-The way the dependency injection works is again by using the `$brooklyn:` DSL,
-this time referring to the `component("db")` (looked up by the `id` field on our DB component),
-and then to a sensor emitted by that component.
-All the database entities emit a `database.url` sensor when they are up and running;
-the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under the covers)
-in the Java system properties map which the JBoss entity reads at launch time, blocking if needed.
-
-This means that the deployment occurs in parallel, and if the database comes up first,
-there is no blocking; but if the JBoss entity completes its installation and
-downloading the WAR, it will wait for the database before it launches.
-At that point the URL is injected, first passing it through `formatString`
-to include the credentials for the database (which are defined in the database creation script).
-
-
-
-### An Aside: Substitutability
-
-Don't like JBoss? Is there something about Maria?
-One of the modular principles we follow in Brooklyn is substitutability:
-in many cases, the config keys, sensors, and effectors are defined
-in superclasses and are portable across multiple implementations.
-
-Here's an example deploying the same application but with different flavors of the components:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
-{% endhighlight %}
-
-We've also brought in the `provisioning.properties` from the VM example earlier
-so our database has 8GB RAM.
-Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.
-
-
-### Clusters and Policies
-
-Now let's bring the concept of the "cluster" back in.
-We could wrap our appserver in the same `DynamicCluster` we used earlier,
-although then we'd need to define and configure the load balancer.
-But another blueprint, the `ControlledDynamicWebAppCluster`, does this for us.
-It takes the same `memberSpec`, so we can build a fully functional elastic 3-tier
-deployment of our `hello-world-sql` application as follows:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-clustered-w-db.yaml %}
-{% endhighlight %}
-
-This sets up Nginx as the controller by default, but that can be configured
-using the `controllerSpec` key. In fact, JBoss is the default appserver,
-and because configuration in Brooklyn is inherited by default,
-the same blueprint can be expressed more concisely as:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-clustered-w-db-concise.yaml %}
-{% endhighlight %}
-
-The other nicety supplied by the `ControlledDynamicWebAppCluster` blueprint is that
-it aggregates sensors from the appserver, so we have access to things like
-`webapp.reqs.perSec.windowed.perNode`.
-These are convenient for plugging in to policies!
-We can set up our blueprint to do autoscaling based on requests per second
-(keeping it in the range 10..100, with a maximum of 5 appserver nodes)
-as follows:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-policy.yaml %}
-{% endhighlight %}
-
-Use your favorite load-generation tool (`jmeter` is one good example) to send a huge
-volume of requests against the server and see the policies kick in to resize it.
-
-
-## New Custom Entities
-
-So far we've covered how to configure and compose entities.
-There's a large library of blueprints available, but
-there are also times when you'll want to write your own.
-
-For complex use cases, you can write JVM, but for many common situations,
-some of the highly-configurable blueprints make it easy to write in YAML,
-including `bash` and Chef.
-
-
-### Vanilla Software using `bash`
-
-The following blueprint shows how a simple script can be embedded in the YAML
-(the `|` character is special YAML which makes it easier to insert multi-line text):
-
-{% highlight yaml %}
-{% readj example_yaml/vanilla-bash-netcat.yaml %}
-{% endhighlight %}
-
-This starts a simple `nc` listener on port 4321 which will respond `hello` to the first
-session which connects to it. Test it by running `telnet localhost 4321`.
-
-This is just a simple script, but it shows how any script can be easily embedded here,
-including a script to download and run other artifacts.
-Many artifacts are already packaged such that they can be downloaded and launched
-with a simple script, and `VanillaSoftwareProcess` can also be used for them.
-We can specify a `download.url` which downloads artifacts (unpacking TAR, TGZ, and ZIP archives)
-before running `launch.command` relative to where that file is installed (or unpacked),
-with `./start.sh` being the default `launch.command`.
-
-So if we create a file `/tmp/netcat-server.tgz` containing just `start.sh` in the root
-which consists of the two lines in the previous example,
-we can instead write our example as:
-
-{% highlight yaml %}
-{% readj example_yaml/vanilla-bash-netcat-file.yaml %}
-{% endhighlight %}
-
-The one requirement of the script is that it store the process ID (PID) in the file
-pointed to by `$PID_FILE`, hence the second line of the script.
-This is because Brooklyn wants to monitor the services under management.
-(There are other options; you can set `checkRunning.command` and `stop.command` instead,
-as documented on the Javadoc of the `VanillaSoftwareProcess` class,
-and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`.)
-
-And indeed, once you've run one `telnet` to the server, you'll see that the
-service has gone "on fire" in Brooklyn -- because the `nc` process has stopped.
-Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate
-action. A simple recovery here might just be to restart the process:
-
-{% highlight yaml %}
-{% readj example_yaml/vanilla-bash-netcat-restarter.yaml %}
-{% endhighlight %}
-
-Autonomic management in Brooklyn often follows the principle that complex behaviours emerge
-from composing simple policies.
-The blueprint above uses one policy to triggering a failure sensor when the service is down,
-and another responds to such failures by restarting the service.
-This makes it easy to configure various aspects, such as to delay to see if the service itself recovers
-(which here we've set to 15 seconds) or to bail out on multiple failures within a time window (which again we are not doing).
-Running with this blueprint, you'll see that the service shows as on fire for 15s after a `telnet`,
-before the policy restarts it.
-
-For an even more interesting way to test it, look at the blueprint defining
-[a netcat server and client](example_yaml/vanilla-bash-netcat-w-client.yaml).
-This uses `initializers` to define an effector to `sayHiNetcat` on the `Simple Pinger` client,
-using `env` variables to inject the `netcat-server` location and
-`parameters` to pass in per-effector data:
-
- env:
- TARGET_HOSTNAME: $brooklyn:component("netcat-server").attributeWhenReady("host.name")
- brooklyn.initializers:
- - type: brooklyn.entity.software.ssh.SshCommandEffector
- brooklyn.config:
- name: sayHiNetcat
- description: Echo a small hello string to the netcat entity
- command: |
- echo $message | nc $TARGET_HOSTNAME 4321
- parameters:
- message:
- description: The string to pass to netcat
- defaultValue: hi netcat
-
-This blueprint also uses initializers to define sensors on the `netcat-server` entity
-so that the `$message` we passed above gets logged and reported back:
-
- launch.command: |
- echo hello | nc -l 4321 >> server-input &
- echo $! > $PID_FILE
- brooklyn.initializers:
- - type: brooklyn.entity.software.ssh.SshCommandSensor
- brooklyn.config:
- name: output.last
- command: tail -1 server-input
-
-This is still a simple example, but worth going through carefully.
-It shows many of the building blocks used in real-world blueprints,
-and how they can often be easily described and combined in Brooklyn YAML blueprints.
-Next, if you need to drive off-piste, or you want to write tests against these blueprints,
-have a look at, for example, `VanillaBashNetcatYamlTest.java` in the Brooklyn codebase,
-or follow the other references below.
-
-<!--
-TODO building up children entities
-
--->
-
-<!--
-
-### Using Chef Recipes
-
-TODO
-
--->
-
-
-### More Information
-
-Plenty of examples of blueprints exist in the Brooklyn codebase,
-so a good starting point is to [`git clone`]({{ site.path.guide }}/dev/code/index.html) it
-and search for `*.yaml` files therein.
-
-Brooklyn lived as a Java framework for many years before we felt confident
-to make a declarative front-end, so you can do pretty much anything you want to
-by dropping to the JVM. Information on that is available:
-* in the [user guide]({{site.path.guide}}/use/guide/entities/index.html),
-* through a [Maven archetype]({{site.path.guide}}/use/guide/defining-applications/archetype.html),
-* in the [codebase](https://github.com/apache/incubator-brooklyn),
-* and in plenty of [examples]({{site.path.guide}}/use/examples/index.html).
-
-You can also come talk to us, on IRC (#brooklyncentral on Freenode) or
-any of the usual [hailing frequencies]({{site.path.guide}}/meta/contact.html),
-as these documents are a work in progress.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/deploying-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/deploying-yaml.md b/docs/guide/use/guide/defining-applications/deploying-yaml.md
deleted file mode 100644
index a57e5c8..0000000
--- a/docs/guide/use/guide/defining-applications/deploying-yaml.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: Deploying YAML Blueprints
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, defining-applications]
----
-
-Once you've [written a YAML blueprint](creating-yaml.md), there are several ways to deploy it.
-These insructions assume you have [installed]({{ site.path.guide }}/use/guide/quickstart/) Brooklyn.
-You can then:
-
-- Supply the YAML blueprint file on the CLI when launching the server:
-
-{% highlight bash %}
-$ brooklyn launch --app ./blueprint.yaml
-{% endhighlight %}
-
-
-Or, assuming you've launched a server already
-(usually on [http://127.0.0.1/](http://127.0.0.1/) unless you've
-configured security in [`brooklyn.properties`](/use/guide/quickstart/brooklyn.properties)),
-you can:
-
-- Curl it to the Brooklyn REST API:
-
-{% highlight bash %}
-$ curl -T ./blueprint.yaml -X POST http://localhost:8081/v1/applications
-{% endhighlight %}
-
-
-- In the web-console, select the "YAML" tab in the "Add Application" wizard:
-
-[](web-console-yaml.png)
-
-
-- The web-console also has an interactive "REST API" page,
- where you can paste the YAML for uploading into the `POST` to `/v1/applications`.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_files/tomcat_multi-location.java
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_files/tomcat_multi-location.java b/docs/guide/use/guide/defining-applications/example_files/tomcat_multi-location.java
deleted file mode 100644
index cb92766..0000000
--- a/docs/guide/use/guide/defining-applications/example_files/tomcat_multi-location.java
+++ /dev/null
@@ -1,15 +0,0 @@
-// TODO Untested code; see brooklyn-example for better maintained examples!
-public class TomcatFabricApp extends AbstractApplication {
- @Override
- public void init() {
- addChild(EntitySpec.create(DynamicFabric.class)
- .configure("displayName", "WebFabric")
- .configure("displayNamePrefix", "")
- .configure("displayNameSuffix", " web cluster")
- .configure("memberSpec", EntitySpec.create(ControlledDynamicWebAppCluster.class)
- .configure("initialSize", 2)
- .configure("memberSpec", : EntitySpec.create(TomcatServer.class)
- .configure("httpPort", "8080+")
- .configure("war", "/path/to/booking-mvc.war"))));
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_files/tomcat_nginx.java
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_files/tomcat_nginx.java b/docs/guide/use/guide/defining-applications/example_files/tomcat_nginx.java
deleted file mode 100644
index 20db33d..0000000
--- a/docs/guide/use/guide/defining-applications/example_files/tomcat_nginx.java
+++ /dev/null
@@ -1,17 +0,0 @@
-// TODO Untested code; see brooklyn-example for better maintained examples!
-public class TomcatClusterWithNginxApp extends AbstractApplication {
- @Override
- public void init() {
- addChild(EntitySpec.create(NginxController.class)
- .configure("domain", "brooklyn.geopaas.org")
- .configure("port", "8000+")
- .configure("portNumberSensor", Attributes.HTTP_PORT));
-
- addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
- .configure("controller", nginxController)
- .configure("memberSpec", : EntitySpec.create(TomcatServer.class)
- .configure("httpPort", "8080+")
- .configure("war", "/path/to/booking-mvc.war"))
- .configure("initialSize", 2));
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_files/tomcat_simple.java
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_files/tomcat_simple.java b/docs/guide/use/guide/defining-applications/example_files/tomcat_simple.java
deleted file mode 100644
index 480a333..0000000
--- a/docs/guide/use/guide/defining-applications/example_files/tomcat_simple.java
+++ /dev/null
@@ -1,9 +0,0 @@
-// TODO Untested code; see brooklyn-example for better maintained examples!
-public class TomcatServerApp extends AbstractApplication {
- @Override
- public void init() {
- addChild(EntitySpec.create(TomcatServer.class)
- .configure("httpPort", "8080+")
- .configure("war", "/path/to/booking-mvc.war")));
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml
deleted file mode 100644
index 518f65a..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
-name: appserver-clustered-w-db-concise
-services:
-- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
- initialSize: 2
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
-- type: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: DB HelloWorld Visitors
- brooklyn.config:
- datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db.yaml
deleted file mode 100644
index 10592d8..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-clustered-w-db.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-name: appserver-clustered-w-db
-services:
-- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
- initialSize: 2
- memberSpec:
- $brooklyn:entitySpec:
- type: brooklyn.entity.webapp.jboss.JBoss7Server
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
-- type: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: DB HelloWorld Visitors
- brooklyn.config:
- datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured-in-config.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured-in-config.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured-in-config.yaml
deleted file mode 100644
index 50c1873..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured-in-config.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-name: appserver-configured-in-config
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured.yaml
deleted file mode 100644
index 04ec858..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-configured.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
-name: appserver-configured
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
- war: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- httpPort: 8080
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml
deleted file mode 100644
index 6a4a81d..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-name: appserver-w-db-other-flavor
-services:
-- type: brooklyn.entity.webapp.tomcat.TomcatServer
- name: AppServer HelloWorld
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
-- type: brooklyn.entity.database.mariadb.MariaDbNode
- id: db
- name: DB HelloWorld Visitors
- brooklyn.config:
- datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
- provisioning.properties:
- minRam: 8192
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db.yaml
deleted file mode 100644
index a043f1a..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-db.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
-name: appserver-w-db
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
- name: AppServer HelloWorld
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
-- type: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: DB HelloWorld Visitors
- brooklyn.config:
- datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-policy.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-policy.yaml b/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-policy.yaml
deleted file mode 100644
index cada61f..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/appserver-w-policy.yaml
+++ /dev/null
@@ -1,26 +0,0 @@
-name: appserver-w-policy
-services:
-- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
- initialSize: 1
- memberSpec:
- $brooklyn:entitySpec:
- type: brooklyn.entity.webapp.jboss.JBoss7Server
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
- http.port: 8080+
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
- brooklyn.policies:
- - policyType: brooklyn.policy.autoscaling.AutoScalerPolicy
- brooklyn.config:
- metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode")
- metricLowerBound: 10
- metricUpperBound: 100
- minPoolSize: 1
- maxPoolSize: 5
-- type: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: DB HelloWorld Visitors
- brooklyn.config:
- datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/cluster-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/cluster-vm.yaml b/docs/guide/use/guide/defining-applications/example_yaml/cluster-vm.yaml
deleted file mode 100644
index a0a50da..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/cluster-vm.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-name: cluster-vm
-services:
-- type: brooklyn.entity.group.DynamicCluster
- initialSize: 5
- memberSpec:
- $brooklyn:entitySpec:
- type: brooklyn.entity.basic.EmptySoftwareProcess
- name: VM
- provisioning.properties:
- minRam: 8g
- minCores: 4
- minDisk: 100g
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-1.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-1.yaml b/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-1.yaml
deleted file mode 100644
index bdac530..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-1.yaml
+++ /dev/null
@@ -1,24 +0,0 @@
-name: chef-mysql-sample
-services:
-- type: chef:mysql
-
- cookbook_urls:
- # only needed for chef solo; URL can be local to brooklyn, or github, etc...
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
- launch_run_list: [ "mysql::server" ]
- launch_attributes:
- mysql:
- # these attrs are required by the mysql cookbook under node['mysql']
- server_root_password: p4ssw0rd
- server_repl_password: p4ssw0rd
- server_debian_password: p4ssw0rd
- # many others are attrs are supported by the cookbook and can be passed here...
-
- # how to determine if the process is running and how to kill it
- # (supported options are `service_name` and `pid_file`; normally you should just pick one.
- # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-2.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-2.yaml b/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-2.yaml
deleted file mode 100644
index ced2dbe..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/mysql-chef-2.yaml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: chef-mysql-sample
-services:
-- type: chef:mysql
- id: db
-
- cookbook_urls:
- # only needed for chef solo; URL can be local to brooklyn, or github, etc...
- mysql: https://github.com/opscode-cookbooks/mysql/archive/v4.0.12.tar.gz
- openssl: https://github.com/opscode-cookbooks/openssl/archive/v1.1.0.tar.gz
- build-essential: https://github.com/opscode-cookbooks/build-essential/archive/v1.4.4.tar.gz
-
- launch_run_list: [ "mysql::server" ]
- launch_attributes:
- mysql:
- # these attrs are required by the mysql cookbook under node['mysql']
- server_root_password: $brooklyn:component("db").config("mysql.password")
- server_repl_password: $brooklyn:component("db").config("mysql.password")
- server_debian_password: $brooklyn:component("db").config("mysql.password")
- # many others are attrs are supported by the cookbook and can be passed here...
-
- # how to determine if the process is running and how to kill it
- # (supported options are `service_name` and `pid_file`; normally you should just pick one.
- # here we use the pid_file because the service_name varies, mysql on centos, mysqld on ubuntu!)
- #service_name: mysqld
- pid_file: /var/run/mysqld/mysqld.pid
-
-brooklyn.config:
- mysql.password: p4ssw0rd
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml b/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml
deleted file mode 100644
index 7ba5b0c..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-name: simple-appserver-with-location-byon
-location:
- byon:
- user: brooklyn
- privateKeyFile: ~/.ssh/brooklyn.pem
- hosts:
- - 192.168.0.18
- - 192.168.0.19
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
- location:
- byon: { hosts: [ 127.0.0.1 ] }
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location.yaml b/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location.yaml
deleted file mode 100644
index c241ab2..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver-with-location.yaml
+++ /dev/null
@@ -1,8 +0,0 @@
-name: simple-appserver-with-location
-location:
- jclouds:aws-ec2:
- region: us-east-1
- identity: AKA_YOUR_ACCESS_KEY_ID
- credential: <access-key-hex-digits>
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver.yaml b/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver.yaml
deleted file mode 100644
index 3850b26..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/simple-appserver.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-name: simple-appserver
-location: localhost
-services:
-- type: brooklyn.entity.webapp.jboss.JBoss7Server
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/simple-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/simple-vm.yaml b/docs/guide/use/guide/defining-applications/example_yaml/simple-vm.yaml
deleted file mode 100644
index 149a1b9..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/simple-vm.yaml
+++ /dev/null
@@ -1,8 +0,0 @@
-name: simple-vm
-services:
-- type: brooklyn.entity.basic.EmptySoftwareProcess
- name: VM
- provisioning.properties:
- minRam: 8192mb
- minCores: 4
- minDisk: 100gb
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml b/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml
deleted file mode 100644
index 7950b8c..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-name: Simple Netcat Example From File
-location: localhost
-services:
-- type: brooklyn.entity.basic.VanillaSoftwareProcess
- name: Simple Netcat Server
- download.url: file:///tmp/netcat-server.tgz
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml b/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml
deleted file mode 100644
index 1fd70c3..0000000
--- a/docs/guide/use/guide/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml
+++ /dev/null
@@ -1,20 +0,0 @@
-name: Simple Netcat Example with Restarter Policy
-location: localhost
-services:
-- type: brooklyn.entity.basic.VanillaSoftwareProcess
- id: netcat-server
- name: Simple Netcat Server
- launch.command: |
- echo hello | nc -l 4321 &
- echo $! > $PID_FILE
- brooklyn.enrichers:
- - type: brooklyn.policy.ha.ServiceFailureDetector
- brooklyn.config:
- # wait 15s after service fails before propagating failure
- serviceFailedStabilizationDelay: 15s
- brooklyn.policies:
- - type: brooklyn.policy.ha.ServiceRestarter
- brooklyn.config:
- # repeated failures in a time window can cause the restarter to abort,
- # propagating the failure; a time window of 0 will mean it always restarts!
- failOnRecurringFailuresInThisDuration: 0
[02/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-configured.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-configured.yaml b/docs/guide/yaml/example_yaml/appserver-configured.yaml
new file mode 100644
index 0000000..04ec858
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-configured.yaml
@@ -0,0 +1,5 @@
+name: appserver-configured
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
+ war: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ httpPort: 8080
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-w-db-other-flavor.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-w-db-other-flavor.yaml b/docs/guide/yaml/example_yaml/appserver-w-db-other-flavor.yaml
new file mode 100644
index 0000000..6a4a81d
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-w-db-other-flavor.yaml
@@ -0,0 +1,17 @@
+name: appserver-w-db-other-flavor
+services:
+- type: brooklyn.entity.webapp.tomcat.TomcatServer
+ name: AppServer HelloWorld
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: brooklyn.entity.database.mariadb.MariaDbNode
+ id: db
+ name: DB HelloWorld Visitors
+ brooklyn.config:
+ datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
+ provisioning.properties:
+ minRam: 8192
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-w-db.yaml b/docs/guide/yaml/example_yaml/appserver-w-db.yaml
new file mode 100644
index 0000000..a043f1a
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-w-db.yaml
@@ -0,0 +1,15 @@
+name: appserver-w-db
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
+ name: AppServer HelloWorld
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: DB HelloWorld Visitors
+ brooklyn.config:
+ datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/appserver-w-policy.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/appserver-w-policy.yaml b/docs/guide/yaml/example_yaml/appserver-w-policy.yaml
new file mode 100644
index 0000000..cada61f
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/appserver-w-policy.yaml
@@ -0,0 +1,26 @@
+name: appserver-w-policy
+services:
+- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ initialSize: 1
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: brooklyn.entity.webapp.jboss.JBoss7Server
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+ brooklyn.policies:
+ - policyType: brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode")
+ metricLowerBound: 10
+ metricUpperBound: 100
+ minPoolSize: 1
+ maxPoolSize: 5
+- type: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: DB HelloWorld Visitors
+ brooklyn.config:
+ datastore.creation.script.url: https://github.com/apache/incubator-brooklyn/raw/master/usage/launcher/src/test/resources/visitors-creation-script.sql
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/cluster-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/cluster-vm.yaml b/docs/guide/yaml/example_yaml/cluster-vm.yaml
new file mode 100644
index 0000000..a0a50da
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/cluster-vm.yaml
@@ -0,0 +1,12 @@
+name: cluster-vm
+services:
+- type: brooklyn.entity.group.DynamicCluster
+ initialSize: 5
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: brooklyn.entity.basic.EmptySoftwareProcess
+ name: VM
+ provisioning.properties:
+ minRam: 8g
+ minCores: 4
+ minDisk: 100g
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml b/docs/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
new file mode 100644
index 0000000..7ba5b0c
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
@@ -0,0 +1,12 @@
+name: simple-appserver-with-location-byon
+location:
+ byon:
+ user: brooklyn
+ privateKeyFile: ~/.ssh/brooklyn.pem
+ hosts:
+ - 192.168.0.18
+ - 192.168.0.19
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
+ location:
+ byon: { hosts: [ 127.0.0.1 ] }
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/simple-appserver-with-location.yaml b/docs/guide/yaml/example_yaml/simple-appserver-with-location.yaml
new file mode 100644
index 0000000..c241ab2
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/simple-appserver-with-location.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location
+location:
+ jclouds:aws-ec2:
+ region: us-east-1
+ identity: AKA_YOUR_ACCESS_KEY_ID
+ credential: <access-key-hex-digits>
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/simple-appserver.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/simple-appserver.yaml b/docs/guide/yaml/example_yaml/simple-appserver.yaml
new file mode 100644
index 0000000..3850b26
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/simple-appserver.yaml
@@ -0,0 +1,4 @@
+name: simple-appserver
+location: localhost
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/simple-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/simple-vm.yaml b/docs/guide/yaml/example_yaml/simple-vm.yaml
new file mode 100644
index 0000000..149a1b9
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/simple-vm.yaml
@@ -0,0 +1,8 @@
+name: simple-vm
+services:
+- type: brooklyn.entity.basic.EmptySoftwareProcess
+ name: VM
+ provisioning.properties:
+ minRam: 8192mb
+ minCores: 4
+ minDisk: 100gb
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/vanilla-bash-netcat-file.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/vanilla-bash-netcat-file.yaml b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-file.yaml
new file mode 100644
index 0000000..7950b8c
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-file.yaml
@@ -0,0 +1,6 @@
+name: Simple Netcat Example From File
+location: localhost
+services:
+- type: brooklyn.entity.basic.VanillaSoftwareProcess
+ name: Simple Netcat Server
+ download.url: file:///tmp/netcat-server.tgz
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/vanilla-bash-netcat-restarter.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/vanilla-bash-netcat-restarter.yaml b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-restarter.yaml
new file mode 100644
index 0000000..1fd70c3
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-restarter.yaml
@@ -0,0 +1,20 @@
+name: Simple Netcat Example with Restarter Policy
+location: localhost
+services:
+- type: brooklyn.entity.basic.VanillaSoftwareProcess
+ id: netcat-server
+ name: Simple Netcat Server
+ launch.command: |
+ echo hello | nc -l 4321 &
+ echo $! > $PID_FILE
+ brooklyn.enrichers:
+ - type: brooklyn.policy.ha.ServiceFailureDetector
+ brooklyn.config:
+ # wait 15s after service fails before propagating failure
+ serviceFailedStabilizationDelay: 15s
+ brooklyn.policies:
+ - type: brooklyn.policy.ha.ServiceRestarter
+ brooklyn.config:
+ # repeated failures in a time window can cause the restarter to abort,
+ # propagating the failure; a time window of 0 will mean it always restarts!
+ failOnRecurringFailuresInThisDuration: 0
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
new file mode 100644
index 0000000..50051db
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/vanilla-bash-netcat-w-client.yaml
@@ -0,0 +1,72 @@
+name: Simple Netcat with Client
+
+location: localhost
+
+services:
+
+# the netcat server instance, running in listener mode (-l)
+- type: brooklyn.entity.basic.VanillaSoftwareProcess
+ id: netcat-server
+ name: Simple Netcat Server
+ launch.command: |
+ echo hello | nc -l 4321 >> server-input &
+ echo $! > $PID_FILE
+
+ brooklyn.policies:
+ # restarter and
+ - policyType: brooklyn.policy.ha.ServiceFailureDetector
+ brooklyn.config:
+ # wait 15s after service fails before propagating failure
+ serviceFailedStabilizationDelay: 15s
+ - policyType: brooklyn.policy.ha.ServiceRestarter
+ brooklyn.config:
+ # repeated failures in a time window can cause the restarter to abort,
+ # propagating the failure; a time window of 0 will mean it always restarts!
+ failOnRecurringFailuresInThisDuration: 0
+
+ brooklyn.initializers:
+ # two sensors, recording the data sent to this netcat server:
+
+ - type: brooklyn.entity.software.ssh.SshCommandSensor
+ brooklyn.config:
+ name: output.last
+ command: tail -1 server-input
+
+ - type: brooklyn.entity.software.ssh.SshCommandSensor
+ brooklyn.config:
+ name: output.all
+ command: cat server-input
+
+# a client to hit netcat
+- type: brooklyn.entity.basic.VanillaSoftwareProcess
+ name: Simple Pinger
+
+ # set the hostname of the netcat instance as an env var for the scripts
+ env:
+ TARGET_HOSTNAME: $brooklyn:component("netcat-server").attributeWhenReady("host.name")
+
+ # start/check/stop are no-op
+ launch.command: ""
+ checkRunning.command: ""
+ stop.command: ""
+
+ brooklyn.initializers:
+ # but there is a sample effector which runs nc in client mode
+
+ - type: brooklyn.entity.software.ssh.SshCommandEffector
+ brooklyn.config:
+ name: sayHiNetcat
+ description: Echo a small hello string to the netcat entity
+ command: |
+ echo $message | nc $TARGET_HOSTNAME 4321
+ parameters:
+ message:
+ description: The string to pass to netcat
+ defaultValue: hi netcat
+
+# and add an enricher at the root so all sensors from netcat-server are visible on the root
+brooklyn.enrichers:
+- enricherType: brooklyn.enricher.basic.Propagator
+ brooklyn.config:
+ enricher.producer: $brooklyn:component("netcat-server")
+ enricher.propagating.propagatingAll: true
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/example_yaml/vanilla-bash-netcat.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/example_yaml/vanilla-bash-netcat.yaml b/docs/guide/yaml/example_yaml/vanilla-bash-netcat.yaml
new file mode 100644
index 0000000..d4cb37b
--- /dev/null
+++ b/docs/guide/yaml/example_yaml/vanilla-bash-netcat.yaml
@@ -0,0 +1,18 @@
+name: Simple Netcat Server Example
+location: localhost
+services:
+- type: brooklyn.entity.basic.VanillaSoftwareProcess
+ name: Simple Netcat Server
+ launch.command: |
+ echo hello | nc -l 4321 &
+ echo $! > $PID_FILE
+
+ # The following overrides demonstrate the use of a custom shell environment as well as
+ # check-running and stop commands. These are optional; default behavior will "do the
+ # right thing" with the pid file automatically.
+
+ env: { CHECK_MARKER: "checkRunning", STOP_MARKER: "stop" }
+ checkRunning.command: echo $CHECK_MARKER >> DATE && test -f "$PID_FILE" && ps -p `cat $PID_FILE` >/dev/null
+ stop.command: echo $STOP_MARKER >> DATE && test -f "$PID_FILE" && { kill -9 `cat $PID_FILE`; rm /tmp/vanilla.pid; }
+
+# can also define download.url, in which case the launch command defaults to ./start.sh in that (archive) file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/index.md b/docs/guide/yaml/index.md
new file mode 100644
index 0000000..4073f70
--- /dev/null
+++ b/docs/guide/yaml/index.md
@@ -0,0 +1,18 @@
+---
+title: YAML Blueprints
+layout: website-normal
+children:
+- creating-yaml.md
+- setting-locations.md
+- configuring-vms.md
+- clusters.md
+- multiple-services.md
+- clusters-and-policies.md
+- custom-entities.md
+- catalog-maintenance.md
+- chef/
+- { path: yaml-reference.md, title: YAML Blueprint Reference }
+---
+
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/multiple-services.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/multiple-services.md b/docs/guide/yaml/multiple-services.md
new file mode 100644
index 0000000..17e1f04
--- /dev/null
+++ b/docs/guide/yaml/multiple-services.md
@@ -0,0 +1,64 @@
+---
+title: Multiple Services and Dependency Injection
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+If you explored the `hello-world-sql` application we just deployed,
+you'll have noticed it tries to access a database.
+And it fails, because we have not set one up. Let's do that now:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db.yaml %}
+{% endhighlight %}
+
+Here there are a few things going on:
+
+* We've added a second service, which will be the database;
+ you'll note the database has been configured to run a custom setup script
+* We've injected the URL of the second service into the appserver as a Java system property
+ (so our app knows where to find the database)
+
+**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
+All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
+
+There are as many ways to do dependency injection as there are developers,
+it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
+but to support the various mechanisms people might need to do, for whatever reasons.
+(We each have our opinions about what works well, of course;
+the one thing we do want to call out is that being able to dynamically update
+the injection is useful in a modern agile application -- so we are definitively **not**
+recommending this Java system property approach ... but it is an easy one to demo!)
+
+The way the dependency injection works is again by using the `$brooklyn:` DSL,
+this time referring to the `component("db")` (looked up by the `id` field on our DB component),
+and then to a sensor emitted by that component.
+All the database entities emit a `database.url` sensor when they are up and running;
+the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under the covers)
+in the Java system properties map which the JBoss entity reads at launch time, blocking if needed.
+
+This means that the deployment occurs in parallel, and if the database comes up first,
+there is no blocking; but if the JBoss entity completes its installation and
+downloading the WAR, it will wait for the database before it launches.
+At that point the URL is injected, first passing it through `formatString`
+to include the credentials for the database (which are defined in the database creation script).
+
+
+
+### An Aside: Substitutability
+
+Don't like JBoss? Is there something about Maria?
+One of the modular principles we follow in Brooklyn is substitutability:
+in many cases, the config keys, sensors, and effectors are defined
+in superclasses and are portable across multiple implementations.
+
+Here's an example deploying the same application but with different flavors of the components:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
+{% endhighlight %}
+
+We've also brought in the `provisioning.properties` from the VM example earlier
+so our database has 8GB RAM.
+Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/mutlitple-services.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/mutlitple-services.md b/docs/guide/yaml/mutlitple-services.md
new file mode 100644
index 0000000..b5dfe34
--- /dev/null
+++ b/docs/guide/yaml/mutlitple-services.md
@@ -0,0 +1,100 @@
+---
+title: Multiple Services and Dependency Injection
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+We've seen the configuration of machines and how to build up clusters.
+Now let's return to our app-server example and explore how more interesting
+services can be configured, composed, and combined.
+
+Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html)
+covering clusters, sensors, effectors and more,
+if you're the kind of person who likes to learn more about concepts before seeing them in action.
+
+
+### Service Configuration
+
+We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured.yaml %}
+{% endhighlight %}
+
+(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.)
+
+When this is deployed, you can see management information in the Brooklyn Web Console,
+including a link to the deployed application (downloaded to the target machine from the `hello-world` URL),
+running on port 8080.
+
+**Top tip**: If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080;
+the actual port will be reported as a sensor by Brooklyn.
+
+It's also worth indicating an alternate, more formal syntax.
+Not all configuration on entities is supported at the top level of the service specification
+(only those which are defined as "flags" in the underlying blueprint,
+e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
+All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not
+explicitly defined, by placing it into a `brooklyn.config` section:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured-in-config.yaml %}
+{% endhighlight %}
+
+If you explored the `hello-world-sql` application we just deployed,
+you'll have noticed it tries to access a database.
+And it fails, because we have not set one up. Let's do that now:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db.yaml %}
+{% endhighlight %}
+
+Here there are a few things going on:
+
+* We've added a second service, which will be the database;
+ you'll note the database has been configured to run a custom setup script
+* We've injected the URL of the second service into the appserver as a Java system property
+ (so our app knows where to find the database)
+
+**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
+All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
+
+There are as many ways to do dependency injection as there are developers,
+it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
+but to support the various mechanisms people might need to do, for whatever reasons.
+(We each have our opinions about what works well, of course;
+the one thing we do want to call out is that being able to dynamically update
+the injection is useful in a modern agile application -- so we are definitively **not**
+recommending this Java system property approach ... but it is an easy one to demo!)
+
+The way the dependency injection works is again by using the `$brooklyn:` DSL,
+this time referring to the `component("db")` (looked up by the `id` field on our DB component),
+and then to a sensor emitted by that component.
+All the database entities emit a `database.url` sensor when they are up and running;
+the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under the covers)
+in the Java system properties map which the JBoss entity reads at launch time, blocking if needed.
+
+This means that the deployment occurs in parallel, and if the database comes up first,
+there is no blocking; but if the JBoss entity completes its installation and
+downloading the WAR, it will wait for the database before it launches.
+At that point the URL is injected, first passing it through `formatString`
+to include the credentials for the database (which are defined in the database creation script).
+
+
+
+### An Aside: Substitutability
+
+Don't like JBoss? Is there something about Maria?
+One of the modular principles we follow in Brooklyn is substitutability:
+in many cases, the config keys, sensors, and effectors are defined
+in superclasses and are portable across multiple implementations.
+
+Here's an example deploying the same application but with different flavors of the components:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
+{% endhighlight %}
+
+We've also brought in the `provisioning.properties` from the VM example earlier
+so our database has 8GB RAM.
+Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/mysql-in-catalog-w700.png b/docs/guide/yaml/mysql-in-catalog-w700.png
new file mode 100644
index 0000000..f370249
Binary files /dev/null and b/docs/guide/yaml/mysql-in-catalog-w700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/mysql-in-catalog.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/mysql-in-catalog.png b/docs/guide/yaml/mysql-in-catalog.png
new file mode 100644
index 0000000..685455d
Binary files /dev/null and b/docs/guide/yaml/mysql-in-catalog.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/setting-locations.md b/docs/guide/yaml/setting-locations.md
new file mode 100644
index 0000000..6feffe3
--- /dev/null
+++ b/docs/guide/yaml/setting-locations.md
@@ -0,0 +1,44 @@
+---
+title: Setting Locations
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience for testing.
+With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and cloud platforms are supported.
+The following example is for Amazon EC2:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location.yaml %}
+{% endhighlight %}
+
+(You'll need to replace the `identity` and `credential` with the
+"Access Key ID" and "Secret Access Key" for your account,
+as configured in the [AWS Console](https://console.aws.amazon.com/iam/home?#security_credential).)
+
+Other popular public clouds include `softlayer`, `google-compute-engine`, and `rackspace-cloudservers-us`.
+Private cloud systems including `openstack-nova` and `cloudstack` are also supported,
+although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/`
+(or `client/api/` in the case of CloudStack) instead of the `region`.
+
+You can also specify pre-existing servers to use -- "bring-your-own-nodes".
+These can be a global pool or specific to a service.
+Both styles are shown here (though normally only one will be selected,
+<!-- TODO see #1377, currently it is *parent* location which is preferred typically -->
+depending on the blueprint):
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
+{% endhighlight %}
+
+You'll also note in this example that we've used JSON-style notation in the second `location` block.
+YAML supports this, and sometimes that makes more readable plans.
+(Although in this case a simple `location: localhost` is equivalent and even more succinct, but this is a tutorial.)
+
+For more information see the Locations section of the [YAML reference](yaml-reference.html)
+and in the [User's Guide]({{ site.path.guide }}/use/guide/locations/).
+Another good reference is the [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties),
+which if you install in `~/.brooklyn/brooklyn.properties` and edit with your credentials,
+allows you to refer to clouds simply as `location: jclouds:aws-ec2:eu-west-1` or
+set up "named locations" you can use as `location: named:my_cloudstack`.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/web-console-yaml-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/web-console-yaml-700.png b/docs/guide/yaml/web-console-yaml-700.png
new file mode 100644
index 0000000..d6a2249
Binary files /dev/null and b/docs/guide/yaml/web-console-yaml-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/web-console-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/web-console-yaml.png b/docs/guide/yaml/web-console-yaml.png
new file mode 100644
index 0000000..3d65a99
Binary files /dev/null and b/docs/guide/yaml/web-console-yaml.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/yaml/yaml-reference.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/yaml-reference.md b/docs/guide/yaml/yaml-reference.md
new file mode 100644
index 0000000..980b9e3
--- /dev/null
+++ b/docs/guide/yaml/yaml-reference.md
@@ -0,0 +1,181 @@
+---
+title: Broooklyn YAML Blueprint Reference
+layout: website-normal
+---
+
+## Root Elements
+
+* `name`: human readable names
+* `services`: a list of `ServiceSpecification` elements
+* `location` (or `locations` taking a list): a `LocationSpecification` element as a string or a map
+
+
+## `ServiceSpecification` Elements
+
+Within the `services` block, a list of maps should be supplied, with each map
+defining a `ServiceSpecification`. Each `ServiceSpecification` should declare the
+service `type` (synonyms `serviceType` and `service_type`), indicating what type of
+service is being specified there. The following formats are supported for
+defining types:
+
+* `io.brooklyn.package.JavaEntityClass`
+* `java:io.brooklyn.package.JavaEntityClass`
+* *OSGi and YAML references are coming soon!* <!-- TODO -->
+
+A reference of some of the common service `type` instances used is included in a section below.
+
+Within the `ServiceSpecification`, other key-value pairs can be supplied to customize
+the entity being defined, with these being the most common:
+
+* `id`: an ID string, used to refer to this service
+
+* `location` (or `locations`): as defined in the root element
+
+* `brooklyn.config`: configuration key-value pairs passed to the service entity being created
+
+* `brooklyn.children`: a list of `ServiceSpecifications` which will be configured as children of this entity
+
+* `brooklyn.policies`: a list of policies, each as a map described with their `type` and their `brooklyn.config` as keys
+
+* `brooklyn.enrichers`: a list of enrichers, each as a map described with their `type` and their `brooklyn.config` as keys
+
+* `brooklyn.initializers`: a list of `EntityInitializer` instances to be constructed and run against the entity,
+ each as a map described with their `type` and their `brooklyn.config` as keys.
+ An `EntityInitiailzer` can perform arbitrary customization to an entity whilst it is being constructed,
+ such as adding dynamic sensors and effectors. These classes must expose a public constructor taking
+ a single `Map` where the `brooklyn.config` is passed in.
+ Some common initializers are:
+
+ * `brooklyn.entity.software.ssh.SshCommandEffector`: takes a `name` and `command`,
+ and optionally a map of named `parameters` to their `description` and `defaultValue`,
+ to define an effector with the given name implemented by the given SSH command
+ (on an entity which as an ssh-able machine)
+
+ * `brooklyn.entity.software.ssh.SshCommandSensor`: takes a `name` and `command`,
+ and optionally a `period`, to create a sensor feed which populates the sensor with
+ the given name by running the given command (on an entity which as an ssh-able machine)
+
+Entities, policies, and initializers may accept additional key-value pairs,
+usually documented in their documentation (e.g. javadoc), or in the case of Java
+often as static fields in the underlying Java class.
+Often there are config keys or flags (indicated by `@SetFromFlag`) declared on the class;
+these declared flags and config keys may be passed in at the root of the `ServiceSpecification` or in `brooklyn.config`.
+(Undeclared config is only accepted in the `brooklyn.config` map.)
+
+
+## `LocationSpecification` Elements
+
+<!-- TODO - expand this, currently it's concise notes -->
+
+In brief, location specs are supplied as follows, either for the entire application (at the root)
+or for a specific `ServiceSpecification`:
+
+ location:
+ jclouds:aws-ec2:
+ region: us-east-1
+ identity: AKA_YOUR_ACCESS_KEY_ID
+ credential: <access-key-hex-digits>
+
+Or in many cases it can be in-lined:
+
+ location: localhost
+ location: named:my_openstack
+ location: aws-ec2:us-west-1
+
+For the first immediately, you'll need password-less ssh access to localhost.
+For the second, you'll need to define a named location in `brooklyn.properties`,
+using `brooklyn.location.named.my_openstack....` properties.
+For the third, you'll need to have the identity and credentials defined in
+`brooklyn.properties`, using `brooklyn.location.jclouds.aws-ec2....` properties.
+
+If specifying multiple locations, e.g. for a fabric:
+
+ locations:
+ - localhost
+ - named:my_openstack
+ - aws-ec2:us-east-2 # if credentials defined in `brooklyn.properties
+ - jclouds:aws-ec2:
+ region: us-east-1
+ identity: AKA_YOUR_ACCESS_KEY_ID
+ credential: <access-key-hex-digits>
+
+If you have pre-existing nodes, you can use the `byon` provider, either in this format:
+
+ location:
+ byon:
+ user: root
+ privateKeyFile: ~/.ssh/key.pem
+ hosts:
+ - 81.95.144.58
+ - 81.95.144.59
+ - brooklyn@159.253.144.139
+ - brooklyn@159.253.144.140
+
+or:
+
+ location:
+ byon:
+ user: root
+ privateKeyFile: ~/.ssh/key.pem
+ hosts: "{81.95.144.{58,59},brooklyn@159.253.144.{139-140}"
+
+You cannot use glob expansions with the list notation, nor can you specify per-host
+information apart from user within a single `byon` declaration.
+However you can combine locations using `multi`:
+
+ location:
+ multi:
+ targets:
+ - byon:
+ user: root
+ privateKeyFile: ~/.ssh/key.pem
+ hosts:
+ - 81.95.144.58
+ - 81.95.144.59
+ - byon:
+ privateKeyFile: ~/.ssh/brooklyn_key.pem
+ hosts: brooklyn@159.253.144{139-140}
+
+
+## DSL Commands
+
+Dependency injection other powerful references and types can be built up within the YAML using the
+concise DSL defined here:
+
+* `$brooklyn:component("ID")` refers to a Brooklyn component with the given ID; you can then access the following subfields:
+ * `.attributeWhenReady("sensor")` will store a future which will be blocked when it is accessed,
+ until the given `sensor` from the component `ID` has a "truthy" (i.e. non-trivial, non-empty, non-zero) value
+ * `.config("key")` will insert the value set against the given key at this entity (or nearest ancestor);
+ can be used to supply config at the root which is used in multiple places in the plan
+* `$brooklyn:component("scope", "ID")` is also supported, to limit scope to any of
+ * `global`: looks for the `ID` anywhere in the plan
+ * `child`: looks for the `ID` anywhere in the child only
+ * `descendant`: looks for the `ID` anywhere in children or their descendants
+ * `sibling`: looks for the `ID` anywhere among children of the parent entity
+ * `parent`: returns the parent entity (ignores the `ID`)
+ * `this`: returns this entity (ignores the `ID`)
+* `$brooklyn:formatString("pattern e.g. %s %s", "field 1", "field 2")` returns a future which creates the formatted string
+ with the given parameters, where parameters may be strings *or* other tasks such as `attributeWhenReady`
+* `$brooklyn:literal("string")` returns the given string as a literal (suppressing any `$brooklyn:` expansion)
+* `$brooklyn:sensor("io.brooklyn.ContainingEntityClass", "sensor.name")` returns the strongly typed sensor defined in the given class
+* `$brooklyn:entitySpec(Map)` returns a new `ServiceSpecification` as defined by the given `Map`,
+ but as an `EntitySpec` suitable for setting as the value of `ConfigKey<EntitySpec>` config items
+ (such as `memberSpec` in `DynamicCluster`)
+
+These can be supplied either as strings or as lists and maps in YAML.
+
+
+## Some Powerful YAML Entities
+
+All entities support configuration via YAML, but these entities in particular
+have been designed for general purpose use from YAML. Consult the Javadoc for these
+elements for more information:
+
+* **Vanilla Software** in `VanillaSoftwareProcess`: makes it very easy to build entities
+ which use `bash` commands to install and the PID to stop and restart
+* **Chef** in `ChefSoftwareProcess`: makes it easy to use Chef cookbooks to build entities,
+ either with recipes following conventions or with configuration in the `ServiceSpecification`
+ to use artibitrary recipes
+* `DynamicCluster`: provides resizable clusters given a `memberSpec` set with `$brooklyn.entitySpec(Map)` as described above
+* `DynamicFabric`: provides a set of homogeneous instances started in different locations,
+ with an effector to `addLocation`, i.e. add a new instance in a given location, at runtime
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/style/css/base.scss
----------------------------------------------------------------------
diff --git a/docs/style/css/base.scss b/docs/style/css/base.scss
index 8356379..74308df 100644
--- a/docs/style/css/base.scss
+++ b/docs/style/css/base.scss
@@ -23,6 +23,13 @@ img {border: 0;}
a {color: $a_color;}
a:hover {text-decoration: none; color: $a_hover_color;}
+/* Offset link anchors so they are not hidden by the header */
+a[id]:empty, a[name]:empty {
+ padding-top: 60px;
+ margin-top: -60px;
+ display: block;
+}
+
/* WEBSITE MENUS
----------------------------------------------------------------------- */
@@ -64,11 +71,81 @@ a:hover {text-decoration: none; color: $a_hover_color;}
}
.navbar-icon-shift { margin-right: -2px; }
-/* pop-up menu */
+.navbar div.dropdown_section_header hr {
+ margin: 4px 12px;
+ border-color: #ddd;
+}
+
+.navbar div.dropdown_new_section hr {
+ margin: 6px 0px;
+ border-color: #ddd;
+}
+
+/* pop-up top-menu */
ul.nav li.dropdown:hover > ul.dropdown-menu {
display: block;
}
+/* side menu */
+.side-menu {
+ h4.with_following {
+ margin-bottom: 0;
+ }
+ h4.with_preceding {
+ margin-top: 0;
+ }
+ h4.with_following a {
+ border-bottom-right-radius: 0 !important ;
+ border-bottom-left-radius: 0 !important ;
+ border-bottom: 0;
+ }
+ h4.with_preceding a {
+ border-top-right-radius: 0;
+ border-top-left-radius: 0;
+ border-top: 0;
+ }
+ a, a.breadcrumb.breadcrumb0 { padding-left: 15px; }
+ a.breadcrumb.breadcrumb1 { padding-left: 30px; }
+ a.breadcrumb.breadcrumb2 { padding-left: 45px; }
+ a.breadcrumb.breadcrumb3 { padding-left: 60px; }
+ /* further crumbs all get the same */
+ a.breadcrumb { padding-left: 70px; }
+
+ div.sub-item {
+ background-color: #48a648;
+ border-left: 1px solid #428bca;
+ /*
+ border-bottom: 1px solid #428bca;
+ border-top: 1px solid #428bca;
+ border-right: 1px solid #428bca;
+ */
+ /*
+ padding-bottom: 6px;
+ padding-right: 6px;
+ */
+ }
+ div.sub-item:last-child {
+ border-bottom: 1px solid #ddd;
+ border-bottom-left-radius: 4px;
+ border-bottom-right-radius: 4px;
+ }
+ div.sub-item:last-child a.sub-item:last-child {
+ border-bottom-right-radius: 4px !important;
+ }
+ a.with-sub-item {
+ /* border-bottom: 1px solid #ddd; */
+ border-bottom: 0;
+ }
+ a.sub-item {
+ border-radius: 0 !important;
+ border-bottom: 0;
+ margin-left: 12px;
+ padding-left: 10px;
+ padding-top: 8px;
+ padding-bottom: 8px;
+ }
+}
+
/* FOOTER
----------------------------------------------------------------------- */
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/community/how-to-contribute-docs.md
----------------------------------------------------------------------
diff --git a/docs/website/community/how-to-contribute-docs.md b/docs/website/community/how-to-contribute-docs.md
index b6b3cd5..2e29b6b 100644
--- a/docs/website/community/how-to-contribute-docs.md
+++ b/docs/website/community/how-to-contribute-docs.md
@@ -93,7 +93,7 @@ Contributing using GitHub
Our GitHub repository is located at
[https://github.com/apache/incubator-brooklyn](https://github.com/apache/incubator-brooklyn)
-Your commit messages must properly describes the changes that have been made and
+Your commit messages must properly describe the changes that have been made and
their purpose ([here are some
guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)).
If your contributions fix a Jira issue, then ensure that you reference the issue
@@ -130,7 +130,7 @@ set of commits, and having an atomic change per commit is preferred in the end.
Use your best judgement and work with your reviewer as to when you should revise
a commit or create a new one.
-A pull request is considered ready to be merged once it gets at lease one +1
+A pull request is considered ready to be merged once it gets at least one +1
from a committer. Once all the changes have been completed and the pull request
is accepted, you may be asked to rebase it against the latest code. You may also
wish to squash some commits together and make other history revisions, to leave
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/community/how-to-contribute.md
----------------------------------------------------------------------
diff --git a/docs/website/community/how-to-contribute.md b/docs/website/community/how-to-contribute.md
index f73c2fb..0f2ce1e 100644
--- a/docs/website/community/how-to-contribute.md
+++ b/docs/website/community/how-to-contribute.md
@@ -1,7 +1,6 @@
---
layout: website-normal
title: How to Contribute
-navgroup: community
---
Welcome and thank you for your interest in contributing to Apache Brooklyn! This guide will take you through the
@@ -83,3 +82,9 @@ Our canonical repository is located at `https://git-wip-us.apache.org/repos/asf/
When producing patches, please use `git format-patch` or a similar mechanism - this will ensure that you are properly
attributed as the author of the patch when a committer merges it.
+
+
+Handy Places
+------------
+
+Development bookmarks are available [here](links.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/community/links.md
----------------------------------------------------------------------
diff --git a/docs/website/community/links.md b/docs/website/community/links.md
new file mode 100644
index 0000000..20a062d
--- /dev/null
+++ b/docs/website/community/links.md
@@ -0,0 +1,22 @@
+---
+layout: website-normal
+title: Development Bookmarks
+menu_proxy_for: how-to-contribute.md
+---
+
+{% include fields.md %}
+
+Handy places:
+
+* **Code** is in Github at [https://github.com/apache/incubator-brooklyn/](https://github.com/apache/incubator-brooklyn/)
+
+* **Issues** are in Jira at [https://issues.apache.org/jira/browse/BROOKLYN/](https://issues.apache.org/jira/browse/BROOKLYN/)
+
+* **Maven repositories** are:
+ * [Apache releases]({{ apache_releases_repo_groupid_url }})
+ * [Apache snapshots]({{ apache_snapshots_repo_groupid_url }})
+ * Other repositories are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases
+ and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots
+
+* **CI server** is a jenkins server at: [https://builds.apache.org/job/incubator-brooklyn-master-build/](https://builds.apache.org/job/incubator-brooklyn-master-build/)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation.md b/docs/website/documentation.md
deleted file mode 100644
index 4ad3c8e..0000000
--- a/docs/website/documentation.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-layout: website-normal
-title: Documentation
-children:
-- { link: "{{ site.path.guide }}", title: User Guide }
-- { path: glossary.md }
-- { path: documentation/install-on-server.md }
----
-
-## Official User Manual
-
-Our main user manual is organised by release version. Please pick the version that you are using:
-
-- [0.7.0-M1]({{ site.path.v }}/0.7.0-M1) -
- Please note that this release was made prior to entering the Apache Incubator,
- and therefore it is not endorsed by Apache.
-
-## Server install
-Follow this [guide](documentation/install-on-server.html) to install Brooklyn on a production server.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation/faq.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/faq.md b/docs/website/documentation/faq.md
new file mode 100644
index 0000000..25d3864
--- /dev/null
+++ b/docs/website/documentation/faq.md
@@ -0,0 +1,22 @@
+---
+title: FAQ
+layout: website-normal
+---
+
+## What's the difference between Brooklyn and...
+
+#### Chef and Puppet and other server config management tools?
+
+#### Cloudformation and Heat and other infrastructure declarative tools?
+
+#### CloudFoundry and other PaaS platforms?
+
+
+## Why is this page blank?
+
+Supplying the answers are a TODO.
+
+
+## How do I supply answers?
+
+Click the "Edit this Page" link in the bottom right.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation/glossary.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/glossary.md b/docs/website/documentation/glossary.md
new file mode 100644
index 0000000..0651068
--- /dev/null
+++ b/docs/website/documentation/glossary.md
@@ -0,0 +1,92 @@
+---
+layout: website-normal
+title: Glossary
+---
+
+[//]: # (Abusing link groups to write comments that are not rendered in the document..)
+[//]: # (The links below reference the id attributes generated for the headers.)
+[//]: # (For example, the Autonomic section can be referred to with a link to #autonomic.)
+[//]: # (So if you alter any of the headers you should update the relevant link group too.)
+
+[autonomic]: #autonomic
+[blueprint]: #blueprint
+[effector]: #effector
+[entity]: #entity
+[policy]: #policy
+[sensor]: #sensor
+[YAML]: #yaml
+
+[//]: # (Note: Autonomic and blueprint section could link to learnmore page.)
+
+
+#### Autonomic
+
+Refers to the self-managing characteristics of distributed computing resources,
+adapting to unpredictable changes while hiding intrinsic complexity to
+operators and users.
+
+
+#### Blueprint
+
+A description of an application or system, which can be used for its automated
+deployment and runtime management. The blueprint describes a model of the
+application (i.e. its components, their configuration, and their
+relationships), along with policies for runtime management. The blueprint can
+be described in [YAML][].
+
+###### See also
+* [Documentation]({{site.path.website}}/learnmore/catalog/index.html) for the entity,
+ policy and enricher blueprints that Apache Brooklyn supports out-of-the-box.
+
+
+#### Effector
+
+An operation on an [entity][].
+
+
+#### Entity
+
+A component of an application or system. This could be a physical component, a
+service, a grouping of components, or a logical construct describing part of an
+application/system. It is a "managed element" in autonomic computing parlance.
+
+
+#### Policy
+
+Part of an autonomic management system, performing runtime management. A policy
+is associated with an [entity][]; it normally manages the health of that entity
+or an associated group of entities (e.g. HA policies or auto-scaling policies).
+
+
+#### Sensor
+
+An attribute of an [entity][].
+
+
+#### YAML
+
+A human-readable data format.
+
+###### See also
+* [Wikipedia article](http://en.wikipedia.org/wiki/YAML) on YAML
+
+
+#### Apache Jclouds
+
+An open source Java library that provides a consistent interface to many
+clouds. Apache Brooklyn uses Apache Jclouds as its core cloud abstraction.
+
+###### See also
+* [Project homepage](https://jclouds.apache.org/)
+
+
+#### CAMP and TOSCA
+
+OASIS Cloud Application Management for Platforms (CAMP) and OASIS Topology and
+Orchestration Specification for Cloud Applications (TOSCA) are specifications
+that aim to standardise the portability and management of cloud applications.
+
+###### See also
+* [CAMP homepage](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=camp)
+* [TOSCA homepage](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tosca)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation/index.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/index.md b/docs/website/documentation/index.md
new file mode 100644
index 0000000..67aaa9c
--- /dev/null
+++ b/docs/website/documentation/index.md
@@ -0,0 +1,31 @@
+---
+layout: website-normal
+title: Documentation
+children:
+- /guide/
+- /guide/dev/
+- faq.md
+- other-docs.md
+---
+
+{% comment %}
+This is redundant with versions page. Link to versions page? List more things including other docs?
+Basically make this page pretty...
+{% endcomment %}
+
+## Official User Guide
+
+Our main user manual is organised by release version. Please pick the version that you are using:
+
+- [{{ site.brooklyn-stable-version }}]({{ site.path.v }}/latest) -
+ This is the latest stable version.
+
+- [0.7.0-M1]({{ site.path.v }}/0.7.0-M1) -
+ Please note that this release was made prior to entering the Apache Incubator,
+ and therefore it is not endorsed by Apache.
+
+From the links above you can also access the Developer Guide for the relevant versions.
+
+## Other Docs
+
+Many other mini-docs are available [here](other-docs.md).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation/other-docs.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/other-docs.md b/docs/website/documentation/other-docs.md
new file mode 100644
index 0000000..a6d01df
--- /dev/null
+++ b/docs/website/documentation/other-docs.md
@@ -0,0 +1,11 @@
+---
+title: Other Resources
+layout: website-normal
+children:
+- { path: glossary.md }
+- { path: install-on-server.md }
+- { path: ../meta/versions.md }
+- { path: ../meta/sitemap.md }
+---
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/documentation/todo.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/todo.md b/docs/website/documentation/todo.md
new file mode 100644
index 0000000..724cb8c
--- /dev/null
+++ b/docs/website/documentation/todo.md
@@ -0,0 +1,7 @@
+---
+title: TODO
+layout: website-normal
+---
+
+TODO
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/download.md
----------------------------------------------------------------------
diff --git a/docs/website/download.md b/docs/website/download.md
deleted file mode 100644
index 4cd5cdf..0000000
--- a/docs/website/download.md
+++ /dev/null
@@ -1,40 +0,0 @@
----
-layout: website-normal
-title: Download
-children:
-- { path: download/verify.md }
----
-
-## Latest Brooklyn Source Code Release
-
-[Download Apache Brooklyn {{ site.data.brooklyn.version }} from our mirror sites](https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/{{ site.data.brooklyn.version }}/apache-brooklyn-{{ site.data.brooklyn.version }}.tar.gz)
-
-You can also verify that you build has not been tampered with by [verifying the hashes and signatures](download/verify.html).
-
-
-## Build the Binary Package
-
-We do not yet have an official binary package for Apache Brooklyn. We plan to address this in our next release. However,
-it is relatively easy to create the binary package from source code, if you have a working JDK of at least version 6,
-and Maven 3.
-
-Unpack `apache-brooklyn-{{ site.data.brooklyn.version }}.tar.gz` and then execute this command in the `apache-brooklyn-{{ site.data.brooklyn.version }}` folder:
-
-{% highlight bash %}
-mvn clean install -DskipTests
-{% endhighlight %}
-
-You can then find the binary distribution in the folder `usage/dist/target/brooklyn-dist`, or archived as `usage/dist/target/brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz`.
-
-
-## Get Started!
-
-Take a look at the [Get Started](quickstart/) page!
-
-
-## Previous Versions
-
-Versions of Brooklyn prior to 0.7.0-M2 were all made prior to joining the Apache Incubator, therefore **they are not
-endorsed by Apache** and are not hosted by Apache or their mirrors. You can obtain the source code by [inspecting the
-branches of the pre-Apache GitHub repository](https://github.com/brooklyncentral/brooklyn/branches/stale) and binary
-releases by [querying Maven Central for io.brooklyn:brooklyn.dist](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.brooklyn%22%20AND%20a%3A%22brooklyn-dist%22).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/download/index.md
----------------------------------------------------------------------
diff --git a/docs/website/download/index.md b/docs/website/download/index.md
new file mode 100644
index 0000000..690c856
--- /dev/null
+++ b/docs/website/download/index.md
@@ -0,0 +1,40 @@
+---
+layout: website-normal
+title: Download
+children:
+- { path: verify.md }
+---
+
+## Latest Brooklyn Source Code Release
+
+[Download Apache Brooklyn {{ site.data.brooklyn.version }} from our mirror sites](https://www.apache.org/dyn/closer.cgi/incubator/brooklyn/{{ site.data.brooklyn.version }}/apache-brooklyn-{{ site.data.brooklyn.version }}.tar.gz)
+
+You can also verify that you build has not been tampered with by [verifying the hashes and signatures](download/verify.html).
+
+
+## Build the Binary Package
+
+We do not yet have an official binary package for Apache Brooklyn. We plan to address this in our next release. However,
+it is relatively easy to create the binary package from source code, if you have a working JDK of at least version 6,
+and Maven 3.
+
+Unpack `apache-brooklyn-{{ site.data.brooklyn.version }}.tar.gz` and then execute this command in the `apache-brooklyn-{{ site.data.brooklyn.version }}` folder:
+
+{% highlight bash %}
+mvn clean install -DskipTests
+{% endhighlight %}
+
+You can then find the binary distribution in the folder `usage/dist/target/brooklyn-dist`, or archived as `usage/dist/target/brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz`.
+
+
+## Get Started!
+
+Take a look at the [Get Started](quickstart/) page!
+
+
+## Previous Versions
+
+Versions of Brooklyn prior to 0.7.0-M2 were all made prior to joining the Apache Incubator, therefore **they are not
+endorsed by Apache** and are not hosted by Apache or their mirrors. You can obtain the source code by [inspecting the
+branches of the pre-Apache GitHub repository](https://github.com/brooklyncentral/brooklyn/branches/stale) and binary
+releases by [querying Maven Central for io.brooklyn:brooklyn.dist](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.brooklyn%22%20AND%20a%3A%22brooklyn-dist%22).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/glossary.md
----------------------------------------------------------------------
diff --git a/docs/website/glossary.md b/docs/website/glossary.md
deleted file mode 100644
index 0651068..0000000
--- a/docs/website/glossary.md
+++ /dev/null
@@ -1,92 +0,0 @@
----
-layout: website-normal
-title: Glossary
----
-
-[//]: # (Abusing link groups to write comments that are not rendered in the document..)
-[//]: # (The links below reference the id attributes generated for the headers.)
-[//]: # (For example, the Autonomic section can be referred to with a link to #autonomic.)
-[//]: # (So if you alter any of the headers you should update the relevant link group too.)
-
-[autonomic]: #autonomic
-[blueprint]: #blueprint
-[effector]: #effector
-[entity]: #entity
-[policy]: #policy
-[sensor]: #sensor
-[YAML]: #yaml
-
-[//]: # (Note: Autonomic and blueprint section could link to learnmore page.)
-
-
-#### Autonomic
-
-Refers to the self-managing characteristics of distributed computing resources,
-adapting to unpredictable changes while hiding intrinsic complexity to
-operators and users.
-
-
-#### Blueprint
-
-A description of an application or system, which can be used for its automated
-deployment and runtime management. The blueprint describes a model of the
-application (i.e. its components, their configuration, and their
-relationships), along with policies for runtime management. The blueprint can
-be described in [YAML][].
-
-###### See also
-* [Documentation]({{site.path.website}}/learnmore/catalog/index.html) for the entity,
- policy and enricher blueprints that Apache Brooklyn supports out-of-the-box.
-
-
-#### Effector
-
-An operation on an [entity][].
-
-
-#### Entity
-
-A component of an application or system. This could be a physical component, a
-service, a grouping of components, or a logical construct describing part of an
-application/system. It is a "managed element" in autonomic computing parlance.
-
-
-#### Policy
-
-Part of an autonomic management system, performing runtime management. A policy
-is associated with an [entity][]; it normally manages the health of that entity
-or an associated group of entities (e.g. HA policies or auto-scaling policies).
-
-
-#### Sensor
-
-An attribute of an [entity][].
-
-
-#### YAML
-
-A human-readable data format.
-
-###### See also
-* [Wikipedia article](http://en.wikipedia.org/wiki/YAML) on YAML
-
-
-#### Apache Jclouds
-
-An open source Java library that provides a consistent interface to many
-clouds. Apache Brooklyn uses Apache Jclouds as its core cloud abstraction.
-
-###### See also
-* [Project homepage](https://jclouds.apache.org/)
-
-
-#### CAMP and TOSCA
-
-OASIS Cloud Application Management for Platforms (CAMP) and OASIS Topology and
-Orchestration Specification for Cloud Applications (TOSCA) are specifications
-that aim to standardise the portability and management of cloud applications.
-
-###### See also
-* [CAMP homepage](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=camp)
-* [TOSCA homepage](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tosca)
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/index.md
----------------------------------------------------------------------
diff --git a/docs/website/index.md b/docs/website/index.md
index 2892e94..dac0968 100644
--- a/docs/website/index.md
+++ b/docs/website/index.md
@@ -1,19 +1,24 @@
---
layout: website-landing
title: Home
-navgroup: home
+landing: true
children:
-- { path: learnmore/index.md }
-- { path: download.md }
-- { path: quickstart/index.md }
-- { path: documentation.md }
-- { path: community/index.md }
-navgroups:
-- { id: learnmore, page: learnmore/index.md, title: learn more, title_in_menu: Learn More }
-- { id: download, page: download.md, title: download }
-- { id: getstarted, page: quickstart/index.md, title: get started, title_in_menu: Get Started }
-- { id: documentation, page: documentation.md, title: documentation, title_in_menu: All Documentation }
-- { id: community, page: community/index.md, title: community, title_in_menu: Community Home }
+- learnmore/
+- { path: download/, menu: null }
+- { path: /guide/start/running.md, title: Get Started }
+- path: documentation/
+ menu:
+ - { path: /guide/index.md, title_in_menu: "User Guide",
+ menu_customization: { dropdown_section_header: true } }
+ - { path: /guide/yaml/index.md, title_in_menu: YAML Blueprints, href_path: /guide/yaml/creating-yaml.md }
+ - { path: /guide/java/index.md, title_in_menu: Java Blueprints }
+ - { path: /guide/ops/index.md, title_in_menu: Operations,
+ menu_customization: { dropdown_section_header: true } }
+ - { path: /guide/dev/index.md, title_in_menu: Developer Guide }
+ - { path: documentation/faq.md, title_in_menu: FAQ,
+ menu_customization: { dropdown_new_section: true } }
+ - { path: documentation/other-docs.md, title_in_menu: Other Resources }
+- community/
---
<div class="jumbotron">
@@ -63,7 +68,7 @@ View and modify using the *web console* or automate using the *REST API*
<div style="text-align: center" markdown="1">
-<a class="btn btn-primary btn-lg" role="button" href="learnmore.html">learn more</a>
+<a class="btn btn-primary btn-lg" role="button" href="learnmore/">learn more</a>
<a class="btn btn-primary btn-lg" role="button" href="quickstart/">get started</a>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/learnmore/index.md
----------------------------------------------------------------------
diff --git a/docs/website/learnmore/index.md b/docs/website/learnmore/index.md
index b185ace..d2a8998 100644
--- a/docs/website/learnmore/index.md
+++ b/docs/website/learnmore/index.md
@@ -3,7 +3,7 @@ layout: website-normal
title: Learn More
children:
# - { path: yaml-explained.md }
-- { path: theory.md, title: Theory }
+- { path: theory.md, title_in_menu: Theory }
---
<!--
@@ -12,4 +12,5 @@ TODO have a list of resources here? or start w yaml explained?
TODO include { path: catalog/index.html }
-->
-* [The Theory of Brooklyn](theory.html)
+{% include list-children.html %}
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/learnmore/theory.md
----------------------------------------------------------------------
diff --git a/docs/website/learnmore/theory.md b/docs/website/learnmore/theory.md
index 33d9b18..f1c3899 100644
--- a/docs/website/learnmore/theory.md
+++ b/docs/website/learnmore/theory.md
@@ -1,7 +1,6 @@
---
layout: website-normal
title: The Theory behind Brooklyn
-navgroup: learnmore
---
<div class="jumobotron" markdown="1">
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/meta/license.md
----------------------------------------------------------------------
diff --git a/docs/website/meta/license.md b/docs/website/meta/license.md
new file mode 100644
index 0000000..c7f5366
--- /dev/null
+++ b/docs/website/meta/license.md
@@ -0,0 +1,205 @@
+---
+layout: website-normal
+title: Legal
+---
+
+## License
+
+Apache Brooklyn is released to the public as open source under the
+terms of the [Apache License, v2.0](http://www.apache.org/licenses/LICENSE-2.0), a full copy of
+which is included below for reference.
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Apache Brooklyn is currently undergoing Incubation at the Apache Software Foundation.
+
+
+## Trademark
+
+The Brooklyn name and logo are trademarks owned by the Apache Software Foundation.
+
+
+## Apache License, v2.0 (reference copy)
+
+
+{% highlight text %}
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/meta/sitemap.md
----------------------------------------------------------------------
diff --git a/docs/website/meta/sitemap.md b/docs/website/meta/sitemap.md
new file mode 100644
index 0000000..efff2b2
--- /dev/null
+++ b/docs/website/meta/sitemap.md
@@ -0,0 +1,19 @@
+---
+layout: website-normal
+title: Site Map
+---
+
+<!-- TODO this is very much work in progress -->
+
+Site map is:
+
+{% for item in site.data.menu %}
+ * {{ item['title_in_menu'] }} / {{ item.data['title'] }} - {{ item.data }}<br/>
+ {% for item2 in item['menu'] %}
+ * {{ item2['title_in_menu'] }} / {{ item2['path'] }} / {{ item2['link'] }}<br/>
+ {% for item3 in item2['menu'] %}
+ * {{ item3['title_in_menu'] }} / {{ item3['path'] }} / {{ item3['breadcrumbs'] }}<br/>
+ {% endfor %}
+ {% endfor %}
+{% endfor %}
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/website/meta/versions.md b/docs/website/meta/versions.md
new file mode 100644
index 0000000..949e6f6
--- /dev/null
+++ b/docs/website/meta/versions.md
@@ -0,0 +1,71 @@
+---
+layout: website-normal
+title: Versions
+---
+
+### Current Version: {{ site.brooklyn-stable-version }}
+
+The current stable version of Brooklyn is {{ site.brooklyn-stable-version }}:
+
+* [Download]({{ site.path.website }}/download.md)
+* [User Guide]({{ site.path.guide }}/)
+* [Release Notes]({{ site.path.guide }}/start/release-notes.md)
+
+This documentation was generated {{ site.time | date_to_string }}.
+
+
+### Version History
+
+Apache versions:
+
+* **[0.7.0-SNAPSHOT](/v/0.7.0-SNAPSHOT/)**: bleeding-edge (not voted on or endorsed by Apache!)
+
+* **[0.7.0-M2](/v/0.7.0-M2/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (Dec 2014)
+
+
+The versions below were made prior to joining the Apache Incubator,
+therefore **they are not endorsed by Apache** and are not hosted by Apache or their mirrors.
+You can obtain the source code by [inspecting the branches of the pre-Apache GitHub repository](https://github.com/brooklyncentral/brooklyn/branches/stale)
+and binary releases by [querying Maven Central for io.brooklyn:brooklyn.dist](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.brooklyn%22%20AND%20a%3A%22brooklyn-dist%22).
+
+* **[0.6.0](/v/0.6.0/)**: use of spec objects, chef and windows support, more clouds (Nov 2013)
+
+* **[0.5.0](/v/0.5.0/)**: includes new JS GUI and REST API, rebind/persistence support, cleaner model and naming conventions, more entities (May 2013)
+
+* **[0.4.0](/v/0.4.0/)**: initial public GA release of Brooklyn to Maven Central, supporting wide range of entities and examples (Jan 2013)
+
+Note: To prevent accidentally referring to out-of-date information,
+a banner is displayed when accessing content from specific versions in the archive.
+You may
+<a href="#" onclick="set_user_versions_all();">disable all warnings</a> or
+<a href="#" onclick="clear_user_versions();">re-enable all warnings</a>.
+
+
+### Versioning
+
+Brooklyn follows [semantic versioning](http://semver.org/) with a leading `0.` qualifier:
+
+ 0.<major>.<minor>[.<patch>]-<qualifier>
+
+Breaking backward compatibility increments the `<major>` version.
+New additions without breaking backward compatibility ups the `<minor>` version.
+Bug fixes and misc changes bumps the `<patch>` version.
+New major and minor releases zero the less significant counters.
+
+From time to time, the Brooklyn project will make snapshots, milestone releases, and other qualified versions available,
+using the following conventions:
+
+* Milestone versions (`-M<n>`) have been voted on and have been through some QA,
+ but have not had the extensive testing as is done on a release.
+
+* Snapshot (`-SNAPSHOT`) is the bleeding edge.
+ With good test coverage these builds are usually healthy,
+ but they have not been through QA or voted on.
+
+* Nightly builds (`-N<date>`) represent a snapshot which has
+ been given a permanent version number, typically for use by other projects.
+ The same caveats as for snapshot releases apply (no QA or Apache vote).
+
+* Release Candidate builds (`-RC<n>`) are made in the run-up to a release;
+ these should not normally be used except for deciding whether to cut a release.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/_my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/_my-web-cluster.yaml b/docs/website/quickstart/_my-web-cluster.yaml
deleted file mode 100644
index 3b6134b..0000000
--- a/docs/website/quickstart/_my-web-cluster.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-name: My Web Cluster
-location: location
-services:
-
-- serviceType: 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
- java.sysprops:
- brooklyn.example.db.url: >
- $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("datastore.url"),
- "visitors", "brooklyn", "br00k11n")
-
-- serviceType: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: My DB
- brooklyn.config:
- creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/catalog.xml
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/catalog.xml b/docs/website/quickstart/catalog.xml
deleted file mode 100644
index 6cff554..0000000
--- a/docs/website/quickstart/catalog.xml
+++ /dev/null
@@ -1,22 +0,0 @@
-<catalog>
- <name>Brooklyn Demos</name>
-
-
- <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB">
- <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB">
- <description>Deploys a demonstration web application to JBoss clusters around the world</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
- </template>
-
- <classpath>
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
- </classpath>
-
-
-</catalog>
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-large.png b/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
deleted file mode 100644
index b566b1a..0000000
Binary files a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
deleted file mode 100644
index 05e9b0c..0000000
Binary files a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location.png b/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
deleted file mode 100644
index c13fdd8..0000000
Binary files a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db-location.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db.png b/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db.png
deleted file mode 100644
index ebb6f42..0000000
Binary files a/docs/website/quickstart/images/add-application-catalog-web-cluster-with-db.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/add-application-modal-yaml.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/add-application-modal-yaml.png b/docs/website/quickstart/images/add-application-modal-yaml.png
deleted file mode 100644
index c50b7ab..0000000
Binary files a/docs/website/quickstart/images/add-application-modal-yaml.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/jboss7-cluster-policies-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/jboss7-cluster-policies-large.png b/docs/website/quickstart/images/jboss7-cluster-policies-large.png
deleted file mode 100644
index 3d84477..0000000
Binary files a/docs/website/quickstart/images/jboss7-cluster-policies-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/jboss7-cluster-policies.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/jboss7-cluster-policies.png b/docs/website/quickstart/images/jboss7-cluster-policies.png
deleted file mode 100644
index 2f85328..0000000
Binary files a/docs/website/quickstart/images/jboss7-cluster-policies.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-db-activities-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-db-activities-large.png b/docs/website/quickstart/images/my-db-activities-large.png
deleted file mode 100644
index c214d9e..0000000
Binary files a/docs/website/quickstart/images/my-db-activities-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-db-activities.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-db-activities.png b/docs/website/quickstart/images/my-db-activities.png
deleted file mode 100644
index 0f2327c..0000000
Binary files a/docs/website/quickstart/images/my-db-activities.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web-cluster-starting.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web-cluster-starting.png b/docs/website/quickstart/images/my-web-cluster-starting.png
deleted file mode 100644
index c389b0b..0000000
Binary files a/docs/website/quickstart/images/my-web-cluster-starting.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web-cluster-stop-confirm-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web-cluster-stop-confirm-large.png b/docs/website/quickstart/images/my-web-cluster-stop-confirm-large.png
deleted file mode 100644
index c9bdab6..0000000
Binary files a/docs/website/quickstart/images/my-web-cluster-stop-confirm-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web-cluster-stop-confirm.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web-cluster-stop-confirm.png b/docs/website/quickstart/images/my-web-cluster-stop-confirm.png
deleted file mode 100644
index 179b00a..0000000
Binary files a/docs/website/quickstart/images/my-web-cluster-stop-confirm.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web-summary-large.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web-summary-large.png b/docs/website/quickstart/images/my-web-summary-large.png
deleted file mode 100644
index fc4bffe..0000000
Binary files a/docs/website/quickstart/images/my-web-summary-large.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web-summary.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web-summary.png b/docs/website/quickstart/images/my-web-summary.png
deleted file mode 100644
index e85752f..0000000
Binary files a/docs/website/quickstart/images/my-web-summary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/website/quickstart/images/my-web.png
----------------------------------------------------------------------
diff --git a/docs/website/quickstart/images/my-web.png b/docs/website/quickstart/images/my-web.png
deleted file mode 100644
index 2bd6ac3..0000000
Binary files a/docs/website/quickstart/images/my-web.png and /dev/null differ
[07/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/locations/configuring.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/configuring.md b/docs/guide/ops/locations/configuring.md
new file mode 100644
index 0000000..3a02260
--- /dev/null
+++ b/docs/guide/ops/locations/configuring.md
@@ -0,0 +1,105 @@
+---
+title: Configuring Locations
+layout: guide-normal
+---
+
+<a id="locations"></a>
+
+Brooklyn supports deploying to any machine which admits SSH access, as well as to
+a huge variety of external and on-premise clouds. You can also connect to services,
+or use whatever technique for deployment suits you best (such as Xebia Overthere, in development!).
+
+Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the following:
+
+{% highlight bash %}
+# use this key for localhost (this is the default, although if you have a passphrase you must set it)
+brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa
+
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+
+# use a special key when connecting to public clouds, and a particularly special one for AWS
+brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa
+brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa
+
+# AWS credentials (when deploying to location jclouds:aws-ec2)
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+
+# credentials for 'geoscaling' service
+brooklyn.geoscaling.username=cloudsoft
+brooklyn.geoscaling.password=xxx
+{% endhighlight %}
+
+These can also be set as environment variables (in the shell) or system properties (java command line).
+(There are also ``BROOKLYN_JCLOUDS_PRIVATE_KEY_FILE`` variants accepted.)
+
+For any jclouds provider you will typically need to set ``identity`` and ``credential``
+in the ``brooklyn.location.jclouds.provider`` namespace.
+
+To deploy to sets of machines with known IP's, assuming you have the credentials,
+use the syntax ``byon:(hosts="user@10.9.1.1,user@10.9.1.2,user@10.9.1.3")``
+(this requires your default private key to have access;
+see the ``prod1`` example below for specifying other credentials).
+
+A wide range of other fields is available, because in the real world sometimes things do get complicated.
+The following is supported from the configuration file (with whatever customization you might want available in code):
+
+- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
+ ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``, or other places
+ where ``privateKeyFile`` is valid). If you don't like keys, you can just use a plain old ``password``.
+
+- Hardware requirements such as ``minRam`` and ``minCores`` can be supplied, or a ``hardwareId`` (jclouds only)
+
+- Specific Secury Groups can be specified using `securityGroups`, if you want to reuse set of existing ones (jclouds only)
+
+- Specific KeyPair can be specified using `keyPair`, if you want to reuse an existing keypair (jclouds only).
+
+- Specific VM images can be specified using ``imageId`` or ``imageNameRegex`` (jclouds only)
+
+- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"`` (jclouds only)
+
+- A ``user`` can be specified, with the property that -- in a jclouds world -- the user will be *created* on the machine,
+ with admin rights, authorizing the relevant public key (corresponding to the private key, or as described below).
+ Login for the root account will be disabled, as will login by password if a public key is supplied.
+ (This is skipped if ``user`` is the ``root`` or other initial login user.)
+
+- You can specify the user account to use to login to jclouds initially with the ``loginUser`` property.
+ Typically this is auto-detected by jclouds
+ (often ``root``, or ``ubuntu`` or ``ec2-user`` for known Ubuntu or Amazon Linux images),
+ but the strategy isn't foolproof, particularly in some private cloud setups. (jclouds only). In some cases, you may need to specify a `loginUser.privateKeyFile` if the image you are using doesn't allow ssh password login.
+
+- Public keys can be specified using ``publicKeyFile``,
+ although these can usually be omitted if they follow the common pattern of being
+ the private key file with the suffix ``.pub`` appended.
+ (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
+ or might not even have, the private key of the ``root`` user in order to log in.)
+
+- You can specify the number of attempts Brooklyn should make to create
+ machines with ``machineCreateAttempts`` (jclouds only). This is useful for
+ working around the rare occasions in which cloud providers give machines that
+ are dead on arrival.
+
+You can also define named locations for commonly used groups of properties,
+with the syntax ``brooklyn.location.named.your-group-name.``
+followed by the relevant properties.
+These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment location.
+
+Some more advanced examples showing the syntax and properties above are as follows:
+
+{% highlight bash %}
+# Production pool of machines for my application (deploy to named:prod1)
+brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.prod1.user=produser1
+brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
+
+# AWS using my company's credentials and image standard, then labelling images so others know they're mine
+brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU
+brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
+brooklyn.location.named.company-jungle.imageId=ami-12345
+brooklyn.location.named.company-jungle.minRam=2048
+brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
+brooklyn.location.named.company-jungle.machineCreateAttempts=2
+{% endhighlight %}
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md
new file mode 100644
index 0000000..2e3c092
--- /dev/null
+++ b/docs/guide/ops/locations/index.md
@@ -0,0 +1,101 @@
+---
+title: Locations Intro
+layout: guide-normal
+---
+
+Locations are the environments to which Brooklyn deploys applications.
+These can be clouds (public or private), fixed infrastructure environments, or your laptop.
+
+Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`.
+
+## Setting up an SSH key
+
+While some locations can be accessed using *user:password* credentials it is more common to use authentication keys.
+
+To use keyfile based authentication, Brooklyn requires that the management machine has an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`.
+
+If you do not already have an SSH key installed, create a new id_rsa key:
+
+{% highlight bash %}
+$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
+{% endhighlight %}
+
+If you wish to use an existing key SSH, or an SSH key
+that has a passphrase, or a location other than `~/.ssh`, you can specify this in
+`brooklyn.properties` using `brooklyn.location.localhost.privateKeyFile` and
+`brooklyn.location.localhost.privateKeyPassphrase`.
+
+## Localhost
+
+Brooklyn can access localhost if there is an SSH key on the machine and if the SSH key has been added to the list of `authorized_keys` on that machine.
+
+{% highlight bash %}
+# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
+$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+{% endhighlight %}
+
+MacOS user? In addition to the above, enable 'Remote Login' in System Preferences >
+ Sharing.
+
+
+## Cloud Endpoints (via jclouds)
+
+[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/) is available on jclouds.apache.org.
+
+Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key on the management machine.
+
+Some clouds provide both API keys and SSH keys. In this case add only the API credentials to `brooklyn.properties`. (jclouds will transparently use the API credentials to setup access using the management machine's SSH key.)
+
+### Example: AWS Virginia Large Centos
+
+{% highlight bash %}
+## Snippet from ~/.brooklyn/brooklyn.properties.
+
+# Provide jclouds with AWS API credentials.
+brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
+
+# Name this location 'AWS Virginia Large Centos' and wire to AWS US-East-1
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2:us-east-1
+
+# (Using the same name) specify image, user and minimum ram size (ie instance size)
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096
+
+
+{% endhighlight %}
+
+This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line as: `AWS\ Virginia\ Large\ Centos`.
+
+See the Getting Started [template brooklyn.properties](../quickstart/brooklyn.properties) for more examples of using cloud endpoints.
+
+
+## Fixed Infrastructure
+
+Bringing your own nodes (BYON) to Brooklyn is straightforward.
+
+You will need the IP addresses of the nodes and the access credentials. Both SSH and password based login are supported.
+
+### Example: On-Prem Iron
+
+{% highlight bash %}
+## Snippet from ~/.brooklyn/brooklyn.properties.
+
+# Use the byon prefix, and provide the IP addresss (or IP ranges)
+brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+
+{% endhighlight %}
+
+
+## Advanced Options
+
+Unusual provider? 'Featureful' API? Brooklyn can cope.
+
+[This spreadsheet](https://docs.google.com/a/cloudsoftcorp.com/spreadsheet/ccc?key=0Avy7Tdf2EOIqdGQzSlNiT2M0V19SejBScDhSdzMtT2c) provides explanation, guidance, and examples for the majority of location options.
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/persistence/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md
new file mode 100644
index 0000000..be19606
--- /dev/null
+++ b/docs/guide/ops/persistence/index.md
@@ -0,0 +1,274 @@
+---
+title: Persistence
+layout: guide-normal
+---
+
+Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted,
+or so that a high availability standby server can take over.
+
+Brooklyn can persist its state to one of two places: the file system, or to an Object Store
+of your choice.
+
+Command Line Options
+--------------------
+
+To configure brooklyn, the relevant command line options for the `launch` commands are:
+
+* `--persist` <persistence mode>
+ The persistence mode.
+* `--persistenceDir` <persistence dir>
+ The directory to read/write persisted state (or container name if using an object store).
+* `--persistenceLocation` <persistence location>
+ The location spec for an object store to read/write persisted state.
+
+For the persistence mode, the possible values are:
+
+* `disabled` means that no state will be persisted or read; when Brooklyn stops all state is lost.
+* `rebind` means that it will read existing state, and recreate entities, locations and policies
+ from that. If there is no existing state, startup will fail.
+* `clean` means that any existing state will be deleted, and Brooklyn will be started afresh.
+* `auto` means Brooklyn will rebind if there is any existing state, or will start afresh if
+ there is no state.
+
+The persistence directory and location can instead be specified from `brooklyn.properties` using
+the following config keys:
+
+* `brooklyn.persistence.dir`
+* `brooklyn.persistence.location.spec`
+
+
+File-based Persistence
+----------------------
+
+To persist to the file system, start brooklyn with:
+
+{% highlight bash %}
+brooklyn launch --persist auto --persistenceDir /path/to/myPersistenceDir
+{% endhighlight %}
+
+If there is already data at `/path/to/myPersistenceDir`, then a backup of the directory will
+be made. This will have a name like `/path/to/myPersistenceDir.20140701-142101345.bak`.
+
+The state is written to the given path. The file structure under that path is:
+
+* `./entities/`
+* `./locations/`
+* `./policies/`
+* `./enrichers/`
+
+In each of those directories, an XML file will be created per item - for example a file per
+entity in ./entities/. This file will capture all of the state - for example, an
+entity's: id; display name; type; config; attributes; tags; relationships to locations, child
+entities, group membership, policies and enrichers; and dynamically added effectors and sensors.
+
+
+Object Store Persistence
+------------------------
+
+Brooklyn can persist its state to any Object Store API that jclouds supports including
+S3, Swift and Azure. This gives access to any compatible Object Store product or cloud provider
+including AWS-S3, SoftLayer, Rackspace, HP and Microsoft Azure.
+
+To configure the Object Store, add the credentials to `~/.brooklyn/brooklyn.properties` such as:
+
+{% highlight properties %}
+brooklyn.location.named.aws-s3-eu-west-1:aws-s3:eu-west-1
+brooklyn.location.named.aws-s3-eu-west-1.identity=ABCDEFGHIJKLMNOPQRSTU
+brooklyn.location.named.aws-s3-eu-west-1.credential=abcdefghijklmnopqrstuvwxyz1234567890ab/c
+{% endhighlight %}
+
+or:
+
+{% highlight properties %}
+brooklyn.location.named.softlayer-swift-ams01=jclouds:swift:https://ams01.objectstorage.softlayer.net/auth/v1.0
+brooklyn.location.named.softlayer-swift-ams01.identity=ABCDEFGHIJKLM:myname
+brooklyn.location.named.softlayer-swift-ams01.credential=abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz12
+{% endhighlight %}
+
+Start Brooklyn pointing at this target object store, e.g.:
+
+{% highlight bash %}
+brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLocation named:softlayer-swift-ams01
+{% endhighlight %}
+
+
+Rebind
+------
+
+When Brooklyn starts up pointing at existing state, it will recreate the entities, locations
+and policies based on that persisted state.
+
+Once all have been created, Brooklyn will "manage" the entities. This will bind to the
+underlying entities under management to update the each entity's sensors (e.g. to poll over
+HTTP or JMX). This new state will be reported in the web-console and can also trigger
+any registered policies.
+
+
+Copying Persistence State
+-------------------------
+
+Brooklyn includes a command to copy persistence state easily between two locations.
+The `copy-state` CLI command takes the following arguments:
+
+* `--persistenceDir` <source persistence dir>
+ The directory to read persisted state (or container name if using an object store).
+* `--persistenceLocation` <source persistence location>
+ The location spec for an object store to read persisted state.
+* `--destinationDir` <target persistence dir>
+ The directory to copy persistence data to (or container name if using an object store).
+* `--destinationLocation` <target persistence location>
+ The location spec for an object store to copy data to.
+* `--transformations` <transformations>
+ The local transformations file to be applied to the copy of the data before uploading it.
+
+
+Handling Rebind Failures
+------------------------
+If rebind were to fail for any reason, details of the underlying failures will be reported
+in the brooklyn.debug.log. There are several approaches to resolving problems.
+
+### Determine Underlying Cause
+
+The problems reported in brooklyn.debug.log will indicate where the problem lies - which
+entities, locations or policies, and in what way it failed.
+
+### Ignore Errors
+
+The `~/.brooklyn/brooklyn.properties` has several configuration options:
+
+{% highlight properties %}
+rebind.failureMode.danglingRef=continue
+rebind.failureMode.loadPolicy=continue
+rebind.failureMode.addPolicy=continue
+rebind.failureMode.rebind=fail_at_end
+{% endhighlight %}
+
+For each of these configuration options, the possible values are:
+
+* `fail_fast`: stop rebind immediately upon errors; do not try to rebind other entities
+* `fail_at_end`: continue rebinding all entities, but then fail so that all errors
+ encountered are reported
+* `continue`: log a warning, but ignore the error to continue rebinding. Depending on the
+ type of error, this can cause serious problems later (e.g. if the state of an entity
+ was entirely missing, then all its children would be orphaned).
+
+The meaning of the configuration options is:
+
+* `rebind.failureMode.dangingRef`: if there is a reference to an entity, location or policy
+ that is missing... whether to continue (discarding the reference) or fail.
+* `rebind.failureMode.loadPolicy`: if there is an error instantiate or reconstituting the
+ state of a policy or enricher... whether to continue (discarding the policy or enricher)
+ or fail.
+* `rebind.failureMode.addPolicy`: if there is an error re-adding the policy or enricher to
+ its associated entity... whether to continue (discarding the policy or enricher)
+ or fail.
+* `rebind.failureMode.rebind`: any errors on rebind not covered by the more specific error cases described above.
+
+
+### Seek Help
+
+Help can be found at `dev@brooklyn.incubator.apache.org`, where folk will be able to investigate
+issues and suggest work-arounds.
+
+By sharing the persisted state (with credentials removed), Brooklyn developers will be able to
+reproduce and debug the problem.
+
+
+### Fix-up the State
+
+The state of each entity, location, policy and enricher is persisted in XML.
+It is thus human readable and editable.
+
+After first taking a backup of the state, it is possible to modify the state. For example,
+an offending entity could be removed, or references to that entity removed, or its XML
+could be fixed to remove the problem.
+
+
+### Fixing with Groovy Scripts
+
+The final (powerful and dangerous!) tool is to execute Groovy code on the running Brooklyn
+instance. If authorized, the REST api allows arbitrary Groovy scripts to be passed in and
+executed. This allows the state of entities to be modified (and thus fixed) at runtime.
+
+If used, it is strongly recommended that Groovy scripts are run against a disconnected Brooklyn
+instance. After fixing the entities, locations and/or policies, the Brooklyn instance's
+new persisted state can be copied and used to fix the production instance.
+
+
+High Availability
+-----------------
+
+Brooklyn will automatically run in HA mode if multiple Brooklyn instances are started
+pointing at the same persistence store. One Brooklyn node (e.g. the first one started)
+is elected as HA master: all *write operations* against Brooklyn entities, such as creating
+an application or invoking an effector, should be directed to the master.
+
+Once one node is running as `MASTER`, other nodes start in either `STANDBY` or `HOT_STANDBY` mode:
+
+* In `STANDBY` mode, a Brooklyn instance will monitor the master and will be a candidate
+ to become `MASTER` should the master fail. Standby nodes do *not* attempt to rebind
+ until they are elected master, so the state of existing entities is not available at
+ the standby node. However a standby server consumes very little resource until it is
+ promoted.
+
+* In `HOT_STANDBY` mode, a Brooklyn instance will read and make available the live state of
+ entities. Thus a hot-standby node is available as a read-only copy.
+ As with the standby node, if a hot-standby node detects that the master fails,
+ it will be a candidate for promotion to master.
+
+To explicitly specify what HA mode a node should be in, the following CLI options are available
+for the parameter `--highAvailability`:
+
+* `disabled`: management node works in isolation; it will not cooperate with any other standby/master nodes in management plane
+* `auto`: will look for other management nodes, and will allocate itself as standby or master based on other nodes' states
+* `master`: will startup as master; if there is already a master then fails immediately
+* `standby`: will start up as lukewarm standby; if there is not already a master then fails immediately
+* `hot_standby`: will start up as hot standby; if there is not already a master then fails immediately
+
+The REST API offers live detection and control of the HA mode,
+including setting priority to control which nodes will be promoted on master failure:
+
+* `/server/ha/state`: Returns the HA state of a management node (GET),
+ or changes the state (POST)
+* `/server/ha/states`: Returns the HA states and detail for all nodes in a management plane
+* `/server/ha/priority`: Returns the HA node priority for MASTER failover (GET),
+ or sets that priority (POST)
+
+Note that when POSTing to a non-master server it is necessary to pass a `Brooklyn-Allow-Non-Master-Access: true` header.
+For example, the following cURL command could be used to change the state of a `STANDBY` node on `localhost:8082` to `HOT_STANDBY`:
+
+ curl -v -X POST -d mode=HOT_STANDBY -H "Brooklyn-Allow-Non-Master-Access: true" http://localhost:8082/v1/server/ha/state
+
+
+Writing Persistable Code
+------------------------
+The most common problem on rebind is that custom entity code has not been written in a way
+that can be persisted and/or rebound.
+
+The rule of thumb when implementing new entities, locations and policies is that all state
+must be persistable. All state must be stored as config or as attributes, and must be
+serializable (e.g. avoid the use of anonymous inner classes).
+
+Below is a guide for when implementing an entity in Java (or any other JVM language):
+
+* Don't store state in artibrary fields - the field will not be persisted (this is a design
+ decision, because Brooklyn cannot intercept the field being written to, so cannot know
+ when to persist).
+* Store runtime state as attributes.
+* Ensure values can be serialized. This (currently) uses xstream, which means it does not
+ need to implement `Serializable`. However, if declaring your own classes that are to be
+ persisted as state of the entity then declare them as static (or top-level) classes
+ rather than anonymous inner classes or non-static inner classes.
+* By extending `SoftwareProcess`, entities get a lot of the rebind logic for free. For
+ example, the default `rebind()` method will call `connectSensors()`.
+* If necessary, implement rebind. The `entity.rebind()` is called automatically by the
+ Brooklyn framework on rebind, after configuring the entity's config/attributes but before
+ the entity is managed.
+ Note that `init()` will not be called on rebind.
+* For special cases, it is possible to call `entity.requestPerist()` which will trigger
+ asynchronous persistence of the entity.
+
+For locations, policies and enrichers they (currently) do not have attributes. However,
+config is persisted automatically. Normally the state of a policy or enricher is transient -
+on rebind it starts afresh, for example with monitoring the performance or health metrics
+rather than relying on the persisted values.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/webconsole/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/index.md b/docs/guide/ops/webconsole/index.md
new file mode 100644
index 0000000..9764ae9
--- /dev/null
+++ b/docs/guide/ops/webconsole/index.md
@@ -0,0 +1,399 @@
+---
+title: Runtime Management
+layout: guide-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.
+
+There are several ways to launch applications with brooklyn, and useful configuration options,
+as well as a debug-view web console.
+This chapter describes these high-level runtime concepts, then proceeds to present more
+detailed information on the underlying implementation of management within 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.
+
+
+
+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)] <command> [<args>]
+
+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 <command>' 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.
+
+
+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.
+
+<!-- FIXME Update to use new construction pattern, rather than calling app's constructor -->
+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:
+
+[](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.
+
+[](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 <path-to-keystore-directory>/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 `<path-to-keystore-directory>` 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=<path-to-keystore-directory>/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 does not yet expose a REST API. This was to allow the APi to be designed to align with emerging standards.
+
+Selected management operations are possible remotely using links exposed by the GUI (after authenticating with the GUI).
+
+### Logging
+
+Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including java.util.logging, log4j, and logback.
+
+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.
+
+
+<!---
+
+<a name="distributed-management"></a>
+Distributed Management
+----------------------
+
+TODO Describe how and when objects become "live", pushed out to other nodes.
+-->
+
+<!---
+
+<a name="resilience"></a>
+Resilience
+----------
+TODO
+*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
+-->
+
+
+Key APIs
+--------
+<!---
+TODO - brief overview of 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)
+
+
+<!---
+TODO - describe how to simply configure logging slf4j
+-->
+
+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<String> 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.
+
+<!---
+TODO probably say about events now, quick reference about SubscriptionManager (either here or in next section on management context)
+TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as reader won't need to know too much detail of sensor types to understand policies... though perhaps saying some is right. (Talking about JSON is almost certainly overkill...)
+-->
+
+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".
+
+<!---
+TODO check classes above; is this much detail needed here?
+-->
+
+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.
+<!---
+TODO , etc., example
+-->
+
+### 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.*
+<!---
+TODO
+-->
+
+### 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<Void> 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/a7a317bf/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png b/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
new file mode 100644
index 0000000..6364dc5
Binary files /dev/null and b/docs/guide/ops/webconsole/webconsole-dashboard-w400.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/webconsole/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard.png b/docs/guide/ops/webconsole/webconsole-dashboard.png
new file mode 100644
index 0000000..cac5567
Binary files /dev/null and b/docs/guide/ops/webconsole/webconsole-dashboard.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/webconsole/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail-w400.png b/docs/guide/ops/webconsole/webconsole-detail-w400.png
new file mode 100644
index 0000000..b372e55
Binary files /dev/null and b/docs/guide/ops/webconsole/webconsole-detail-w400.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/ops/webconsole/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail.png b/docs/guide/ops/webconsole/webconsole-detail.png
new file mode 100644
index 0000000..17829cd
Binary files /dev/null and b/docs/guide/ops/webconsole/webconsole-detail.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/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
new file mode 100644
index 0000000..3b6134b
--- /dev/null
+++ b/docs/guide/start/_my-web-cluster.yaml
@@ -0,0 +1,19 @@
+name: My Web Cluster
+location: location
+services:
+
+- serviceType: 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
+ java.sysprops:
+ brooklyn.example.db.url: >
+ $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+ component("db").attributeWhenReady("datastore.url"),
+ "visitors", "brooklyn", "br00k11n")
+
+- serviceType: brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: My DB
+ brooklyn.config:
+ creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints.md b/docs/guide/start/blueprints.md
new file mode 100644
index 0000000..c6c0bc3
--- /dev/null
+++ b/docs/guide/start/blueprints.md
@@ -0,0 +1,57 @@
+---
+title: Launching Applications
+title_in_menu: Launching Applications
+layout: guide-normal
+menu_parent: index.md
+---
+
+{% include fields.md %}
+
+### Launching from the Catalog
+
+
+Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
+
+Now when we open the web console, two applications are displayed from the catalog.
+
+Select the 'Demo Web Cluster with DB' and click 'Next'.
+
+[](add-application-catalog-web-cluster-with-db-large.png)
+
+Select the Location that Brooklyn should deploy to, and name your application then click 'Finish' to launch the application as before.
+
+## Launching from a blueprint
+
+There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
+
+For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
+
+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.
+
+
+
+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.
+
+{% highlight yaml %}
+{% readj _my-web-cluster.yaml %}
+{% endhighlight %}
+
+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 %}
+
+**My Web Cluster Blueprint**
+
+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
+
+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!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/brooklyn.properties
----------------------------------------------------------------------
diff --git a/docs/guide/start/brooklyn.properties b/docs/guide/start/brooklyn.properties
new file mode 100644
index 0000000..08bb4a3
--- /dev/null
+++ b/docs/guide/start/brooklyn.properties
@@ -0,0 +1,324 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# This is Brooklyn's dot-properties file.
+# It should be located at "~/.brooklyn/brooklyn.properties" for automatic loading,
+# or can be specified as a CLI option with --localProperties /path/to/these.properties.
+
+################################## Welcome! ############################################
+
+# It's great to have you here.
+
+# Getting Started options have been pulled to the top. There's a formatting guide at the
+# very bottom.
+
+############################ Getting Started Options ####################################
+
+## GUI Security
+
+## NOTE: in production it is highly recommended to set this, as otherwise it will not require login,
+## not will it be encrypted (though for safety if security is not set it will only bind to loopback)
+
+## Edit the name(s) and passwords as appropriate to your system:
+
+# brooklyn.webconsole.security.users=admin,bob
+# brooklyn.webconsole.security.user.admin.password=password
+# brooklyn.webconsole.security.user.bob.password=bobsword
+
+## If you prefer to run with https (on port 8443 by default), uncomment this:
+
+# brooklyn.webconsole.security.https.required=true
+
+
+# By default we have AWS set up (but with invalid credentials!). Many, many other
+# providers are supported.
+
+## Amazon EC2 Credentials
+# These should be an "Access Key ID" and "Secret Access Key" for your account.
+# This is configured at https://console.aws.amazon.com/iam/home?#security_credential .
+
+brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
+
+# Beware of trailing spaces in your cloud credentials. This will cause unexpected
+# 401: unauthorized responses.
+
+## Using Other Clouds
+# 1. Cast your eyes down this document to find your preferred cloud in the Named Locations
+# section, and the examples.
+# 2. Uncomment the relevant line(s) for your provider.
+# 3. ADD -.identity and -.credential lines for your provider, similar to the AWS ones above,
+# replacing 'aws-ec2' with jcloud's id for your cloud.
+
+
+## Deploying to Localhost
+## see: info on locations at brooklyn.io
+#
+## ~/.ssh/id_rsa is Brooklyn's default location
+# brooklyn.location.localhost.privateKeyFile = ~/.ssh/id_rsa
+## Passphrases are supported, but not required
+# brooklyn.location.localhost.privateKeyPassphrase = s3cr3tpassphrase
+
+## Geoscaling Service - used for the Global Web Fabric demo
+## see: the global web example at brooklyn.io
+## https://www.geoscaling.com/dns2/
+## other services may take similar configuration similarly; or can usually be set in YAML
+# brooklyn.geoscaling.username = USERNAME
+# brooklyn.geoscaling.password = PASSWORD
+# brooklyn.geoscaling.primaryDomain = DOMAIN
+
+
+########################## Getting Started Complete! ###################################
+
+# That's it, although you may want to read through these options...
+
+################################ Brooklyn Options ########################################
+
+## Brooklyn Management Base Directory: specify where management data should be stored on this server;
+## ~/.brooklyn/ is the default but you could use something like /opt/brooklyn/state/
+## (provided this process has write permissions)
+# brooklyn.base.dir=~/.brooklyn/
+
+## Brooklyn On-Box Directory: specify where data should be stored on managed hosts;
+## for most locations a directory off home is the default (but using /tmp/brooklyn-user/ on localhost),
+## however you could specify something like /opt/brooklyn-managed-process/ (creation and permissions are handled)
+# onbox.base.dir=~/brooklyn-managed-process/
+
+## Additional security: Allow all - if you know what you are doing!
+## (Or you can also plug in e.g. LDAP security etc here)
+# brooklyn.webconsole.security.provider = brooklyn.rest.security.provider.AnyoneSecurityProvider
+
+## Optionally disallow deployment to localhost (or any other location)
+# brooklyn.location.localhost.enabled=false
+
+## Scripting Behaviour
+
+## keep scripts around after running them (usually in /tmp)
+# brooklyn.ssh.config.noDeleteAfterExec = true
+
+## Misc Cloud Settings
+## brooklyn will fail a node if the cloud machine doesn't come up, but you can tell it to retry:
+# brooklyn.location.jclouds.machineCreateAttempts = 3
+## many cloud machines don't have sufficient entropy for lots of encrypted networking, so fake it:
+# brooklyn.location.jclouds.installDevUrandom=true
+
+## Sets a minimium ram property for all jclouds locations. Recommended to avoid getting m1.micros on AWS!
+brooklyn.location.jclouds.minRam = 2048
+
+## When setting up a new cloud machine Brooklyn creates a user with the same name as the user running
+## Brooklyn on the management server, but you can force a different user here:
+# brooklyn.location.jclouds.user=brooklyn
+## And you can force a password or key (by default it will use the keys in ~/.ssh/id_rsa{,.pub}
+# brooklyn.location.jclouds.password=s3cr3t
+
+################################ Named Locations ########################################
+
+# Named locations appear in the web console. If using the command line or YAML it may be
+# just as easy to use the jclouds:<provider> locations and specify additional properties there.
+
+## Example: AWS Virginia using Rightscale 6.3 64bit Centos AMI and Large Instances
+# brooklyn.location.named.aws-va-centos-large = jclouds:aws-ec2:us-east-1
+# brooklyn.location.named.aws-va-centos-large.imageId=us-east-1/ami-7d7bfc14
+# brooklyn.location.named.aws-va-centos-large.user=brooklyn
+# brooklyn.location.named.aws-va-centos-large.minRam=4096
+
+## You can also nest these:
+# brooklyn.location.named.aws-acct-two = jclouds:aws-ec2
+# brooklyn.location.named.aws-acct-two.identity = AKA_ACCT_TWO
+# brooklyn.location.named.aws-acct-two.credential = <access-key-hex-digits>
+# brooklyn.location.named.aws-acct-two-singapore = named:aws-acct-two
+# brooklyn.location.named.aws-acct-two-singapore.region = ap-southeast-1
+# brooklyn.location.named.aws-acct-two-singapore.displayName = AWS Singapore (Acct Two)
+
+# For convenience some common defaults:
+brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
+brooklyn.location.named.aws-oregon = jclouds:aws-ec2:us-west-2
+brooklyn.location.named.aws-ireland = jclouds:aws-ec2:eu-west-1
+brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1
+
+## Google Compute
+## Note at present you have to create and download the P12 key from the Google "APIs & auth -> Registered Apps" interface,
+## then convert to PEM private key format using `openssl pkcs12 -in Certificates.p12 -out Certificates.pem -nodes`
+## then embed that on one line as the 'credential, replacing new lines with \n as below
+## (hopefully this will be improved in jclouds in the future)
+# brooklyn.location.jclouds.google-compute-engine.identity=1234567890-somet1mesArand0mU1Dhere@developer.gserviceaccount.com
+# brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN PRIVATE KEY----- \nMIIblahablahblah \nblahblahblah \n-----END PRIVATE KEY-----
+# brooklyn.location.named.Google\ US = jclouds:google-compute-engine
+# brooklyn.location.named.Google\ US.region=us-central1-a
+# brooklyn.location.named.Google\ EU = jclouds:google-compute-engine
+# brooklyn.location.named.Google\ EU.region=europe-west1-a
+## the following flags for GCE are recommended
+## specify the network to use - otherwise it creates new networks each time and you hit quotas pretty quickly
+## you may have to manually create this network AND enable a firewall rule EG tcp:1-65535;udp:1-65535;icmp
+## (fix for this is in progress)
+# brooklyn.location.jclouds.google-compute-engine.networkName=brooklyn-default-network
+## gce images have bad entropy, this ensures they have noisy /dev/random (even if the "randomness" is not quite as random)
+# brooklyn.location.jclouds.google-compute-engine.installDevUrandom=true
+## gce images often start with iptables turned on; turn it off
+# brooklyn.location.jclouds.google-compute-engine.stopIptables=true
+
+## HP Cloud - also Ubuntu 12.04 LTS
+## You specify your HP Credentials like this:
+# brooklyn.location.jclouds.hpcloud-compute.identity = projectname:username
+# brooklyn.location.jclouds.hpcloud-compute.credential = password
+## where username and password are the same as logging in to the web console, and
+## projectname can be found here: https://account.hpcloud.com/projects
+#�brooklyn.location.named.HP\ Cloud\ Arizona-1 = jclouds:hpcloud-compute:az-1.region-a.geo-1
+# brooklyn.location.named.HP\ Cloud\ Arizona-1.imageId = az-1.region-a.geo-1/75845
+# brooklyn.location.named.HP\ Cloud\ Arizona-1.user = ubuntu
+
+## Softlayer - need a key from the gui, under "administrative -> user administration -> api-access
+# brooklyn.location.jclouds.softlayer.identity=username
+# brooklyn.location.jclouds.softlayer.credential=<private-key-hex-digits>
+## locations
+# brooklyn.location.named.Softlayer\ Dallas=jclouds:softlayer:dal05
+# brooklyn.location.named.Softlayer\ Seattle=jclouds:softlayer:sea01
+# brooklyn.location.named.Softlayer\ Washington\ DC=jclouds:softlayer:wdc01
+# brooklyn.location.named.Softlayer\ Singapore\ 1=jclouds:softlayer:sng01
+# brooklyn.location.named.Softlayer\ Amsterdam\ 1=jclouds:softlayer:ams01
+
+
+## Brooklyn uses the jclouds multi-cloud library to access many clouds.
+## http://www.jclouds.org/documentation/reference/supported-providers/
+
+## Templates for many other clouds, but remember to add identity and credentials:
+
+# brooklyn.location.named.Bluelock = jclouds:bluelock-vcloud-zone01
+
+# brooklyn.location.named.CloudSigma\ Nevada = jclouds:cloudsigma-lvs
+# brooklyn.location.named.CloudSigma\ Zurich = jclouds:cloudsigma-zrh
+
+# brooklyn.location.named.ElasticHosts\ London = jclouds:elastichosts-lon-p
+# brooklyn.location.named.ElasticHosts\ Texas = jclouds:elastichosts-sat-p
+
+# brooklyn.location.named.GleSYS = jclouds:glesys
+
+# brooklyn.location.named.Go2Cloud = jclouds:go2cloud-jhb1
+
+# brooklyn.location.named.GoGrid = jclouds:gogrid
+
+# brooklyn.location.named.Green\ House\ Data = jclouds:greenhousedata-element-vcloud
+
+# brooklyn.location.named.Ninefold = jclouds:ninefold-compute
+
+# brooklyn.location.named.OpenHosting = jclouds:openhosting-east1
+
+# brooklyn.location.named.Rackspace\ Chicago\ (ord) = jclouds:rackspace-cloudservers-us:ORD
+# brooklyn.location.named.Rackspace\ Dallas\ (dfw) = jclouds:rackspace-cloudservers-us:DFW
+# brooklyn.location.named.Rackspace\ Hong\ Kong\ (hkg) = jclouds:rackspace-cloudservers-us:HKG
+# brooklyn.location.named.Rackspace\ Northern\ Virginia\ (iad) = jclouds:rackspace-cloudservers-us:IAD
+# brooklyn.location.named.Rackspace\ Sydney\ (syd) = jclouds:rackspace-cloudservers-us:SYD
+## for UK you will need a separate account with rackspace.co.uk
+# brooklyn.location.named.Rackspace\ London\ (lon) = jclouds:rackspace-cloudservers-uk
+
+## if you need to use Rackspace "first gen" API
+## (note the "next gen" api configured above seems to be faster)
+# brooklyn.location.jclouds.cloudservers-us.identity = YOURAPIKEY
+# brooklyn.location.jclouds.cloudservers-us.credential = YOURSECRETKEY
+# brooklyn.location.named.Rackspace\ US\ (First Gen) = jclouds:cloudservers-us
+## and as with next gen, first gen requires a separate acct for the UK:
+# brooklyn.location.jclouds.cloudservers-uk.identity = YOURAPIKEY
+# brooklyn.location.jclouds.cloudservers-uk.credential = YOURSECRETKEY
+# brooklyn.location.named.Rackspace\ UK\ (First Gen) = jclouds:cloudservers-uk
+
+# brooklyn.location.named.SeverLove = jclouds:serverlove-z1-man
+
+# brooklyn.location.named.SkaliCloud = jclouds:skalicloud-sdg-my
+
+# brooklyn.location.named.Stratogen = jclouds:stratogen-vcloud-mycloud
+
+# brooklyn.location.named.TryStack\ (Openstack) = jclouds:trystack-nova
+
+
+## Production pool of machines for my application (deploy to named:On-Prem\ Iron\ Example)
+# brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+# brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+
+## Various Private Clouds
+
+## Example: OpenStack Nova
+
+## openstack identity and credential are random strings of letters and numbers (TBC - still the case?)
+# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:https://9.9.9.9:9999/v2.0/
+
+## OpenStack Nova access information can be downloaded from the openstack web interface; for example, as openrc.sh file
+# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:keystone-url
+# brooklyn.location.named.My\ OpenStack.identity=your-tenant-name:your-user-name
+# brooklyn.location.named.My\ OpenStack.credential=your-password
+# brooklyn.location.named.My\ OpenStack.endpoint=your-keystone-url
+
+## The ID of the image must be configured according to the local OpenStack settings
+## Use the command nova image-list to list all the available images
+## Use the command nova show <image-name> to get more details
+# brooklyn.location.named.My\ OpenStack.imageId=the-region-name/the-image-id
+
+## Virtual Machine flavors must match the ones created upfront according to the local OpenStack settings
+## Use the command nova flavor-list to list all the available options
+## Use the command nova flavor-show <flavor-name> to get more details
+# brooklyn.location.named.My\ OpenStack.hardwareId=the-region-name/the-flavor-id
+
+## (Optional) Configurations
+
+# brooklyn.location.named.My\ OpenStack.user=user-name-inside-the-instance
+
+## The keyPair must by created upfront. Both the following two options are required at the same time.
+# brooklyn.location.named.My\ OpenStack.keyPair=the-key-pair-name
+# brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/keypair.pem
+
+## Security groups must be created upfront (TBC - How to specify many security groups at one ?)
+# brooklyn.location.named.My\ OpenStack.securityGroups=universal
+
+# brooklyn.location.named.My\ OpenStack.openIptables=true
+# brooklyn.location.named.My\ OpenStack.selinux.disabled=true
+# brooklyn.location.named.My\ OpenStack.auto-create-floating-ips=true
+# brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false
+
+## cloudstack identity and credential are rather long random strings of letters and numbers
+## you generate this in the cloudstack gui, under accounts, then "view users", then "generate key"
+## use the "api key" as the identity and "secret key" as the credential
+# brooklyn.location.named.My\ Cloudstack=jclouds:cloudstack:http://9.9.9.9:9999/client/api/
+
+## abiquo identity and credential are your login username/passed
+# brooklyn.location.named.My\ Abiquo=jclouds:abiquo:http://demonstration.abiquo.com/api/
+
+############################### Formatting Guide #######################################
+
+! Both # and ! mark lines as comments
+# The follow syntax are ALL valid.
+# example_key example_value
+# example_key : example_value
+# example_key = example_value
+# example_key=example_value
+
+# The backslash below tells Brooklyn to continue reading the value onto the next line.
+# example_key = A very \
+# long string!
+# Note all white space before 'long...' is ignored. Also '!' is kept as part of the string
+
+
+# Keys with spaces should be escaped with backslashes.
+# This is useful for named locations, as the name displayed in Brooklyn's web
+# interface is derived from the key name.
+# key\ with\ spaces = some\ value
+
+# Encoding for .properties must be ISO-8859-1, aka Latin-1.
+# All non-latin1 characters must be entered using unicode escape characters
+# polish_pangram = P\u00F3jd\u017A\u017Ce, ki\u0144 \
+# t\u0119 chmurno\u015B\u0107 w g\u0142\u0105b flaszy!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/start/catalog.xml b/docs/guide/start/catalog.xml
new file mode 100644
index 0000000..6cff554
--- /dev/null
+++ b/docs/guide/start/catalog.xml
@@ -0,0 +1,22 @@
+<catalog>
+ <name>Brooklyn Demos</name>
+
+
+ <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB">
+ <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB">
+ <description>Deploys a demonstration web application to JBoss clusters around the world</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
+ </template>
+
+ <classpath>
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ </classpath>
+
+
+</catalog>
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/config.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/config.md b/docs/guide/start/config.md
new file mode 100644
index 0000000..125553b
--- /dev/null
+++ b/docs/guide/start/config.md
@@ -0,0 +1,50 @@
+---
+title: Configuring Brooklyn
+title_in_menu: Configuring Brooklyn
+layout: guide-normal
+menu_parent: index.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 = <access-key-hex-digits>
+ 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 = <private-key-hex-digits>
+ 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}}/use/guide/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/a7a317bf/docs/guide/start/docs-summary.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/docs-summary.include.md b/docs/guide/start/docs-summary.include.md
deleted file mode 100644
index a6a176c..0000000
--- a/docs/guide/start/docs-summary.include.md
+++ /dev/null
@@ -1,7 +0,0 @@
-To learn about Brooklyn, here are some recommended starting points:
-
-* [Developer's Walkthrough]({{site.path.guide}}/start/walkthrough/index.html)
-* [Examples]({{site.path.guide}}/use/examples/)
-* [User Guide]({{site.path.guide}}/use/guide/)
-* [Code Overview]({{site.path.guide}}/dev/code/)
-* [Code on Github](http://github.com/apache/incubator-brooklyn/)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/docs-summary.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/docs-summary.md b/docs/guide/start/docs-summary.md
deleted file mode 100644
index 25ba02b..0000000
--- a/docs/guide/start/docs-summary.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-layout: guide-normal
-title: Documentation
-toc: ../toc.json
----
-
-{% readj docs-summary.include.md %}
-
-Beyond this, [just come chat to us]({{site.path.guide}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/download.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/download.md b/docs/guide/start/download.md
deleted file mode 100644
index 34e07ff..0000000
--- a/docs/guide/start/download.md
+++ /dev/null
@@ -1,171 +0,0 @@
----
-layout: guide-normal
-title: Downloads
-toc: ../toc.json
----
-{% include fields.md %}
-
-First time user? The [getting started]({{ site.path.guide }}/use/guide/quickstart/index.html) guide will walk you through downloading Brooklyn, setup of your `brooklyn.properties` and `catalog.xml` files, and then trying the [examples](#examples).
-
-## Download Version {{ site.brooklyn-version }}
-
-<table>
- <tr>
- <th style='text-align:left'>Download</th>
- <th style='text-align:left'>File/Format</th>
- <th>checksums <small><a href="/meta/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
- </tr>
- <tr>
- <td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
- <td style='text-align:left'><a href='{{ this_dist_url_zip }}' title='Download ZIP archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.zip</a></td>
- <td><small><a href='{{ this_dist_url_zip }}.asc'>PGP</a>, <a href='{{ this_dist_url_zip }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'><a href='{{ this_dist_url_tgz }}' title='Download TGZ archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz</a></td>
- <td ><small><a href='{{ this_dist_url_tgz }}.asc'>PGP</a>, <a href='{{ this_dist_url_tgz }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'>All Jar</td>
- <td style='text-align:left'><a href='{{ this_alljar_url_jar }}' title='Download the ALL JAR'>brooklyn-all-{{ site.brooklyn-version }}-with-dependencies.jar</a></td>
- <td><small><a href='{{ this_alljar_url_jar }}.asc'>PGP</a>, <a href='{{ this_alljar_url_jar }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'>Apache Repo</td>
- <td style='text-align:left'>
- <a href='{{ this_anything_url_search }}' title='Search'><i>GUI</i></a>
- —
- <a href='{{ this_dist_url_list }}' title='List'><i>dir</i></a>
- </td>
- <td> — </td>
- </tr>
- <tr>
- <td style='text-align:left'>Release Notes</td>
- <td style='text-align:left'><a href='{{ site.path.guide }}/start/release-notes.html'>{{ site.brooklyn-version }}</a></td>
- <td> — </td>
- </tr>
-</table>
-
-
-<a name="distro"></a>
-
-## The Distro
-
-The distribution archive contains Brooklyn as a standalone executable package.
-
-* [This version ZIP]({{ this_dist_url_zip }})
-* [This version TGZ]({{ this_dist_url_tgz }})
-* [Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-dist/)
-* [Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-dist/)
-
-Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-dist/) for stable releases
-and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-dist/) for snapshot versions.
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-**Please note**: You are reading the documentation for a snapshot version of Brooklyn.
-You should always confirm that the source and date for snapshot artifacts.
-{% endif %}
-
-
-<a name="alljar"></a>
-
-## The All Jar
-
-This is a single JAR containing all of Brooklyn and its dependencies, for developing Brooklyn into your own applications. If not using maven, just add it to your classpath.
-
-* [This version]({{ this_alljar_url_jar }})
-* [All Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-all/)
-* [All Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-all/)
-
-Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-all/) for stable releases
-and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-all/) for snapshot versions.
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-**Again**, check the source and date for SNAPSHOT JARs.
-{% endif %}
-
-## Release Notes
-
-Release notes can be found [here]({{ site.path.guide }}/start/release-notes.html).
-
-
-<a name="examples"></a>
-
-## Examples
-
-Examples can be found in the main Brooklyn codebase, in the `/examples` directory.
-
-A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html).
-
-
-<a name="maven"></a>
-
-## Maven
-
-If you use Maven, you can add Brooklyn with the following in your pom:
-
-<!-- the comment is included due to a jekyll/highlight bug which
- removes indentation on the first line in a highlight block;
- we want the actual XML indented so you can cut and paste into a pom.xml sensibly -->
-{% highlight xml %}
-<!-- include all Brooklyn items in our project -->
- <dependencies>
- <dependency>
- <groupId>org.apache.brooklyn</groupId>
- <artifactId>brooklyn-all</artifactId>
- <version>{{ site.brooklyn-version }}</version>
- </dependency>
- </dependencies>
-{% endhighlight %}
-
-`brooklyn-all` (used above) brings in all dependencies, including jclouds.
-If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``,
-and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``brooklyn-software-messaging``, or others
-(browse the full list [here]({{ this_anything_url_search }})).
-
-If you wish to use the Apache snapshot repo and/or Cloudsoft repositories,
-you can add some of the following sections:
-
-{% highlight xml %}
-<!-- include repos for snapshot items and other dependencies -->
- <repositories>
- <repository>
- <id>apache-nexus-snapshots</id>
- <name>Apache Nexus Snapshots</name>
- <url>https://repository.apache.org/content/repositories/snapshots</url>
- <releases> <enabled>false</enabled> </releases>
- <snapshots> <enabled>true</enabled> </snapshots>
- </repository>
- <repository>
- <id>cloudsoft-cloudfront-releases-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/releases/</url>
- </repository>
- <repository>
- <id>cloudsoft-cloudfront-snapshots-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/snapshots/</url>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- <checksumPolicy>fail</checksumPolicy>
- </snapshots>
- </repository>
- </repositories>
-{% endhighlight %}
-
-{% if SNAPSHOT %}
-**Please note**: to use a snapshot version of Brooklyn, you must either have Brooklyn built locally
-or one of the additional snapshot repositories above.
-{% endif %}
-
-
-<a name="source"></a>
-
-## Source Code
-
-Full source is at [github.com/apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn).
-Information on working with the source is [here]({{ site.path.guide }}/dev/code).
-
-Alternatively you can download archives of the source directly:
-
-<a href="https://github.com/apache/incubator-brooklyn/tarball/master"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
-<a href="https://github.com/apache/incubator-brooklyn/zipball/master"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/add-application-catalog-web-cluster-with-db-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/add-application-catalog-web-cluster-with-db-large.png b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-large.png
new file mode 100644
index 0000000..b566b1a
Binary files /dev/null and b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location-large.png
new file mode 100644
index 0000000..05e9b0c
Binary files /dev/null and b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location.png b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location.png
new file mode 100644
index 0000000..c13fdd8
Binary files /dev/null and b/docs/guide/start/images/add-application-catalog-web-cluster-with-db-location.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/add-application-catalog-web-cluster-with-db.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/add-application-catalog-web-cluster-with-db.png b/docs/guide/start/images/add-application-catalog-web-cluster-with-db.png
new file mode 100644
index 0000000..ebb6f42
Binary files /dev/null and b/docs/guide/start/images/add-application-catalog-web-cluster-with-db.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/add-application-modal-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/add-application-modal-yaml.png b/docs/guide/start/images/add-application-modal-yaml.png
new file mode 100644
index 0000000..c50b7ab
Binary files /dev/null and b/docs/guide/start/images/add-application-modal-yaml.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/jboss7-cluster-policies-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/jboss7-cluster-policies-large.png b/docs/guide/start/images/jboss7-cluster-policies-large.png
new file mode 100644
index 0000000..3d84477
Binary files /dev/null and b/docs/guide/start/images/jboss7-cluster-policies-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/jboss7-cluster-policies.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/jboss7-cluster-policies.png b/docs/guide/start/images/jboss7-cluster-policies.png
new file mode 100644
index 0000000..2f85328
Binary files /dev/null and b/docs/guide/start/images/jboss7-cluster-policies.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-db-activities-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-db-activities-large.png b/docs/guide/start/images/my-db-activities-large.png
new file mode 100644
index 0000000..c214d9e
Binary files /dev/null and b/docs/guide/start/images/my-db-activities-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-db-activities.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-db-activities.png b/docs/guide/start/images/my-db-activities.png
new file mode 100644
index 0000000..0f2327c
Binary files /dev/null and b/docs/guide/start/images/my-db-activities.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web-cluster-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web-cluster-starting.png b/docs/guide/start/images/my-web-cluster-starting.png
new file mode 100644
index 0000000..c389b0b
Binary files /dev/null and b/docs/guide/start/images/my-web-cluster-starting.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web-cluster-stop-confirm-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web-cluster-stop-confirm-large.png b/docs/guide/start/images/my-web-cluster-stop-confirm-large.png
new file mode 100644
index 0000000..c9bdab6
Binary files /dev/null and b/docs/guide/start/images/my-web-cluster-stop-confirm-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web-cluster-stop-confirm.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web-cluster-stop-confirm.png b/docs/guide/start/images/my-web-cluster-stop-confirm.png
new file mode 100644
index 0000000..179b00a
Binary files /dev/null and b/docs/guide/start/images/my-web-cluster-stop-confirm.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web-summary-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web-summary-large.png b/docs/guide/start/images/my-web-summary-large.png
new file mode 100644
index 0000000..fc4bffe
Binary files /dev/null and b/docs/guide/start/images/my-web-summary-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web-summary.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web-summary.png b/docs/guide/start/images/my-web-summary.png
new file mode 100644
index 0000000..e85752f
Binary files /dev/null and b/docs/guide/start/images/my-web-summary.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/start/images/my-web.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/images/my-web.png b/docs/guide/start/images/my-web.png
new file mode 100644
index 0000000..2bd6ac3
Binary files /dev/null and b/docs/guide/start/images/my-web.png differ
[10/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/highlevel1.md
----------------------------------------------------------------------
diff --git a/docs/_extra/highlevel1.md b/docs/_extra/highlevel1.md
new file mode 100644
index 0000000..3dfafb4
--- /dev/null
+++ b/docs/_extra/highlevel1.md
@@ -0,0 +1,50 @@
+## What is Brooklyn?
+
+**brooklyn** is a library that simplifies application deployment and management.
+
+For **deployment**, it is designed to tie in with other tools,
+giving single-click deploy and adding the concepts of
+manageable clusters and fabrics:
+
+* many common software entities available out-of-the-box
+* integrates with [Apache Whirr](http://whirr.apache.org)
+ to deploy well-known services such as Hadoop and elasticsearch
+ (or use POBS, plain-old-bash-scripts)
+* use PaaS's such as OpenShift, alongside self-built clusters, for maximum flexibility
+
+Brooklyn makes roll-out an integral part of the DevOps chain,
+as code which can be version-controlled and programmatically tested,
+and portable across many clouds or fixed IP machines,
+using [jclouds](http://jclouds.org) --
+or just hitting ``localhost`` for quick dev/test.
+
+Brooklyn's main emphasis is post-deployment, **managing** an application once it is live:
+management policies are an integral part of the deployment descriptor,
+and at runtime policies have access to all aspects of the deployment.
+They are aware of the deployment topology (hierarchical) and
+locations (machines, PaaSes, and jurisdictions),
+as well as scripts, instrumentation, and operational goals and constraints.
+This means they're all set, once the application is launched,
+to keep the application running optimally,
+based on whatever *optimally* means in that context.
+
+These deployment patterns and management policies are expressed as Java (and Groovy) classes,
+open-sourced here and giving you full control over what you want to happen.
+More importantly, however, this code can be shared, improved, and extended.
+
+We're still near the beginning of figuring this out:
+[join us to make it better]({{site.path.guide}}/meta/contact.html).
+
+
+## To Get Started
+
+* See the [developer's walkthrough]({{site.path.guide}}/start/walkthrough/index.html) for a quick tour
+* Check out the [examples]({{site.path.guide}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
+* Jump in to the [user guide]({{site.path.guide}}/use/guide/) describing the
+ [concepts]({{site.path.guide}}/use/guide/defining-applications/basic-concepts.html)
+ and including a [tutorial]({{site.path.guide}}/use/guide/quickstart/)
+* Or dive straight in to the code, either [reading]({{site.path.guide}}/dev/code/) about it
+ or [gitting](http://github.com/apache/incubator-brooklyn/) it
+
+If you like it, or if you have ideas how it could be better,
+[join the discussion]({{site.path.guide}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/list-of-blueprints.md
----------------------------------------------------------------------
diff --git a/docs/_extra/list-of-blueprints.md b/docs/_extra/list-of-blueprints.md
new file mode 100644
index 0000000..7136dd1
--- /dev/null
+++ b/docs/_extra/list-of-blueprints.md
@@ -0,0 +1,160 @@
+---
+title: Systems Available Out-of-the-Box
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide]
+---
+
+brooklyn comes bundled with support for a large number of systems and entities.
+
+*Some entities are in an early-access state, and documentation is incomplete. Please contact the Brooklyn Project for assistance and clarification.*
+<!---
+.. TODO fix
+.. TODO name entities
+.. TODO include the fully qualified name of the entity
+-->
+
+<a name="web"></a>
+Web
+---
+
+### Clusters and Interfaces
+
+The class ``ControlledDynamicWebAppCluster`` creates a load-balanced cluster of web servers.
+It defaults to Nginx and JBoss 7, but this is configurable with the ``controller`` or ``controllerSpec``, and
+the ``memberSpec`` configuration options.
+
+Most web app server processes, and some clusters and PaaS implementations,
+support the interface ``WebAppService`` which defines many sensors including requests per second.
+This allows app server metrics to interoperable across implementations in many cases.
+
+
+### JBoss Application Server
+
+Brooklyn supports JBoss 7 in the calss ``JBoss7Server``, with a wide range of
+monitoring.
+
+JBoss 6 is also supported using the different class ``JBoss6Server``.
+(The different implementation is needed due to major differences between 6 and 7,
+including switching from JMX to HTTP/JSON as the preferred metrics mechanism.)
+
+
+### Apache Tomcat
+
+Apache Tomcat is supported in the class ``TomcatServer``.
+(Note that this currently uses a legacy Brooklyn class hierarchy,
+and could benefit from being ported to the ``JavaSoftwareProcessSshDriver`` implementation.)
+
+
+### Nginx Load Balancer
+
+Nginx provides clustering support for several web/app servers.
+
+The install process downloads the sources for both the service and the sticky session module, configures them using GNI
+autoconf and compiles them. This requires gcc and autoconf to be installed. The install script also uses the yum package manager (if available) to install openssl-devel which is required to build the service. This will only work on RHEL or CentOS Linux systems, but the install process should proceed on a vanilla system with development tools available.
+
+On debian/ubuntu to build nginx you can get the required libraries with:
+``apt-get install zlib1g-dev libdigest-sha-perl libssl-dev``.
+(The entity install script will attempt to do this with sudo,
+but that may fail if sudo access is not available.)
+
+
+<a name="database"></a>
+Database
+--------
+
+### MySQL
+
+MySQL is one of the most popular relational databases.
+Brooklyn supports setting up individual MySQL nodes with arbitrary configuration,
+which may be used to create multiple nodes using back-up and synchronization processes as desired.
+(If certain patterns for configuring multiple nodes become popular, these could be
+added as Brooklyn entities.)
+
+
+### Apache Derby
+
+*This entity is in the sandbox.*
+
+Brooklyn supports Apache Derby, a pure-Java SQL database. For setting up an instance of a server see ``DerbySetup``.
+
+
+<a name="nosql"></a>
+NoSQL
+-----
+
+*The NoSQL entities may not be complete.*
+
+### Redis
+
+Redis is a distributed key-value store, supporting master/slave replication of a store as a clustered cache. This gives
+a series of read-only slaves and a single read-write master, which propagates to the slaves with eventual consistency.
+
+
+### MongoDB
+
+
+### Cassandra
+
+
+### CouchBase
+
+
+<a name="messaging"></a>
+Messaging
+---------
+
+### Qpid
+
+
+Qpid support provides a JMS broker, running over AMQP. This exposes JMS queues and topics as entities as well.
+See ``QpidSetup`` for instantiating a broker.
+
+### ActiveMQ
+
+
+ActiveMQ support provides a JMS broker. This exposes JMS queues and topics as entities as well. See ``ActiveMQSetup`` for
+instantiating a broker.
+
+### RabbitMQ
+
+
+<a name="downstream-projects"></a>
+Downstream Projects
+-------------------
+
+Downstream projects include those below.
+
+### Apache Whirr
+
+https://github.com/brooklyncentral/brooklyn-whirr
+
+Whirr allows running a variety of services on cloud providers and on localhost. This is done by providing a ``recipe`` which describes what services to launch. You can find an example of how Brooklyn integrates with Whirr [here](/use/examples/whirrhadoop/index.html#custom-whirr-recipe).
+
+### OpenShift
+
+https://github.com/cloudsoft/brooklyn-openshift
+
+### CloudFoundry
+
+https://github.com/cloudsoft/brooklyn-cloudfoundry and https://github.com/cloudsoft/brooklyn-cloudfoundry
+
+### MPI
+
+https://github.com/cloudsoft/brooklyn-openmpi
+
+### Waratek
+
+https://github.com/cloudsoft/brooklyn-waratek
+
+### MapR
+
+https://github.com/cloudsoft/brooklyn-mapr
+
+### Cloudera CDH
+
+https://github.com/cloudsoft/brooklyn-cdh
+
+### Drupal and Wordpress
+
+https://github.com/cloudsoft/brooklyn-social-apps
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/docs/_extra/local-artifact-repo.md b/docs/_extra/local-artifact-repo.md
new file mode 100644
index 0000000..455a545
--- /dev/null
+++ b/docs/_extra/local-artifact-repo.md
@@ -0,0 +1,32 @@
+---
+layout: guide-normal
+title: Prepopulating a Local Artifact Repository
+toc: /guide/toc.json
+---
+
+On occasion it can be useful to have/control/prepopulate a local repository of entity installers <small>[1]</small>.
+
+The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder:
+
+ wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/
+
+Brooklyn's default search behaviour for installation artifacts is as follows:
+
+1. The local `~/.brooklyn/repository/` folder.
+2. The entity's installer's public download url (or an overridden url if one has been specified).
+3. Cloudsoft's fallback repository.
+
+Cloudsoft's fallback repository <small>[2]</small> contains many of the installation artifacts used by current Brooklyn entities.
+
+It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis.
+
+If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from fallback behaviour, allowing out-of-date entities to be more easily identified and updated.
+
+<br />
+<small>
+<ol>
+<li>For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do <small>[3]</small>.</li>
+<li><a href="http://downloads.cloudsoftcorp.com/brooklyn/repository/">downloads.cloudsoftcorp.com/brooklyn/repository</a></li>
+<li>This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.</li>
+</ol>
+</small>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/brooklyn-gpg-public-key.asc
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/brooklyn-gpg-public-key.asc b/docs/_extra/meta/brooklyn-gpg-public-key.asc
new file mode 100644
index 0000000..3b515a4
--- /dev/null
+++ b/docs/_extra/meta/brooklyn-gpg-public-key.asc
@@ -0,0 +1,21 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG/MacGPG2 v2.0.18 (Darwin)
+Comment: GPGTools - http://gpgtools.org
+
+mQENBFDsSLEBCAC2JxQHeXpL3oGN2IickcG9C49gkxIsws4hpasQModVipezrQi0
+9pLq4lkB01GgC2sfPH+XXE8rCpA9EL0e4wVA7JICz5AsLZAAJH91tKksL20tLMeU
+Yrbufaq1ga7ifk3JWhF4iwvkDMBKyCjrF173nI+2TwX2XfNTQpzoQGOL1bNvS4NZ
+AD9JeXGW2D996zHdSK+x3wVdY3cDECvVMuw61+5ytZrGNnyvaaWTl3lJUyydPXHQ
+5TXVtbQH5WgYCLPr4E95axJ0BoY8H+fEaG1Uax1a+xLumVWhiWNp7rMvmgcZXuJO
+fx+wXAIbRNlAHoJcdZ4NCReRxDIBQ+2HsU1zABEBAAG0bUJyb29rbHluIFByb2pl
+Y3QgKGJyb29rbHluLmlvKSAoS2V5IHVzZWQgdG8gYXV0aGVudGljYXRlIEJyb29r
+bHluIGFydGlmYWN0cykgPGJyb29rbHluLWRldkBncm91cHMuZ29vZ2xlLmNvbT6J
+AT8EEwECACkFAlDsSLECGy8FCQeGH4AHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIX
+gAAKCRANhinnSRLCsOdIB/4tUVShup2NHXJ9acCah8TuEN4GmN9dBiD9YsGW66SR
+/ptY0Gn9XExl2wbmQW+7TQg3QUGv8uffwYLtnMwnmCp/WwgE+uSnRmcENxa9GuTu
+PLlURKKGK0C9ljTAHwXtPcIYxPNN3BT4VB56ME1DTBRCgEvudaNSANs8/kT88kE2
+eMC7x0Uo3/P38Ob8XSOfR8c6G6nSz6jILcRBXZTPNNK4svyqF5XHIru65d3/0+mr
+bpfcDLcUQYms0MpPmO1RCHLZWwJLsPUIxNwGGnKJc8/RNEvQinK+Ap0cf+PGUQSX
+PhB6Z81ROFIVToEVZslgSiL+u4Tc7zXDfDQDY4HeLY2t
+=w/CG
+-----END PGP PUBLIC KEY BLOCK-----
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/contact.include.md
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/contact.include.md b/docs/_extra/meta/contact.include.md
new file mode 100644
index 0000000..e0d1e4b
--- /dev/null
+++ b/docs/_extra/meta/contact.include.md
@@ -0,0 +1,9 @@
+
+Contact us on the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/).
+
+Additionally look for us on:
+
+* **IRC**: #brooklyncentral ([IRC??](/meta/irc.html))
+* **Twitter**: @brooklyncentral #brooklyncentral
+
+We'd love to hear from you!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/contact.md
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/contact.md b/docs/_extra/meta/contact.md
new file mode 100644
index 0000000..c318a1f
--- /dev/null
+++ b/docs/_extra/meta/contact.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Contact
+toc: /guide/toc.json
+---
+
+{% readj contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/irc.md
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/irc.md b/docs/_extra/meta/irc.md
new file mode 100644
index 0000000..9324bd2
--- /dev/null
+++ b/docs/_extra/meta/irc.md
@@ -0,0 +1,31 @@
+---
+layout: guide-normal
+title: IRC
+toc: /guide/toc.json
+---
+
+IRC is a basic group chat system used by many open source projects to enable developers to
+collaborate and to help users communicate and support each other. Brooklyn has an IRC
+channel where users and developers hang out.
+
+## Getting Help On IRC
+
+When you connect to the Brooklyn IRC channel, say Hi and then ask your question. It may
+take a little while for someone to see and respond to your question. (Be
+patient if you don't get an instant answer - unless there's already a conversation
+happening folk will probably not have their eyes on the channel.)
+
+You may want to do other things while you wait, like reviewing the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
+lists to see if anyone has had the same issue before.
+
+## Brooklyn IRC Channel
+
+* **IRC Server:** irc.freenode.net
+* **Channel/Room:** #brooklyncentral
+* **Port:** 6667 (Default)
+
+If you are new to IRC, there is a web interface at [webchat.freenode.net](http://webchat.freenode.net/?channels=brooklyncentral)
+but you may prefer to checkout the [Wikipedia IRC article](http://en.wikipedia.org/wiki/IRC#Client_software)
+for an IRC application.
+
+You can find more information about using IRC at [irchelp.org](http://www.irchelp.org/).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/toc.json
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/toc.json b/docs/_extra/meta/toc.json
new file mode 100644
index 0000000..f01fa8e
--- /dev/null
+++ b/docs/_extra/meta/toc.json
@@ -0,0 +1,8 @@
+[
+{ "title": "Versions",
+ "file": "{{ site.path.guide }}/meta/versions.html" },
+{ "title": "Verify",
+ "file": "{{ site.path.guide }}/meta/verify.html" },
+{ "title": "Contact",
+ "file": "{{ site.path.guide }}/meta/contact.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/_extra/meta/versions.md b/docs/_extra/meta/versions.md
new file mode 100644
index 0000000..57e64a4
--- /dev/null
+++ b/docs/_extra/meta/versions.md
@@ -0,0 +1,110 @@
+---
+layout: guide-normal
+title: Versions
+toc: /guide/toc.json
+---
+
+<!--- display which version we are using, based on where it is written -->
+
+### Brooklyn v{{ site.brooklyn-stable-version }}
+
+
+{% if site.server %}
+> **Server (debug) mode detected.**
+
+> *Links to other versions on this page and others will likely not work when running in server/debug mode.
+Files must be copied to the brooklyncentral.github.com repo for these links to resolve correctly.*
+
+> *Debug page generated {{ site.time }}*
+{% endif %}
+
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+<!--- snapshot version -->
+
+ {% if site.path.guide == '' %}
+
+<!--- current version (served off root of site) is snapshot (unusual) -->
+
+This is the documentation for the current snapshot version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+
+ {% else %}
+
+<!--- archive docs -->
+
+This is the documentation for a snapshot version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+
+[View current documentation here.](/meta/versions.html)
+
+
+ {% endif %}
+
+NB: "Snapshot" means it is the code at a point in time,
+and that a reference to this version {{ site.brooklyn-version }}
+may resolve to different code at a different point in time.
+Where possible it is preferable to develop against a GA version
+rather than a shapshot.
+
+{% else %}
+<!--- not snapshot -->
+
+ {% if site.path.guide == '' %}
+
+<!--- current version (served off root of site) -->
+
+This is the documentation for the latest stable version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+Other versions with documentation available are listed below.
+
+ {% else %}
+
+<!--- archive version -->
+
+This is the archived documentation for Brooklyn {{ site.brooklyn-version }}
+(generated {{ site.time }}, archived under {{ site.path.guide }}).
+
+[View current documentation here.](/meta/versions.html)
+
+ {% endif %}
+{% endif %}
+
+
+### Version History
+
+* **[0.7.0-SNAPSHOT (master)](/v/0.7.0-SNAPSHOT)**: since 0.6.0, lots of work on yaml, persistence, policies, and more supported systems
+
+* **[0.7.0](/v/0.7.0-M1/)**: most recent milestone release
+
+* **[0.6.0](/v/0.6.0/)**: use of spec objects, chef and windows support, more clouds (Nov 2013)
+
+* **[0.5.0](/v/0.5.0/)**: includes new JS GUI and REST API, rebind/persistence support, cleaner model and naming conventions, more entities (May 2013)
+
+* **[0.4.0](/v/0.4.0/)**: initial public GA release of Brooklyn to Maven Central, supporting wide range of entities and examples (Jan 2013)
+
+Note: To prevent accidentally referring to out-of-date information,
+a banner is displayed when accessing specific versions from the archive.
+You may
+<a href="#" onclick="set_user_versions_all();">disable all warnings</a> or
+<a href="#" onclick="clear_user_versions();">re-enable all warnings</a>.
+
+
+### Versioning
+
+Brooklyn uses the [semantic versioning](http://semver.org/) guidelines. Releases will be numbered with the following format:
+
+`Brooklyn <major>.<minor>.<patch>`
+
+Breaking backward compatibility increments the `<major>` version.
+New additions without breaking backward compatibility ups the `<minor>` version.
+Bug fixes and misc changes bumps the `<patch>` version.
+New major and minor releases zero the less significant counters.
+
+Additionally, Brooklyn's release process include Snapshots, Milestones and Release Candidates.
+
+A Snapshot (`-SNAPSHOT`) is the bleeding edge. This will not be stable.
+
+Milestone versions (`-Mn`) are frozen snapshots. Some code features may be stable, but the documentation and examples may not be complete.
+
+A Release Candidate (`-rc.n`) is a just-about-ready version. Release candidates are tested against our acceptance criteria, and qualifying builds are promoted as final.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/release.md
----------------------------------------------------------------------
diff --git a/docs/_extra/release.md b/docs/_extra/release.md
new file mode 100644
index 0000000..66f730b
--- /dev/null
+++ b/docs/_extra/release.md
@@ -0,0 +1,288 @@
+---
+layout: guide-normal
+title: Release Process
+toc: /guide/toc.json
+---
+
+**This needs substantial updating in light of the Apache move.**
+
+<!--
+TODO
+
+vote required? see governance.
+
+
+ branch-twice-then-reversion-twice
+ e.g. from master=1.0.0_SNAPSHOT we will go to
+ create branch: v1.0.0_SNAPSHOT
+ reversion master: 1.1.0_SNAPSHOT
+ create branch and reversion: v1.0.0_RC1, v1.0.0_SNAPSHOT
+ describe scripts for releasing
+ docs
+
+update version, using scripts
+
+push examples to repo
+
+push docs to branch and publish
+
+-->
+
+Brooklyn is published to two locations:
+
+* Sonatype, for snapshots and for staging releases
+* Maven Central, for full (GA and milestone) releases
+
+Brooklyn artifacts are generally downloaded from:
+
+1. [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.brooklyn%22),
+ and (http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.brooklyn%22) for pre 0.7.0 versions
+2. [Apache](https://repository.apache.org/index.html#nexus-search;quick~org.apache.brooklyn),
+2. [Sonatype](https://oss.sonatype.org/index.html#nexus-search;quick~io.brooklyn) for pre 0.7.0 versions
+3. [GitHub](https://github.com/apache/incubator-brooklyn).
+
+
+To publish:
+
+* a snapshot release:
+ * mvn deploy to Sonatype
+ * (optional) publish versioned docs to brooklyncentral.github.com project
+* a (milestone) release:
+ * same as above, but with some git versioning
+ * deploy to Sonatype, then release to Maven Central
+ * deploy a version branch to brooklyn-examples
+ * deploy (or update) versioned docs
+* a major release:
+ * same as above, and
+ * in addition to versioned examples, update brooklyn-examples master to match the current (stable) release
+ * in addition to versioned docs, publish full (front page) docs to brooklyncentral.github.com project
+ * bump the snapshot version in brooklyn master to the next release
+
+
+
+## Configuration
+
+Your .m2/settings.xml must be configured with the right credentials for Sonatype
+
+ <servers>
+ ...
+ <server>
+ <username> ... </username>
+ <password> ... </password>
+ <id>sonatype-nexus-snapshots</id>
+ </server>
+ <server>
+ <username> ... </username>
+ <password> ... </password>
+ <id>sonatype-nexus-staging</id>
+ </server>
+ ...
+ </servers>
+You must be configured to sign artifacts using PGP.
+
+If this is the first time you have used Sonatype, the [Sonatype - Maven Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) is required reading.
+
+The code snippets below use the following variables:
+{% highlight bash %}
+
+export BROOKLYN_DIR=/path/to/brooklyncentral-brooklyn
+export EXAMPLES_DIR=/path/to/brooklyncentral-brooklyn-examples
+export SITE_DIR=/path/to/brooklyncentral-brooklyncentral.github.com
+
+export SNAPSHOT_VERSION=0.6.0-SNAPSHOT
+export RELEASE_VERSION=0.6.0-M1
+{% endhighlight %}
+
+
+## Preparing a Snapshot Release
+
+### Deploy to Sonatype
+
+Execute the following:
+{% highlight bash %}
+mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
+{% endhighlight %}
+
+### (Option) Publish snapshot docs.
+
+(Only required if there have been significant changes to docs or java docs.)
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+git checkout master
+
+if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
+
+# Build the docs
+_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
+
+# Wipe any previous edition of the same version, replacing with new build.
+rm -rf $SITE_DIR/v/$SNAPSHOT_VERSION
+mkdir $SITE_DIR/v/$SNAPSHOT_VERSION
+cp -r _site/* $SITE_DIR/v/$SNAPSHOT_VERSION/
+
+# and push, causing GitHub to republish with updated /v/$SNAPSHOT_VERSION/
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated version docs for version $SNAPSHOT_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+
+
+## Preparing a (Milestone) Release
+
+### Prepare a Release Branch
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR
+git checkout -b $RELEASE_VERSION
+usage/scripts/change-version.sh $SNAPSHOT_VERSION $RELEASE_VERSION
+git commit -a -m "Changed version to $RELEASE_VERSION"
+git push -u upstream $RELEASE_VERSION
+
+{% endhighlight %}
+
+### Deploy to Sonatype, and Close the repo.
+
+{% highlight bash %}
+mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
+{% endhighlight %}
+
+* Go to [oss.sonatype.org ... #stagingRepositories](https://oss.sonatype.org/index.html#stagingRepositories) (again, need credentials)
+* 'Close' the repo
+* Email the closed repo address to brooklyn-dev list, have people download and confirm it works.
+
+### Update the brooklyn-examples repo's version Branch
+
+{% highlight bash %}
+
+cd $EXAMPLES_DIR
+
+pushd $BROOKLYN_DIR
+git checkout $RELEASE_VERSION
+popd
+
+if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
+git checkout master
+git checkout -b $RELEASE_VERSION
+rm -rf *
+cp -r $BROOKLYN_DIR/examples/* .
+rm -rf target
+git add -A
+git commit -m "branch for $RELEASE_VERSION"
+git push -u origin $RELEASE_VERSION
+
+{% endhighlight %}
+
+
+### Update the Versioned Docs
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+git checkout $RELEASE_VERSION
+
+if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
+
+# Build the docs
+_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
+
+# Wipe any previous edition of the same version, replacing with new build.
+rm -rf $SITE_DIR/v/$RELEASE_VERSION
+mkdir $SITE_DIR/v/$RELEASE_VERSION
+cp -r _site/* $SITE_DIR/v/$RELEASE_VERSION/
+
+# and push, causing GitHub to republish with updated /v/$RELEASE_VERSION/
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated version docs for version $RELEASE_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+## Preparing a Full Release
+
+Complete *all* above steps.
+
+### Deploy to Maven Central
+
+* Confirm that the closed Sonatype repo has no errors
+* Return to [Sonatype: Staging Repositories](https://oss.sonatype.org/index.html#stagingRepositories)
+* 'Release' the repo
+
+### Deploy the Examples master branch.
+
+{% highlight bash %}
+
+cd $EXAMPLES_DIR
+
+pushd $BROOKLYN_DIR
+git checkout $RELEASE_VERSION
+popd
+
+if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
+git checkout master
+rm -rf *
+cp -r $BROOKLYN_DIR/examples/* .
+rm -rf target
+git add -A
+git commit -m "Updated to $RELEASE_VERSION"
+git push -u origin master
+
+{% endhighlight %}
+
+### Update the brooklyn.io Front Page Version
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+
+pushd $SITE_DIR
+# remove old root files, but not the previous version in /v/
+if [ -f start/index.html ] ; then
+ for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
+else
+ echo IN WRONG DIRECTORY $SITE_DIR - export SITE_DIR to continue
+ exit 1
+fi
+popd
+
+# re-build for hosting at / rather than at /v/VERSION/
+_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
+
+# copy to site dir
+cp -r _site/* $SITE_DIR/
+
+# and git push
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated root docs for version $RELEASE_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+
+### Announce
+* Email the Dev and Users mailing lists.
+* Tweet from [@brooklyncentral](https://twitter.com/brooklyncentral)
+
+### Update Snapshot Version
+
+{% highlight bash %}
+
+export NEW_SNAPSHOT_VERSION=0.7.0-SNAPSHOT
+
+cd $BROOKLYN_DIR
+git checkout master
+usage/scripts/change-version.sh $SNAPSHOT_VERSION $NEW_SNAPSHOT_VERSION
+git commit -a -m "Changed version to $NEW_SNAPSHOT_VERSION"
+git push -u upstream master
+
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/simple_java_examples/example_files/tomcat_multi-location.java
----------------------------------------------------------------------
diff --git a/docs/_extra/simple_java_examples/example_files/tomcat_multi-location.java b/docs/_extra/simple_java_examples/example_files/tomcat_multi-location.java
new file mode 100644
index 0000000..cb92766
--- /dev/null
+++ b/docs/_extra/simple_java_examples/example_files/tomcat_multi-location.java
@@ -0,0 +1,15 @@
+// TODO Untested code; see brooklyn-example for better maintained examples!
+public class TomcatFabricApp extends AbstractApplication {
+ @Override
+ public void init() {
+ addChild(EntitySpec.create(DynamicFabric.class)
+ .configure("displayName", "WebFabric")
+ .configure("displayNamePrefix", "")
+ .configure("displayNameSuffix", " web cluster")
+ .configure("memberSpec", EntitySpec.create(ControlledDynamicWebAppCluster.class)
+ .configure("initialSize", 2)
+ .configure("memberSpec", : EntitySpec.create(TomcatServer.class)
+ .configure("httpPort", "8080+")
+ .configure("war", "/path/to/booking-mvc.war"))));
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/simple_java_examples/example_files/tomcat_nginx.java
----------------------------------------------------------------------
diff --git a/docs/_extra/simple_java_examples/example_files/tomcat_nginx.java b/docs/_extra/simple_java_examples/example_files/tomcat_nginx.java
new file mode 100644
index 0000000..20db33d
--- /dev/null
+++ b/docs/_extra/simple_java_examples/example_files/tomcat_nginx.java
@@ -0,0 +1,17 @@
+// TODO Untested code; see brooklyn-example for better maintained examples!
+public class TomcatClusterWithNginxApp extends AbstractApplication {
+ @Override
+ public void init() {
+ addChild(EntitySpec.create(NginxController.class)
+ .configure("domain", "brooklyn.geopaas.org")
+ .configure("port", "8000+")
+ .configure("portNumberSensor", Attributes.HTTP_PORT));
+
+ addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+ .configure("controller", nginxController)
+ .configure("memberSpec", : EntitySpec.create(TomcatServer.class)
+ .configure("httpPort", "8080+")
+ .configure("war", "/path/to/booking-mvc.war"))
+ .configure("initialSize", 2));
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/simple_java_examples/example_files/tomcat_simple.java
----------------------------------------------------------------------
diff --git a/docs/_extra/simple_java_examples/example_files/tomcat_simple.java b/docs/_extra/simple_java_examples/example_files/tomcat_simple.java
new file mode 100644
index 0000000..480a333
--- /dev/null
+++ b/docs/_extra/simple_java_examples/example_files/tomcat_simple.java
@@ -0,0 +1,9 @@
+// TODO Untested code; see brooklyn-example for better maintained examples!
+public class TomcatServerApp extends AbstractApplication {
+ @Override
+ public void init() {
+ addChild(EntitySpec.create(TomcatServer.class)
+ .configure("httpPort", "8080+")
+ .configure("war", "/path/to/booking-mvc.war")));
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/simple_java_examples/examples.md
----------------------------------------------------------------------
diff --git a/docs/_extra/simple_java_examples/examples.md b/docs/_extra/simple_java_examples/examples.md
new file mode 100644
index 0000000..330b6d3
--- /dev/null
+++ b/docs/_extra/simple_java_examples/examples.md
@@ -0,0 +1,121 @@
+---
+title: Examples
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+** TODO: this examples page is deprecated;
+code is out-of-date, and better examples are described on the web site.
+need to figure out if this page should be kept at all
+(indeed if the "guide" is even still relevant)**
+
+
+### Integrating with a Maven project
+
+If you have a Maven-based project, integrate this XML fragment with your pom.xml:
+
+<!-- TODO this should import from the downloads page -->
+
+{% highlight xml %}
+<dependencies>
+ <dependency>
+ <groupId>io.brooklyn</groupId>
+ <artifactId>brooklyn-all</artifactId>
+ <version>0.7.0-SNAPSHOT</version> <!-- BROOKLYN_VERSION -->
+ </dependency>
+</dependencies>
+
+<repository>
+ <id>cloudsoft-releases</id>
+ <url>http://developers.cloudsoftcorp.com/download/maven2/</url>
+</repository>
+<repository>
+ <id>libs-snapshot-local</id>
+ <url>http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/</url>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ <checksumPolicy>fail</checksumPolicy>
+ </snapshots>
+</repository>
+{% endhighlight %}
+
+
+### Starting a Tomcat Server
+
+The code below starts a Tomcat server on the local machine.
+
+The ``main`` method defines the application, and passes it to the ``BrooklynLauncher`` to be managed.
+It is then started in a localhost location (other locations are shown in the next section).
+
+The Tomcat's configuration indicates that the given WAR should be deployed to the Tomcat server when it is started.
+
+{% highlight java %}
+{% readj example_files/tomcat_simple.java %}
+{% endhighlight %}
+
+The ``wars`` config is also supported (with config keys ``ROOT_WAR`` and ``NAMED_WARS`` the long-hand syntax);
+they accept EARs and other common archives, and can be described as files or as URLs (as Strings),
+with URLs supporting an optional ``classpath://org/acme/resources/xxx.war`` syntax.
+
+
+### Starting Tomcat in Amazon EC2
+
+To start a tomcat node or cluster in Amazon EC2, the application is identical to that for localhost.
+The only difference is the location supplied.
+
+The Brooklyn CLI can be used to launch the application in your choice of location, such as:
+
+{% highlight bash %}
+brooklyn launch --app TomcatServerApp --location localhost
+brooklyn launch --app TomcatServerApp --location aws-ec2:eu-west-1
+{% endhighlight %}
+
+
+### Starting a Tomcat Cluster with Nginx
+
+The code below starts a Tomcat cluster along with an Nginx instance, where each Tomcat server in the cluster is registered with the Nginx instance.
+
+{% highlight java %}
+{% readj example_files/tomcat_nginx.java %}
+{% endhighlight %}
+
+This creates a cluster that of Tomcat servers, along with an Nginx instance. The ``NginxController`` instance
+is notified whenever a member of the cluster joins or leaves; the entity is configured to look at the ``HTTP_PORT``
+attribute of that instance so that the Nginx configuration can be updated with the ip:port of the cluster member.
+
+<!---
+TODO things may need tidying (paragraphs, and/or eliminating any extra setConfig calls, though looks like these have gone)
+-->
+
+
+Starting a Multi-location Tomcat Fabric
+---------------------------------------
+
+<!---
+TODO this example should use several cloud providers, including Openshift, and use GeoDNS,
+and maybe a data store and/or messaging service; it is the last "most advanced" example
+-->
+
+<!---
+FIXME Discuss above comment with Aled/Alex as it is contentious
+-->
+
+The ``ControlledDynamicWebAppCluster`` entity used above can also be used with a DynamicFabric to start
+a web-cluster in each location.
+
+{% highlight java %}
+{% readj example_files/tomcat_multi-location.java %}
+{% endhighlight %}
+
+
+Examples Source
+---------------
+
+Source code for (more up-to-date!) examples is available for download from GitHub. To retrieve the source, execute the following command:
+
+ git clone git@github.com:apache/incubator-brooklyn.git
+ cd incubator-brooklyn/examples
+
+You can also [browse the code](https://github.com/apache/incubator-brooklyn/tree/examples) on the web.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/standards.md
----------------------------------------------------------------------
diff --git a/docs/_extra/standards.md b/docs/_extra/standards.md
new file mode 100644
index 0000000..66b77b0
--- /dev/null
+++ b/docs/_extra/standards.md
@@ -0,0 +1,15 @@
+---
+layout: guide-normal
+title: Code Standards
+toc: /guide/toc.json
+---
+
+Without being too restrictive about how you have to code as part of Brooklyn,
+there are some style points that really make life easier when sharing code
+among ourselves:
+
+* Use spaces (not tabs!) with 4 spaces indentation
+* Keep line length <=128
+* Don't reformat code or organize imports unless there's very good
+ reason (this makes history and merges much harder)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_extra/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/_extra/update-docs.md b/docs/_extra/update-docs.md
new file mode 100644
index 0000000..ccb573e
--- /dev/null
+++ b/docs/_extra/update-docs.md
@@ -0,0 +1,14 @@
+---
+layout: guide-normal
+title: Updating the Docs
+toc: /guide/toc.json
+---
+
+<!-- TODO retire this page -->
+
+The Brooklyn docs live in the **docs** project in the Brooklyn codebase.
+It's built using standard jekyll/markdown with a few extensions.
+
+Instructions for building and working with docs are in a `README.md` file
+in that folder; for the most recent version of instructions click
+[here](https://github.com/apache/incubator-brooklyn/tree/master/docs/README.md).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_includes/list-children.html
----------------------------------------------------------------------
diff --git a/docs/_includes/list-children.html b/docs/_includes/list-children.html
new file mode 100644
index 0000000..68f8b5c
--- /dev/null
+++ b/docs/_includes/list-children.html
@@ -0,0 +1,7 @@
+{% comment %}
+TODO style this much better
+{% endcomment %}
+
+{% for item in page.menu %}
+* [{{ item.title }}]({{ item.url }})
+{% endfor %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_includes/topmenu.html
----------------------------------------------------------------------
diff --git a/docs/_includes/topmenu.html b/docs/_includes/topmenu.html
index 0230f1c..c15f0df 100644
--- a/docs/_includes/topmenu.html
+++ b/docs/_includes/topmenu.html
@@ -21,32 +21,40 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
- {% if page.navgroup != 'home' %}<a class="navbar-brand" href="{{site.path.website}}/"><img src="{{site.path.style}}/img/apache-brooklyn-logo-244px-wide.png" alt="brooklyn"></a>{% endif %}
+ {% unless page.landing %}<a class="navbar-brand" href="{{site.path.website}}/"><img src="{{site.path.style}}/img/apache-brooklyn-logo-244px-wide.png" alt="brooklyn"></a>{% endunless %}
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
- {% for navgroup in site.data.navgroups %}
- {% if navgroup.page.menu2 %}
- <li class="dropdown{% if page.navgroup == navgroup.id %} active{% endif %}">
- <a href="{{navgroup.page.url}}">{{navgroup.title}}</a>
+ {% for item in site.data.menu %}
+ {% if item.menu %}
+ <li class="dropdown{% if page.breadcrumb_paths contains item.path %} active{% endif %}">
+ <a href="{{item.url}}">{{ item.title_in_menu | downcase }}</a>
<ul class="dropdown-menu" role="menu">
<li>
- <a href="{{navgroup.page.url}}">{{navgroup.title_in_menu}}</a>
+ <a href="{{item.url}}">{{item.title_in_menu}}</a>
</li>
<li class="divider"></li>
- {% for child in navgroup.page.menu2 %}
- <li>
- <a href="{{child.reference.url}}">{{child.reference.title}}</a>
- </li>
+ {% for item2 in item.menu %}
+ <li>
+ {% if item2.menu_customization.dropdown_new_section %}
+ <div class="dropdown_new_section"><hr></div>
+ {% endif %}
+ <a href="{{item2.url}}">{{item2.title_in_menu}}</a>
+ {% if item2.menu_customization.dropdown_section_header %}
+ <div class="dropdown_section_header"><hr></div>
+ {% endif %}
+ </li>
{% endfor %}
</ul>
- </li><!-- {{ navgroup.id }} -->
- {% else %}
- <li class="{% if page.navgroup == navgroup.id %}active{% endif %}"><a href="{{navgroup.page.url}}">{{navgroup.title}}</a></li><!-- {{ navgroup.id }} -->
- {% endif %}
- {% endfor %}
+ </li>
+ {% else %}
+ <li class="{% if page.breadcrumb_paths contains item.path %}active{% endif %}">
+ <a href="{{item.url}}">{{ item.title_in_menu | downcase }}</a>
+ </li>
+ {% endif %}
+ {% endfor %}
</ul>
</div><!-- /.navbar-collapse -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_layouts/guide-normal.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/guide-normal.html b/docs/_layouts/guide-normal.html
index 736c838..67278e7 100644
--- a/docs/_layouts/guide-normal.html
+++ b/docs/_layouts/guide-normal.html
@@ -16,50 +16,8 @@
# specific language governing permissions and limitations
# under the License.
-layout: guide-base
+layout: website-normal
---
-{% include topmenu.html %}
-
-<div id="container">
-
- <div id="header">
-
- <div id="menubar">
-
-{% include topbar.html %}
-
- <form method="get" id="simple_google" class="searchform" action="http://www.google.com/search" method="get">
- <input type="text" class="searchinput" name="brooklyn-search" placeholder=" Search: type & hit enter" />
- <input type="hidden" name="q" value="" />
- </form>
-
- </div>
-
- </div><!--header-->
-
- <div id="contentcontainer">
-
- <div id="maincontent">
-
-{% include breadcrumbs.html %}
-
-<div id="page_notes"></div>
-
-<h1 id="header_title">{{ page.title }}</h1>
-
{{ content }}
- </div><!--maincontent-->
-
- <div id="sidebar">
-
-{% include sidebar.html %}
-
- </div>
-
- </div><!--contentcontainer-->
-
-</div><!--container-->
-
-{% include footer.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_layouts/guide-old.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/guide-old.html b/docs/_layouts/guide-old.html
new file mode 100644
index 0000000..736c838
--- /dev/null
+++ b/docs/_layouts/guide-old.html
@@ -0,0 +1,65 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+layout: guide-base
+---
+
+{% include topmenu.html %}
+
+<div id="container">
+
+ <div id="header">
+
+ <div id="menubar">
+
+{% include topbar.html %}
+
+ <form method="get" id="simple_google" class="searchform" action="http://www.google.com/search" method="get">
+ <input type="text" class="searchinput" name="brooklyn-search" placeholder=" Search: type & hit enter" />
+ <input type="hidden" name="q" value="" />
+ </form>
+
+ </div>
+
+ </div><!--header-->
+
+ <div id="contentcontainer">
+
+ <div id="maincontent">
+
+{% include breadcrumbs.html %}
+
+<div id="page_notes"></div>
+
+<h1 id="header_title">{{ page.title }}</h1>
+
+{{ content }}
+
+ </div><!--maincontent-->
+
+ <div id="sidebar">
+
+{% include sidebar.html %}
+
+ </div>
+
+ </div><!--contentcontainer-->
+
+</div><!--container-->
+
+{% include footer.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_layouts/website-normal.html
----------------------------------------------------------------------
diff --git a/docs/_layouts/website-normal.html b/docs/_layouts/website-normal.html
index a0596e4..ba6e9b8 100644
--- a/docs/_layouts/website-normal.html
+++ b/docs/_layouts/website-normal.html
@@ -18,6 +18,8 @@
# layout for most website pages, inheriting base for the menu bar, and providing a main column of content and a menu column
# (not used for the landing page, and not used for the guide)
+#
+# menu_customizations can be used, including force_inactive to prevent highlighting
layout: website-base
---
<div class="container">
@@ -27,14 +29,60 @@ layout: website-base
{{ content }}
</div>
<div class="col-md-3">
- {% if page.menu2 %}
- <div class="list-group">
- <h4><a href="{{page.menu2parent.url}}" class="list-group-item{% if page.menu2parent.path == page.path %} active{% endif %}">{{ page.menu2parent.title }}</a></h4>
- {% for child in page.menu2 %}
- <a href="{{child.reference.url}}" class="list-group-item{% if child.reference.path == page.path %} active{% endif %}">{{ child.reference.title }}</a>
- {% endfor %}
+ <div class="list-group side-menu">
+{% comment %}
+
+ Case 1) If we're the landing page show nothing.
+ Case 2) If we're contained in the top (landing page) menu, show our menu if we have one.
+ Case 3a) Otherwise if we're contained in a menu, show that menu.
+ Case 3b) And if we have a menu, show our menu nested.
+
+ Note the breadcrumbs are offset:1. This is because usually breadcrumbs include the root;
+ but also if we're overriding breadcrumbs it gives us a way to set a topmenu item (making it breadcrumb[0])
+ while customizing the side menu (make self breadcrumb[1]).
+{% endcomment %}
+
+{% unless page.landing %}
+ {% if page.menu_parent %}
+ {% if page.menu_parent.landing %} {% comment %} case 2 {% endcomment %}
+ {% for item in page.breadcrumb_pages offset:1 %}
+ <h4 class="{% if forloop.index0 > 0 %} with_preceding{% endif %}{% if forloop.rindex0 > 0 %} with_following{% endif %}">
+ <a href="{{item.url}}" class="list-group-item{% if item.path == page.menu_path %} active{% endif %} breadcrumb breadcrumb{{ forloop.index0 }}">
+ {{ item.title_in_menu }}</a></h4>
+ {% endfor %}
+ {% for item in page.menu %}
+ <a href="{{item.url}}" class="list-group-item{% if page.breadcrumbs contains item %} active{% endif %}">{{ item.title_in_menu }}</a>
+ {% endfor %}
+
+ {% else %} {% comment %} case 3a {% endcomment %}
+ {% for item in page.menu_parent.breadcrumb_pages offset:1 %}
+ <h4 class="{% if forloop.index0 > 0 %} with_preceding{% endif %}{% if forloop.rindex0 > 0 %} with_following{% endif %}">
+ <a href="{{item.url}}" class="list-group-item{% if item.path == page.menu_path %}{% unless item.menu_customization.force_inactive %} active{% endunless %}{% endif %} breadcrumb breadcrumb{{ forloop.index0 }}">
+ {{ item.title_in_menu }}</a></h4>
+ {% endfor %}
+ {% for item in page.menu_parent.menu %}
+ {% if (page.breadcrumb_paths contains item.menu_path) and page.menu %}
+ {% comment %} case 3b {% endcomment %}
+ <a href="{{item.url}}" class="list-group-item active with-sub-item">{{ item.title_in_menu }}</a>
+ <div class="sub-item">
+ {% for item2 in page.menu %}
+ <a href="{{item2.url}}" class="list-group-item sub-item">
+ {{ item2.title_in_menu }}</a>
+ {% endfor %}
+ </div>
+ {% else %}
+ {% comment %} case 3a side menu item {% endcomment %}
+ <a href="{{item.url}}" class="list-group-item{% if page.breadcrumb_paths contains item.menu_path %}{% unless item.menu_customization.force_inactive %} active{% endunless %}{% endif %}">{{ item.title_in_menu }}</a>
+ {% endif %}
+ {% endfor %}
+
+ {% endif %}
+ {% elsif page.menu %}
+ <!-- no pages have a menu without being in the top menu, won't come here -->
+ {% endif %}
+{% endunless %}
+
</div>
- {% endif %}
</div>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_plugins/read.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/read.rb b/docs/_plugins/read.rb
index ae0ba75..23cf0f2 100644
--- a/docs/_plugins/read.rb
+++ b/docs/_plugins/read.rb
@@ -60,9 +60,9 @@ module JekyllRead
def render(context)
filename = @text.strip
filename = context[filename] || filename
-
# Pathname API ignores first arg below if second is absolute
- file = Pathname.new(File.dirname(context['page']['path'])) + filename
+ page = context['page'] || context.registers[:page]
+ file = Pathname.new(File.dirname(page['path'])) + filename
file = file.cleanpath
# is there a better way to trim a leading / ?
file = file.relative_path_from(Pathname.new("/")) unless file.relative?
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_plugins/site_structure.rb
----------------------------------------------------------------------
diff --git a/docs/_plugins/site_structure.rb b/docs/_plugins/site_structure.rb
index e943730..70a07b6 100644
--- a/docs/_plugins/site_structure.rb
+++ b/docs/_plugins/site_structure.rb
@@ -1,22 +1,114 @@
+#
# Builds a hierarchical structure for the site, based on the YAML front matter of each page
-# Starts from a page called "index.md", and follows "children" links in the YAML front matter
+#
+# Starts from a page called "/index.md" (or the value of `root_menu_page` in _config.yml),
+# and follows `children` links in the YAML front matter, building up a variable called `data`
+# on `site` and on each referred `page`.
+#
+# In Ruby data is in page.data['menu'], but in templates `page.data` is promoted,
+# so you should just refer to things in markdown as `{{ page.menu }}`.
+#
+# Each `page.menu` entry will contain:
+# * `url` - URL (relative or absolute) to link to
+# * `title_in_menu` - title to show
+# * `menu_path` - the path of this page for the purposes of looking in breadcrumbs (usually page.path, unless overriden)
+# * `breadcrumbs_pages` - page items for ancestor items (and self)
+# * `breadcrumbs_paths` - paths of breadcrumb pages (useful for `if .. contains` jekyll tests)
+# * `menu_parent` - the parent menu which contains this page
+# * `menu_customization` - a hash of customization set in front matter or in children (can be any data you like)
+# * (in addition the entry may *be* the actual page object when the item is a page whose menu is not overridden)
+#
+# To build, set `children` as a list of either strings (the relative or absolute path to the child .md file),
+# or as maps with a `path` or `link` (absolute URL) key, a `title` (optional for `path`, to override the title from the file),
+# and (for `path` only) an optional `menu` block (to override the menu inherited from the `children` records in file),
+# `menu_customization` to set arbitrary data available (e.g. for templates to use when styling),
+# `href_path` to specify that an actual click should send to a different page than was used to produce the menu.
+#
+# For instance:
+#
+#children:
+#- child.md
+#- { path: child.md } # identical to above
+#- { path: child.md, title: "Child with New Name" } # overriding name
+#- { path: child.md, menu: [ { path: subchild.md, title: "Sub-Child with New Name" } ], href_path: subchild.md } # custom sub-menu with custom title, and click on main sends to submenu
+#- { path: child.md, menu: null } # suppress sub-menu (note `null` not `nil` because this is yaml)
+#
+# The menu is automatically generated for all files referenced from the root menu.
+# You can also set `breadcrumbs` as a list of paths in a page to force breadcrumbs, and
+# `menu_proxy_for` to have `menu_path` set differently to the usual `path` (highlight another page in a menu via breadcrumbs)
+# or `menu_parent` to a path to the menu which should be the parent of the current node.
+#
+# The hash `menu_customization` allows you to pass arbitrary data around, e.g. for use in styling.
+#
+# Additionally URL rewriting is done if a path map is set in _config.yaml,
+# with `path: { xxx: /new_xxx }` causing `/xxx/foo.html` to be rewritten as `/new_xxx/foo.html`.
+#
module SiteStructure
-
- BROOKLYN_WEBSITE_ROOT = "/website/index.md" unless defined? BROOKLYN_WEBSITE_ROOT
+
+ DEBUG = false
+
+ require 'yaml'
+# require 'pp'
+
+ class RewritePaths < Liquid::Tag
+ def initialize(tag_name, text, tokens)
+ super
+ @text = text
+ end
+ def render(context)
+ page = context['page']
+ site = context['site']
+ RewritePaths.rewrite_paths(site, page)
+ end
+
+ def self.rewrite_paths(site, page)
+ path = page['path']
+ page_hash = (page.is_a? Hash) ? page : page.data
+ # set url_basedir and apply path mapping
+ page_hash['url_basedir'] = File.dirname(path)+"/"
+ page_hash['url_basedir'].prepend("/") unless page_hash['url_basedir'].start_with? "/"
+
+ config_hash = (site.is_a? Hash) ? site : site.config
+
+ if ((config_hash['path']) && (config_hash['path'].is_a? Hash))
+ config_hash['path'].each {|key, value|
+ if (path.start_with?(key))
+ if ((!page.is_a? Hash) && page.url)
+ page.url.slice!("/"+key)
+ page.url.prepend(value)
+ end
+
+ page_hash['url_basedir'].slice!("/"+key)
+ page_hash['url_basedir'].prepend(value)
+ end
+ }
+ end
+
+ nil
+ end
+ end
+
+ Liquid::Template.register_tag('rewrite_paths', SiteStructure::RewritePaths)
+
class Generator < Jekyll::Generator
- def find_page_with_path_absolute_or_relative_to(site, path, referrent, structure_processed_pages)
+
+ @@verbose = false;
+
+ def self.find_page_with_path_absolute_or_relative_to(site, path, referrent, structure_processed_pages)
uncleaned_path = path
# Pathname API ignores first arg below if second is absolute
+# puts "converting #{path} wrt #{referrent ? referrent.path : ""}"
file = Pathname.new(File.dirname(referrent ? referrent.path : "")) + path
+ file += "index.md" if file.to_s.end_with? "/"
file = file.cleanpath
# is there a better way to trim a leading / ?
file = file.relative_path_from(Pathname.new("/")) unless file.relative?
path = "#{file}"
# look in our cache
- page = structure_processed_pages.detect { |item| item['path'] == path }
+ page = structure_processed_pages[path]
return page if page != nil
# look in site cache
@@ -28,91 +120,183 @@ module SiteStructure
unless page
# could not load it from pages, look on disk
-
- raise "No such file #{path} in site_structure call (from #{referrent ? referrent.path : ""})" unless file.exist?
-# puts "INFO: reading excluded file #{file} for site structure generation"
- page = Jekyll::Page.new(site, site.source, File.dirname(file), File.basename(file))
-
- throw "Could not find a page called: #{path} (referenced from #{referrent ? referrent.path : "root"})" unless page
- end
- # now apply standard clean-up
- if (page.url.start_with?("/website"))
- page.url.slice!("/website")
- page.url.prepend(site.config['path']['website'])
- end
- if (page.url.start_with?("/guide"))
- page.url.slice!("/guide")
- page.url.prepend(site.config['path']['guide'])
+ if file.exist?
+ puts "INFO: reading excluded file #{file} for site structure generation" if SiteStructure::DEBUG
+ page = Jekyll::Page.new(site, site.source, File.dirname(file), File.basename(file))
+ # make sure right url is set
+ RewritePaths.rewrite_paths(site, page)
+ end
+
+ unless page
+ raise "No such file #{path} in site_structure call (from #{referrent ? referrent.path : ""})" unless SiteStructure::DEBUG
+ puts "Could not find a page called: #{path} (referenced from #{referrent ? referrent.path : "root"}); skipping"
+ return nil
+ end
end
+
# and put in cache
- structure_processed_pages << page
+ structure_processed_pages[path] = page
page
end
def generate(site)
- structure_processed_pages = []
- root_page = find_page_with_path_absolute_or_relative_to(site, SiteStructure::BROOKLYN_WEBSITE_ROOT, nil, structure_processed_pages)
- navgroups = root_page.data['navgroups']
- navgroups.each do |ng|
- ng['page'] = find_page_with_path_absolute_or_relative_to(site, ng['page'], root_page, structure_processed_pages)
- if not ng['title_in_menu']
- ng['title_in_menu'] = ng['title'].capitalize
- end
- end
- site.data['navgroups'] = navgroups
- site.data['structure'] = gen_structure(site, SiteStructure::BROOKLYN_WEBSITE_ROOT, nil, navgroups, structure_processed_pages)
+ # rewrite paths
+ site.pages.each { |p| RewritePaths.rewrite_paths(site, p) }
+ structure_processed_pages = {}
+ # process root page
+ root_menu_page = site.config['root_menu_page']
+ puts "site_structure processing root menu page #{root_menu_page}" if @@verbose
+ site.data.merge!( Generator.gen_structure(site, { 'path' => root_menu_page }, nil, [], [], structure_processed_pages).data ) if root_menu_page
+ # process all pages
+ puts "site_structure now processing all pages" if @@verbose
+ site.pages.each { |p|
+ Generator.gen_structure(site, { 'path' => p.path }, nil, [], [], structure_processed_pages) if (p.path.end_with? ".md") && (!p['menu_processed'])
+ }
+ site.data['structure_processed_pages'] = structure_processed_pages
+# puts "ROOT menu is #{site.data['menu']}"
+# puts "PAGE menu is #{structure_processed_pages['website/documentation/index.md'].data['menu']}"
+# (but note, in the context hash map 'data' on pages is promoted, so you access it like {{ page.menu }})
end
- def render_liquid(site, page, content)
+ # processes liquid tags, e.g. in a link or path object
+ def self.render_liquid(site, page, content)
+ return content unless page
info = { :filters => [Jekyll::Filters], :registers => { :site => site, :page => page } }
page.render_liquid(content, site.site_payload, info)
end
-
- def gen_structure(site, pagename, parent, navgroups, structure_processed_pages)
- page = find_page_with_path_absolute_or_relative_to(site, pagename, parent, structure_processed_pages)
-
- # My navgroup is (first rule matches):
- # 1. what I have explicitly declared
- # 2. if I find my path referred to in the global navgroup list
- # 3. my parent's navgroup
- unless page.data['navgroup']
- match = navgroups.detect { |ng| ng['page'] == page }
- if match
- page.data['navgroup'] = match['id']
- elsif parent
- page.data['navgroup'] = parent.data['navgroup']
+
+ def self.gen_structure(site, item, parent, breadcrumb_pages_in, breadcrumb_paths_in, structure_processed_pages)
+ puts "gen_structure #{item} from #{parent ? parent.path : 'root'} (#{breadcrumb_paths_in})" if @@verbose
+ breadcrumb_pages = breadcrumb_pages_in.dup
+ breadcrumb_paths = breadcrumb_paths_in.dup
+ if (item.is_a? String)
+ item = { 'path' => item }
+ end
+ if (item['path'])
+ page = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, parent, item['path']), parent, structure_processed_pages)
+ # if nil and find_page doesn't raise, we are in debug mode, silently ignore
+ return nil unless page
+ # build up the menu info
+ if (item.length==1 && !page['menu_processed'])
+ puts "setting up #{item} from #{page.path} as original" if @@verbose
+ data = page.data
+ result = page
+ else
+ puts "setting up #{item} from #{page.path} as copy" if @@verbose
+ # if other fields are set on 'item' then we are overriding, so we have to take a duplicate
+ unless page['menu_processed']
+ # force processing if not yet processed, breadcrumbs etc set from that page
+ puts "making copy of #{page.path}" if @@verbose
+ page = gen_structure(site, "/"+page.path, parent, breadcrumb_pages_in, breadcrumb_paths_in, structure_processed_pages)
+ puts "copy is #{page.path}" if @@verbose
+ end
+ data = page.data.dup
+ data['data'] = data
+ result = data
+ end
+ data['path'] = page.path
+ if item['href_path']
+ href_page = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, page, item['href_path']), parent, structure_processed_pages)
+ else
+ href_page = page
end
+ data['url'] = href_page.url
+ puts "data is #{data}" if @@verbose
+ data['page'] = page
+ breadcrumb_pages << page
+ breadcrumb_paths << page.path
+ elsif (item['link'])
+ puts "setting up #{item} as link" if @@verbose
+ link = render_liquid(site, parent, item['link'])
+ data = { 'link' => link, 'url' => link }
+ breadcrumb_pages << data
+ breadcrumb_paths << data['link']
+ data['data'] = data
+ result = data
+ else
+ raise "Link to #{item} in #{parent ? parent.path : nil} must have link or path"
end
-
- # Figure out second level menu
- # If there's no parent => I'm at the top level, so no action
- # If there's a parent, but parent has no parent => I'm at second level, so set second-level menu
- # Otherwise, use the parent's second level menu
- if parent && !parent.data['parent']
- page.data['menu2parent'] = page
- page.data['menu2'] = page.data['children']
- elsif parent && parent.data['parent']
- page.data['menu2parent'] = parent.data['menu2parent']
- page.data['menu2'] = parent.data['menu2']
+
+ data['menu_customization'] = {}.merge(data['menu_customization'] || {}).merge(item['menu_customization'] || {})
+
+ data['breadcrumb_pages'] ||= breadcrumb_pages
+ data['breadcrumb_paths'] ||= breadcrumb_paths
+ data['menu_parent'] ||= parent
+
+ data['title_in_menu'] = render_liquid(site, parent, item['title_in_menu'] || item['title'] || data['title_in_menu'] || data['title'])
+# puts "built #{data}, now looking at children"
+
+ # if already processed then return now that we have set custom item overrides (don't recurse through children)
+ return result if data['menu']
+
+ data['menu_path'] = page.path if page
+
+ if data['menu_proxy_for']
+ menu_proxy_for = gen_structure(site, { 'path' => data['menu_proxy_for'], 'no_copy' => "because breadcrumbs won't be right" }, page, [], [], structure_processed_pages)
+ raise "missing menu_proxy_for #{data['menu_proxy_for']} in #{page.path}" unless menu_proxy_for
+ data['menu_path'] = menu_proxy_for['path']
+ # copy other data across
+ data.merge!(menu_proxy_for.select {|key, value| ['breadcrumb_paths', 'breadcrumb_pages', 'menu', 'title_in_menu', 'menu_parent', 'menu_customization'].include?(key) })
end
- page.data['parent'] = parent
- if page.data['children']
- page.data['children'].each do |c|
- if c['path']
- # links to another Jekyll site-structured page
- c['reference'] = gen_structure(site, render_liquid(site, page, c['path']), page, navgroups, structure_processed_pages)
- elsif c['link']
- # links to a non-site-structured page, on this site or elsewhere
- # allow title and link to use vars and tags (liquid processing)
- c['reference'] = { 'url' => render_liquid(site, page, c['link']), 'title' => render_liquid(site, page, c['title']) }
+ if data['breadcrumbs']
+ # if custom breadcrumbs set on page, use them instead
+ breadcrumb_pages = data['breadcrumb_pages'] = data['breadcrumbs'].collect { |path|
+ result = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, parent, path), page, structure_processed_pages)
+ raise "missing breadcrumb #{path} in #{page.path}" unless result
+ result
+ }
+ breadcrumb_paths = data['breadcrumb_paths'] = data['breadcrumb_pages'].collect { |p| p.path }
+ end
+
+ if data['menu_parent']
+ if data['menu_parent'].is_a? String
+ # if custom menu_parent was set as a string then load it
+ parent_result = find_page_with_path_absolute_or_relative_to(site, render_liquid(site, parent, data['menu_parent']), page, structure_processed_pages)
+ raise "missing parent #{data['menu_parent']} in #{page['path']}" unless parent_result
+ data['menu_parent'] = parent_result
+ if !data['breadcrumbs']
+ # TODO should we inherit actual menu parent breadcrumbs if not set on page?
+ end
+ end
+ else
+ # set menu_parent from breadcrumbs if not set (e.g. we are loading an isolated page)
+ data['menu_parent'] = page['breadcrumb_pages'][-1]
+ end
+
+ if (data['children'])
+ data['menu'] = []
+ puts "children of #{data['path']} - #{data['children']}" if @@verbose
+ data['children'].each do |child|
+ sub = gen_structure(site, child, page, breadcrumb_pages, breadcrumb_paths, structure_processed_pages)
+ if sub
+ if (!(child.is_a? String) && child.has_key?('menu'))
+ # process custom menu override
+ sub['menu'] = child['menu']
+ if (sub['menu'] != nil)
+ if sub['menu'].is_a? String
+ sub['menu'] = YAML.load(render_liquid(site, page, sub['menu'])) if sub['menu'].is_a? String
+ end
+ sub['menu'] = sub['menu'].collect { |mi|
+ gen_structure(site, mi, page, breadcrumb_pages, breadcrumb_paths, structure_processed_pages)
+ }
+ sub['menu'].compact!
+ end
+ end
+ data['menu'] << sub
+ puts "sub is #{sub['url']}" if @@verbose
+ else
+ raise "could not find #{child} in #{page.path}"
end
end
+ puts "end children of #{data['path']}" if @@verbose
end
- page
+ data['menu_processed']=true
+ puts "done #{item}" if @@verbose
+ result
end
end
end
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/advanced-concepts.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/advanced-concepts.md b/docs/guide/concepts/advanced-concepts.md
new file mode 100644
index 0000000..1b36170
--- /dev/null
+++ b/docs/guide/concepts/advanced-concepts.md
@@ -0,0 +1,14 @@
+---
+title: Advanced Concepts
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/application-parent-membership.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/application-parent-membership.md b/docs/guide/concepts/application-parent-membership.md
new file mode 100644
index 0000000..18f1a54
--- /dev/null
+++ b/docs/guide/concepts/application-parent-membership.md
@@ -0,0 +1,25 @@
+---
+title: Application, Parent and Membership
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+All entities have a ***parent*** entity, which creates and manages it, with one important exception: *applications*.
+Application entities are the top-level entities created and managed externally, manually or programmatically.
+
+Applications are typically defined in Brooklyn as an ***application descriptor***.
+This is a Java class specifying the entities which make up the application,
+by extending the class ``AbstractApplication``, and specifying how these entities should be configured and managed.
+
+All entities, including applications, can be the parent of other entities.
+This means that the "child" is typically started, configured, and managed by the parent.
+For example, an application may be the parent of a web cluster; that cluster in turn is the parent of web server processes.
+In the management console, this is represented hierarchically in a tree view.
+
+A parallel concept is that of ***membership***: in addition to one fixed parent,
+and entity may be a ***member*** of any number of special entities called ***groups***.
+Membership of a group can be used for whatever purpose is required;
+for example, it can be used to manage a collection of entities together for one purpose
+(e.g. wide-area load-balancing between locations) even though they may have been
+created by different parents (e.g. a multi-tier stack within a location).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/configuration-sensor-effectors.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/configuration-sensor-effectors.md b/docs/guide/concepts/configuration-sensor-effectors.md
new file mode 100644
index 0000000..5d57b4d
--- /dev/null
+++ b/docs/guide/concepts/configuration-sensor-effectors.md
@@ -0,0 +1,43 @@
+---
+title: Configuration, Sensors and Effectors
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+### Configuration
+
+All entities contain a map of config information. This can contain arbitrary values, typically keyed under static ``ConfigKey`` fields on the ``Entity`` sub-class. These values are inherited, so setting a configuration value at the
+application level will make it available in all entities underneath unless it is overridden.
+
+Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its ``start()`` method is invoked), so config values must be set before this occurs.
+
+Configuration values can be specified in a configuration file (``~/.brooklyn/brooklyn.properties``)
+to apply universally, and/or programmatically to a specific entity and its descendants
+by calling `.configure(KEY, VALUE)` in the entity spec when creating it.
+There is also an ``entity.setConfig(KEY, VALUE)`` method.
+
+Additionally, many common configuration parameters are available as "flags" which can be supplied as Strings when constructing
+then entity, in the form
+``EntitySpec.create˙(MyEntity.class).configure("config1", "value1").configure("config2", "value2")``.
+
+Documentation of the flags available for individual entities can normally be found in the javadocs.
+The ``@SetFromFlag`` annotations on ``ConfigKey`` static field definitions
+in the entity's interface is the recommended mechanism for exposing configuration options.
+
+
+### Sensors and Effectors
+
+***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the ``Entity`` subclass.
+
+Sensors can be updated by the entity or associated tasks, and sensors from an entity can be subscribed to by its parent or other entities to track changes in an entity's activity.
+
+Effectors can be invoked by an entity's parent remotely, and the invoker is able to track the execution of that effector. Effectors can be invoked by other entities, but use this functionality with care to prevent too many managers!
+
+An entity consists of a Java interface (used when interacting with the entity) and a Java class. For resilience. it is recommended to store
+the entity's state in attributes (see `getAttribute(AttributeKey)``). If internal fields can be used then the data will be lost on brooklyn
+restart, and may cause problems if the entity is to be moved to a different brooklyn management node.
+
+Next: [Advanced Concepts]({{site.path.guide}}/use/guide/defining-applications/advanced-concepts.html).
+See also: [Management > Sensors and Effectors]({{site.path.guide}}/use/guide/management/index.html#sensors-and-effectors).
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/dependent-configuration.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/dependent-configuration.md b/docs/guide/concepts/dependent-configuration.md
new file mode 100644
index 0000000..0ed60ff
--- /dev/null
+++ b/docs/guide/concepts/dependent-configuration.md
@@ -0,0 +1,34 @@
+---
+title: Dependent Configuration
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Under the covers Brooklyn has a sophisticated sensor event and subscription model, but conveniences around this model make it very simple to express cross-entity dependencies. Consider the example where Tomcat instances need to know the URL of a database (or a set of URLs to connect to a Monterey processing fabric, or other entities)
+
+{% highlight java %}
+setConfiguration(UsesJava.JAVA_OPTIONS, ImmutableMap.of("mysql.url",
+ attributeWhenReady(mysql, MySqlNode.MY_SQL_URL) ))
+{% endhighlight %}
+
+The ``attributeWhenReady(Entity, Sensor)`` call (a static method on the class ``DependentConfiguration``)
+causes the configuration value to be set when that given entity's attribue is ready.
+In the example, ``attributeWhenReady()`` causes the JVM system property ``mysql.url`` to be set to the value of the ``MySqlNode.MY_SQL_URL`` sensor from ``mysql`` when that value is ready. As soon as the database URL is announced by the MySql entity, the configuration value will be available to the Tomcat cluster.
+
+By default "ready" means being *set* (non-null) and, if appropriate, *non-empty* (for collections and strings) or *non-zero* (for numbers). Formally the interpretation of ready is that of "Groovy truth" defined by an ``asBoolean()`` method on the class and in the Groovy language extensions.
+
+You can customize "readiness" by supplying a ``Predicate`` (Google common) or ``Closure`` (Groovy) in a third parameter.
+This evaluates candidate values reported by the sensor until one is found to be ``true``.
+For example, passing ``{ it.size()>=3 }`` as the readiness argument would require at least three management plane URLs.
+
+More information on this can be found in the javadoc for ``DependentConfiguration``,
+along with a few other methods such as ``valueWhenAttributeReady`` which allow post-processing of an attribute value.
+
+Note that if the value of ``CONFIG_KEY`` passed to ``Entity.getConfig`` is a Closure or Task (such as returned by ``attributeWhenReady``),
+the first access of ``Entity.getConfig(CONFIG_KEY)`` will block until the task completes.
+Typically this does the right thing, blocking when necessary to generate the right start-up sequence
+without the developer having to think through the order, but it can take some getting used to.
+Be careful not to request config information until really necessary (or to use non-blocking "raw" mechanisms),
+and in complicated situations be ready to attend to circular dependencies.
+The management console gives useful information for understanding what is happening and resolving the cycle.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/entities.md b/docs/guide/concepts/entities.md
new file mode 100644
index 0000000..26981e7
--- /dev/null
+++ b/docs/guide/concepts/entities.md
@@ -0,0 +1,23 @@
+---
+title: Entities
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+The central concept in a Brooklyn deployment is that of an ***entity***.
+An entity represents a resource under management, either *base* entities (individual machines or software processes)
+or logical collections of these entities.
+
+Fundamental to the processing model is the capability of entities to be the *parent* of other entities (the mechanism by which collections are formed),
+with every entity having a single parent entity, up to the privileged top-level ***application*** entity.
+
+Entities are code, so they can be extended, overridden, and modified. Entities can have events, operations, and processing logic associated with them, and it is through this mechanism that the active management is delivered.
+
+The main responsibilities of an entity are:
+
+- Provisioning the entity in the given location or locations
+- Holding configuration and state (attributes) for the entity
+- Reporting monitoring data (sensors) about the status of the entity
+- Exposing operations (effectors) that can be performed on the entity
+- Hosting management policies and tasks related to the entity
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/execution.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/execution.md b/docs/guide/concepts/execution.md
new file mode 100644
index 0000000..4bb4875
--- /dev/null
+++ b/docs/guide/concepts/execution.md
@@ -0,0 +1,36 @@
+---
+title: Execution
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+All processing, whether an effector invocation or a policy cycle, are tracked as ***tasks***. This allows several important capabilities:
+
+* active and historic processing can be observed by operators
+* the invocation context is available in the thread, to check entitlement (permissions) and maintain a
+hierarchical causal chain even when operations are run in parallel
+* processing can be managed across multiple management nodes
+
+Some executions create new entities, which can then have tasks associated with them, and the system will record, for example, that a start efector on the new entity is a task associated with that entity, with that task
+created by a task associated with a different entity.
+
+The execution of a typical overall start-up sequence is shown below:
+
+[](brooklyn-flow-websequencediagrams.com.png)
+
+
+## Integration
+
+One vital aspect of Brooklyn is its ability to communicate with the systems it starts. This is abstracted using a ***driver*** facility in Brooklyn, where a
+driver describes how a process or service can be installed and managed using a particular technology.
+
+For example, a ``TomcatServer`` may implement start and other effectors using a ``TomcatSshDriver`` which inherits from ``JavaSoftwareProcessSshDriver`` (for JVM and JMX start confguration), inheriting from ``AbstractSoftwareProcessSshDriver``
+(for SSH scripting support).
+
+Particularly for sensors, some technologies are used so frequently that they are
+packaged as ***feeds*** which can discover their configuration (including from drivers). These include JMX and HTTP (see ``JmxFeed`` and ``HttpFeed``).
+
+Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems. See: [Extras]({{site.path.guide}}/use/guide/extras/index.html).
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/index.md b/docs/guide/concepts/index.md
new file mode 100644
index 0000000..5c81c2d
--- /dev/null
+++ b/docs/guide/concepts/index.md
@@ -0,0 +1,21 @@
+---
+title: Brooklyn Concepts
+title_in_menu: Brooklyn Concepts
+layout: website-normal
+children:
+- entities.md
+- application-parent-membership.md
+- configuration-sensor-effectors.md
+- lifecycle-managementcontext.md
+- dependent-configuration.md
+- location.md
+- policies.md
+- execution.md
+---
+
+This introduces brooklyn and describes how it simplifies the deployment and management of big applications. It is
+intended for people who are using brooklyn-supported application components (such as web/app servers, data stores)
+to be able to use brooklyn to easily start their application in multiple locations with off-the-shelf management
+policies.
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/lifecycle-managementcontext.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/lifecycle-managementcontext.md b/docs/guide/concepts/lifecycle-managementcontext.md
new file mode 100644
index 0000000..3495e17
--- /dev/null
+++ b/docs/guide/concepts/lifecycle-managementcontext.md
@@ -0,0 +1,44 @@
+---
+title: Lifecycle and ManagementContext
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Under-the-covers, at heart of the brooklyn management plane is the ``ManagementContext``.
+This is started automatically when using launching an application using the brooklyn CLI. For programmatic use, see
+``BrooklynLauncher.newLauncher().launch()``.
+
+A Brooklyn deployment consists of many entities in a hierarchical tree, with the privileged *application* entity at the top level.
+
+An application entity (``Application`` class) is responsible for starting the deployment of all its child entities (i.e. the entire entity tree under its ownership).
+
+An ``Application``'s ``start()`` method begins provisioning the child entities of the application (and their entities, recursively).
+
+Provisioning of entities typically happens in parallel automatically,
+although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is visible in the [web-based management console]({{site.path.guide}}/use/guide/management/index.html#console).
+
+Customized provisioning can be useful where two starting entities depend on each other. For example, it is often necessary to delay start of one entity until another entity reaches a certain state, and to supply run-time information about the latter to the former.
+
+<!-- TODO ambiguous language; need a better description of the "manage" lifecycle -->
+When new entities are created, the entity is wired up to an application by giving it a parent. The entity is then explicitly "managed", which allows other entities to discover it.
+
+Typically a Brooklyn deployment has a single management context which records:
+
+* all entities under management that are reachable by the application(s) via the parent-child relationships,
+* the state associated with each entity,
+* subscribers (listeners) to sensor events arising from the entities,
+* active tasks (jobs) associated with any the entity,
+* which Brooklyn management node is mastering (managing) each entity.
+
+<!-- TODO Distributed brooklyn not yet supported; needs clarification in docs -->
+
+In a multi-location deployment, management operates in all regions, with brooklyn entity instances being mastered in the relevant region.
+
+When management is distributed a Brooklyn deployment may consist of multiple Brooklyn management nodes each with a ``ManagementContext`` instance.
+
+<!-- TODO - Clarify the following statements.
+The management context entity forms part of the management plane.
+The management plane is responsible for the distribution of the ``Entity`` instances across multiple machines and multiple locations,
+tracking the transfer of events (subscriptions) between ``Entity`` instances, and the execution of tasks (often initiated by management policies).
+-->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/location.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/location.md b/docs/guide/concepts/location.md
new file mode 100644
index 0000000..2a06cac
--- /dev/null
+++ b/docs/guide/concepts/location.md
@@ -0,0 +1,22 @@
+---
+title: Location
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+<!-- TODO, Clarify is how geographical location works.
+-->
+
+Entities can be provisioned/started in the location of your choice. Brooklyn transparently uses [jclouds](http://www.jclouds.org) to support different cloud providers and to support BYON (Bring Your Own Nodes).
+
+The implementation of an entity (e.g. Tomcat) is agnostic about where it will be installed/started. When writing the application definition specify the location or list of possible locations (``Location`` instances) for hosting the entity.
+
+``Location`` instances represent where they run and indicate how that location (resource or service) can be accessed.
+
+For example, a ``JBoss7Server`` will usually be running in an ``SshMachineLocation``, which contains the credentials and address for sshing to the machine. A cluster of such servers may be running in a ``MachineProvisioningLocation``, capable of creating new ``SshMachineLocation`` instances as required.
+
+<!-- TODO, incorporate the following.
+
+The idea is that you could specify the location as AWS and also supply an image id. You could configure the Tomcat entity accordingly: specify the path if the image already has Tomcat installed, or specify that Tomcat must be downloaded/installed. Entities typically use _drivers_ (such as SSH-based) to install, start, and interact with their corresponding real-world instance.
+-->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/concepts/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/concepts/policies.md b/docs/guide/concepts/policies.md
new file mode 100644
index 0000000..ad8c0bb
--- /dev/null
+++ b/docs/guide/concepts/policies.md
@@ -0,0 +1,11 @@
+---
+title: Policies
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Policies perform the active management enabled by Brooklyn. Entities can have zero or more ``Policy`` instances attached to them.
+
+Policies can subscribe to sensors from entities or run periodically, and
+when they run they can perform calculations, look up other values, and if deemed necessary invoke effectors or emit sensor values from the entity with which they are associated.
[09/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/developers-catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/developers-catalog.xml b/docs/guide/dev/build/developers-catalog.xml
deleted file mode 100644
index 3afe052..0000000
--- a/docs/guide/dev/build/developers-catalog.xml
+++ /dev/null
@@ -1,87 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<catalog>
- <name>Brooklyn Developers Catalog</name>
-
- <template type="io.cloudsoft.cloudera.SampleClouderaManagedCluster" name="Cloudera CDH4">
- <description>Launches Cloudera Distribution for Hadoop Manager with a Cloudera Manager and an initial cluster of 4 CDH nodes
- (resizable) and default services including HDFS, MapReduce, and HBase</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloudera-icon.jpeg</iconUrl>
- </template>
-
- <template type="io.cloudsoft.mapr.MyM3App" name="M3 Cluster">
- <description>Map Reduce using MapR</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mapr-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.SimpleMongoDBReplicaSet" name="Simple MongoDB replica set">
- <description>Launches a MongoDB replica set</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mongo-db-icon.jpeg</iconUrl>
- </template>
-
- <template type="brooklyn.example.cloudfoundry.MovableCloudFoundryClusterExample" name="Stackato Movable CloudFoundry Cluster Example">
- <description>Brooklyn Stackato</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
- </template>
-
- <template type="brooklyn.example.cloudfoundry.MovableElasticWebAppCluster" name="Stackato Movable Elastic Web Cluster">
- <description>Brooklyn Stackato</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
- </template>
-
- <template type="io.cloudsoft.socialapps.drupal.examples.BasicDrupalApp" name="Basic Drupal App">
- <description>Brooklyn Social Apps - Basic. (Requires Debian)</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-icon.png</iconUrl>
- </template>
-
- <template type="io.cloudsoft.socialapps.drupal.examples.ClusteredDrupalApp" name="Clustered Drupal App">
- <description>Brooklyn Social Apps - Cluster. (Requires Debian)</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-text-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.extras.cloudfoundry.CloudFoundryJavaClusterExample" name="Cloud Foundry Web App">
- <description>Deploys a web application to a Cloud Foundry target</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloud-foundry-logo-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.SimpleRedisCluster" name="Redis Cluster">
- <description>Launches a Redis cluster</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/redis-sq-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.SimpleCassandraCluster" name="Cassandra Cluster">
- <description>Launches a Cassandra cluster</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cassandra-sq-icon.jpg</iconUrl>
- </template>
-
- <template type="brooklyn.demo.SimpleCouchDBCluster" name="CouchDB Cluster">
- <description>Launches a CouchDB cluster</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/couchdb-logo-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo 2: GeoDNS Web Fabric DB">
- <description>Deploys a demonstration web application to JBoss clusters around the world</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
- </template>
-
- <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo 1: Web Cluster with DB">
- <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
- <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
- </template>
-
-
- <classpath>
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-M2-incubating/brooklyn-example-global-web-fabric-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-portable-cloudfoundry/0.7.0-M2-incubating/brooklyn-example-portable-cloudfoundry-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-M2-incubating/brooklyn-example-simple-web-cluster-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-sql-webapp-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-messaging-pubsub/0.7.0-M2-incubating/brooklyn-example-simple-messaging-pubsub-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-parent/0.7.0-M2-incubating/brooklyn-examples-parent-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-webapp/0.7.0-M2-incubating/brooklyn-example-hello-world-webapp-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-nosql-cluster/0.7.0-M2-incubating/brooklyn-example-simple-nosql-cluster-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-webapps-parent/0.7.0-M2-incubating/brooklyn-examples-webapps-parent-0.7.0-M2-incubating.jar</entry> <!-- BROOKLYN_VERSION -->
- </classpath>
-
-
-</catalog>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/eclipse.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/eclipse.include.md b/docs/guide/dev/build/eclipse.include.md
deleted file mode 100644
index e0dc3c0..0000000
--- a/docs/guide/dev/build/eclipse.include.md
+++ /dev/null
@@ -1,15 +0,0 @@
-
-- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler)
- (typically bundled with Eclipse or available in the default update site set)
-
-- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates)
- (typically bundled with Eclipse or available in the default update site set)
-
-- Groovy Plugin: GRECLIPSE from
- [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3)
- (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2)
- or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)).
- Be sure to include Groovy 1.8.6 compiler support and Maven-Eclipse (m2e) support.
- More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin).
-
-- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/ide.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/ide.md b/docs/guide/dev/build/ide.md
deleted file mode 100644
index 3abae3c..0000000
--- a/docs/guide/dev/build/ide.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-layout: guide-normal
-title: IDE Setup
-toc: /guide/toc.json
----
-
-Gone are the days when IDE integration always just works... Maven and Eclipse fight,
-neither quite gets along perfectly with Groovy,
-git branch switches (sooo nice) can be slow, etc etc.
-
-But with a bit of a dance the IDE can still be your friend,
-making it much easier to run tests and debug.
-
-As a general tip, don't always trust the IDE to build correctly; if you hit a snag,
-do a command-line ``mvn clean install`` (optionally with ``-DskipTests``)
-then refresh the project.
-
-See instructions below for specific IDEs.
-
-
-## Eclipse
-
-If you're an Eclipse user, you'll probably want the Maven (m2e) plugin
-and the Groovy Eclipse plugin (used for testing and examples primarily).
-You may also want Git and TestNG plugins.
-You can install these using Help -> Install New Software, or from the Eclipse Marketplace:
-
-{% readj eclipse.include.md %}
-
-As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used,
-and the codebase can be imported (Import -> Existing Maven Projects)
-and successfully built and run inside an IDE.
-However there are quirks, and mileage may vary.
-
-If you encounter issues, the following hints may be helpful:
-
-* If you attempt to import projects before the plugins are installed, you may encounter errors such as
- '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``',
- and the projects will not be recognized as java projects. If you do, simply cancel the import
- (or delete the imported projects if they have been imported) and install the plugins as described above.
- If you have installed plugins from alternative locations, remove them and re-install them from the locations
- specified above.
-
-* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh
- can be useful to re-populate files which need to be copied to `target/`
-
-* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files
- (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install
- from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix
- `.classpath`s).
- Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure)
- or the filesystem, or use
- the following command to remove these rogue blocks in the generated `.classpath` files:
-
-{% highlight bash %}
-% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
-{% endhighlight %}
-
-* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later".
- The build-helper connector is useful if you're prompted for it, but
- do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway).
- You can manually mark as permanently ignored certain errors;
- this updates the pom.xml (and should be current).
-
-* You may need to ensure ``src/main/{java,resources}`` is created in each project dir,
- if (older versions) complain about missing directories,
- and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists):
-
-{% highlight bash %}
-find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;
-{% endhighlight %}
-
-* You may need to add the groovy nature (or even java nature) to projects;
- with some maven-eclipse plugins this works fine,
- but for others (older ones) you may need to handcraft these
- (either right-click the project in the Package Explorer and choose Configure,
- or edit the ``.project`` manually adding it to the project properties).
- The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful.
-
-If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls.
-(And if you have a tip we haven't mentioned please let us know that too!)
-
-
-
-## IntelliJ IDEA
-
-To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed
-via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder,
-(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects.
-
-There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use
-generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler
-level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans:
-
-> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation
-> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would
-> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings |
-> Compiler | Java Compiler | "Use Compiler" combobox).
-
-
-## Netbeans
-
-Tips from Netbeans users wanted!
-
-
-
-## Debugging Tips
-
-To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may
-need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql
-project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui
-folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For
-Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``.
-
-To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript.
-When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option
-to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value.
-
-When running at the command line you can enable remote connections so that one can attach a debugger to the Java process:
- Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005``
-
-To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ -
-Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/index.md b/docs/guide/dev/build/index.md
deleted file mode 100644
index 90aa6fa..0000000
--- a/docs/guide/dev/build/index.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 %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/tests.md b/docs/guide/dev/build/tests.md
deleted file mode 100644
index f202dc2..0000000
--- a/docs/guide/dev/build/tests.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-layout: guide-normal
-title: Tests
-toc: /guide/toc.json
----
-
-We have the following tests groups:
-
-* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files)
-* Integration -- deploys locally, may read and write from internet, takes longer.
- If you change an entity, rerun the relevant integration test to make sure all is well!
-* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block)
-* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the
- time/cost of those tests.
-* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles,
- while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line.
-* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests
-
-To run these from the command line, use something like the following:
-
-* normal: `mvn clean install`
-* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true`
-* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true`
-* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true`
-
-<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/build/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/toc.json b/docs/guide/dev/build/toc.json
deleted file mode 100644
index 192f1e3..0000000
--- a/docs/guide/dev/build/toc.json
+++ /dev/null
@@ -1,8 +0,0 @@
-[
-{ "title": "Maven",
- "file": "{{ site.path.guide }}/dev/build/index.html" },
-{ "title": "IDE",
- "file": "{{ site.path.guide }}/dev/build/ide.html" },
-{ "title": "Tests",
- "file": "{{ site.path.guide }}/dev/build/tests.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/entity.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/entity.md b/docs/guide/dev/code/entity.md
deleted file mode 100644
index f84e23c..0000000
--- a/docs/guide/dev/code/entity.md
+++ /dev/null
@@ -1,91 +0,0 @@
----
-layout: guide-normal
-title: Writing an Entity
-toc: /guide/toc.json
----
-
-## Ways to write an entity
-
-There are several ways to write a new entity:
-
-* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`.
-* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**.
-* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`.
-* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef)
-
-The rest of this section covers writing an entity in pure-java (or other JVM languages).
-
-
-## Things To Know
-
-All entities have an interface and an implementation. The methods on the interface
-are its effectors; the interface also defines its sensors.
-
-Entities are created through the management context (rather than calling the
-constructor directly). This returns a proxy for the entity rather than the real
-instance, which is important in a distributed management plane.
-
-All entity implementations inherit from `AbstractEntity`,
-often through one of the following:
-
-* **`SoftwareProcessImpl`**: if it's a software process
-* **`VanillaJavaAppImpl`**: if it's a plain-old-java app
-* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app
-* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities
-
-Software-based processes tend to use *drivers* to install and
-launch the remote processes onto *locations* which support that driver type.
-For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass,
-targetting `SshMachineLocation` (a machine to which Brooklyn can ssh).
-The various `SoftwareProcess` entities above (and some of the exemplars
-listed at the end of this page) have their own dedicated drivers.
-
-Finally, there are a collection of *traits*, such as `Resizable`,
-in the package ``brooklyn.entity.trait``. These provide common
-sensors and effectors on entities, supplied as interfaces.
-Choose one (or more) as appropriate.
-
-
-
-## Key Steps
-
-So to get started:
-
-1. Create your entity interface, extending the appropriate selection from above,
- to define the effectors and sensors.
-2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface,
- where `YourEntityImpl` will be the class name for your entity implementation.
-3. Create your entity class, implementing your entity interface and extending the
- classes for your chosen entity super-types. Naming convention is a suffix "Impl"
- for the entity class, but this is not essential.
-4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`).
- The naming convention is to have a suffix "Driver".
-5. Create the driver class, implementing your driver interface, and again extending as appropriate.
- Naming convention is to have a suffix "SshDriver" for an ssh-based implementation.
- The correct driver implementation is found using this naming convention, or via custom
- namings provided by the `BasicEntityDriverFactory`.
-6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify
- your driver interface.
-7. Provide the implementation of missing lifecycle methods in your driver class (details below)
-8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`)..
- See the sensor feeds, such as `HttpFeed` and `JmxFeed`.
-
-Any JVM language can be used to write an entity. However use of pure Java is encouraged for
-entities in core brooklyn.
-
-
-## Helpful References
-
-A few handy pointers will help make it easy to build your own entities.
-Check out some of the exemplar existing entities
-(note, some of the other entities use deprecated utilities and a deprecated class
-hierarchy; it is suggested to avoid these, looking at the ones below instead):
-
-* `JBoss7Server`
-* `MySqlNode`
-
-You might also find the following helpful:
-
-* **[Entity Design Tips]({{site.path.guide}}/dev/tips/index.html#EntityDesign)**
-* The **[User Guide]({{site.path.guide}}/use/guide/index.html)**
-* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)**
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.include.md b/docs/guide/dev/code/index.include.md
deleted file mode 100644
index d25c163..0000000
--- a/docs/guide/dev/code/index.include.md
+++ /dev/null
@@ -1,96 +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)
-
-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/a7a317bf/docs/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.md b/docs/guide/dev/code/index.md
index 8220a8d..1d4407b 100644
--- a/docs/guide/dev/code/index.md
+++ b/docs/guide/dev/code/index.md
@@ -1,7 +1,94 @@
---
-layout: guide-normal
-title: Code Structure
-toc: /guide/toc.json
+title: About the Code
+layout: website-normal
---
-{% readj index.include.md %}
+## 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](../env/maven-build.html)
+* [IDE setup](../env/ide/)
+* [Tests](tests.html)
+* [Tips](../tips/)
+* [Remote Debugging](../tips/debugging-remote-brooklyn.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/a7a317bf/docs/guide/dev/code/policy.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/policy.md b/docs/guide/dev/code/policy.md
deleted file mode 100644
index a62bdd2..0000000
--- a/docs/guide/dev/code/policy.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-layout: guide-normal
-title: Writing a Policy
-toc: /guide/toc.json
----
-
-Policies perform the active management enabled by Brooklyn.
-Each policy instance is associated with an entity,
-and at runtime it will typically subscribe to sensors on that entity or children,
-performing some computation and optionally actions when a subscribed sensor event occurs.
-This action might be invoking an effector or emitting a new sensor,
-depending the desired behvaiour is.
-
-Writing a policy is straightforward.
-Simply extend ``AbstractPolicy``,
-overriding the ``setEntity`` method to supply any subscriptions desired:
-
-{% highlight java %}
- @Override
- public void setEntity(EntityLocal entity) {
- super.setEntity(entity)
- subscribe(entity, TARGET_SENSOR, this)
- }
-{% endhighlight %}
-
-and supply the computation and/or activity desired whenever that event occurs:
-
-{% highlight java %}
- @Override
- public void onEvent(SensorEvent<Integer> event) {
- int val = event.getValue()
- if (val % 2 == 1)
- entity.sayYoureOdd();
- }
-{% endhighlight %}
-
-You'll want to do more complicated things, no doubt,
-like access other entities, perform multiple subscriptions,
-and emit other sensors -- and you can.
-See the source code, and see some commonly used policies
-in ``AutoScalerPolicy`` and ``RollingMeanEnricher``.
-
-One rule of thumb, to close on:
-try to keep policies simple, and compose them together at runtime;
-for instance, if a complex computation triggers an action,
-define one **enricher** policy to aggregate other sensors and emit a new sensor,
-then write a second policy to perform that action.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/tests.md b/docs/guide/dev/code/tests.md
new file mode 100644
index 0000000..f202dc2
--- /dev/null
+++ b/docs/guide/dev/code/tests.md
@@ -0,0 +1,26 @@
+---
+layout: guide-normal
+title: Tests
+toc: /guide/toc.json
+---
+
+We have the following tests groups:
+
+* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files)
+* Integration -- deploys locally, may read and write from internet, takes longer.
+ If you change an entity, rerun the relevant integration test to make sure all is well!
+* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block)
+* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the
+ time/cost of those tests.
+* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles,
+ while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line.
+* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests
+
+To run these from the command line, use something like the following:
+
+* normal: `mvn clean install`
+* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true`
+* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true`
+* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true`
+
+<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/code/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/toc.json b/docs/guide/dev/code/toc.json
deleted file mode 100644
index 6bb112b..0000000
--- a/docs/guide/dev/code/toc.json
+++ /dev/null
@@ -1,10 +0,0 @@
-[
-{ "title": "Structure",
- "file": "{{ site.path.guide }}/dev/code/index.html" },
-{ "title": "Writing an Entity",
- "file": "{{ site.path.guide }}/dev/code/entity.html" },
-{ "title": "Writing a Policy",
- "file": "{{ site.path.guide }}/dev/code/policy.html" },
-{ "title": "brooklyn.git (github)",
- "file": "http://github.com/apache/incubator-brooklyn" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/ide/eclipse.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/ide/eclipse.include.md b/docs/guide/dev/env/ide/eclipse.include.md
new file mode 100644
index 0000000..b1cf5ea
--- /dev/null
+++ b/docs/guide/dev/env/ide/eclipse.include.md
@@ -0,0 +1,15 @@
+
+- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler)
+ (typically bundled with Eclipse or available in the default update site set)
+
+- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates)
+ (typically bundled with Eclipse or available in the default update site set)
+
+- Groovy Plugin: GRECLIPSE from
+ [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3)
+ (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2)
+ or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)).
+ Be sure to include Groovy 2.3.4 compiler support and Maven-Eclipse (m2e) support.
+ More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin).
+
+- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/ide/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/ide/index.md b/docs/guide/dev/env/ide/index.md
new file mode 100644
index 0000000..3abae3c
--- /dev/null
+++ b/docs/guide/dev/env/ide/index.md
@@ -0,0 +1,123 @@
+---
+layout: guide-normal
+title: IDE Setup
+toc: /guide/toc.json
+---
+
+Gone are the days when IDE integration always just works... Maven and Eclipse fight,
+neither quite gets along perfectly with Groovy,
+git branch switches (sooo nice) can be slow, etc etc.
+
+But with a bit of a dance the IDE can still be your friend,
+making it much easier to run tests and debug.
+
+As a general tip, don't always trust the IDE to build correctly; if you hit a snag,
+do a command-line ``mvn clean install`` (optionally with ``-DskipTests``)
+then refresh the project.
+
+See instructions below for specific IDEs.
+
+
+## Eclipse
+
+If you're an Eclipse user, you'll probably want the Maven (m2e) plugin
+and the Groovy Eclipse plugin (used for testing and examples primarily).
+You may also want Git and TestNG plugins.
+You can install these using Help -> Install New Software, or from the Eclipse Marketplace:
+
+{% readj eclipse.include.md %}
+
+As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used,
+and the codebase can be imported (Import -> Existing Maven Projects)
+and successfully built and run inside an IDE.
+However there are quirks, and mileage may vary.
+
+If you encounter issues, the following hints may be helpful:
+
+* If you attempt to import projects before the plugins are installed, you may encounter errors such as
+ '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``',
+ and the projects will not be recognized as java projects. If you do, simply cancel the import
+ (or delete the imported projects if they have been imported) and install the plugins as described above.
+ If you have installed plugins from alternative locations, remove them and re-install them from the locations
+ specified above.
+
+* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh
+ can be useful to re-populate files which need to be copied to `target/`
+
+* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files
+ (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install
+ from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix
+ `.classpath`s).
+ Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure)
+ or the filesystem, or use
+ the following command to remove these rogue blocks in the generated `.classpath` files:
+
+{% highlight bash %}
+% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
+{% endhighlight %}
+
+* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later".
+ The build-helper connector is useful if you're prompted for it, but
+ do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway).
+ You can manually mark as permanently ignored certain errors;
+ this updates the pom.xml (and should be current).
+
+* You may need to ensure ``src/main/{java,resources}`` is created in each project dir,
+ if (older versions) complain about missing directories,
+ and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists):
+
+{% highlight bash %}
+find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;
+{% endhighlight %}
+
+* You may need to add the groovy nature (or even java nature) to projects;
+ with some maven-eclipse plugins this works fine,
+ but for others (older ones) you may need to handcraft these
+ (either right-click the project in the Package Explorer and choose Configure,
+ or edit the ``.project`` manually adding it to the project properties).
+ The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful.
+
+If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.path.guide}}/meta/contact.html) and we can hopefully share our pearls.
+(And if you have a tip we haven't mentioned please let us know that too!)
+
+
+
+## IntelliJ IDEA
+
+To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed
+via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder,
+(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects.
+
+There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use
+generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler
+level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans:
+
+> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation
+> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would
+> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings |
+> Compiler | Java Compiler | "Use Compiler" combobox).
+
+
+## Netbeans
+
+Tips from Netbeans users wanted!
+
+
+
+## Debugging Tips
+
+To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may
+need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql
+project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui
+folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For
+Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``.
+
+To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript.
+When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option
+to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value.
+
+When running at the command line you can enable remote connections so that one can attach a debugger to the Java process:
+ Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005``
+
+To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ -
+Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/index.md b/docs/guide/dev/env/index.md
new file mode 100644
index 0000000..ef00e89
--- /dev/null
+++ b/docs/guide/dev/env/index.md
@@ -0,0 +1,13 @@
+---
+title: Dev Environment
+layout: website-normal
+breadcrumbs:
+- /website/documentation/index.md
+- ../index.md
+- index.md
+children:
+- maven-build.md
+- ide/
+---
+
+TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/env/maven-build.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/env/maven-build.md b/docs/guide/dev/env/maven-build.md
new file mode 100644
index 0000000..90aa6fa
--- /dev/null
+++ b/docs/guide/dev/env/maven-build.md
@@ -0,0 +1,184 @@
+---
+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 %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/how-to-contrib.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/how-to-contrib.md b/docs/guide/dev/how-to-contrib.md
deleted file mode 100644
index 120d3d9..0000000
--- a/docs/guide/dev/how-to-contrib.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-layout: guide-normal
-title: How to Contribute
-toc: /guide/toc.json
----
-
-### The Process
-
-If you've built something which you think others could use, or are interested in doing so --
-whether a new supported entity, or a policy, or an example --
-it's easy to give back to the community. Just:
-
-1. **Tell [the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** about your work or interest
-
-1. **Create your fork** of the project on GitHub
-
-1. **Clone it** to your local machine and do your work on it
-
-1. **Push it**, and tell everyone about it
-
-1. **Sign the relevant Apache contributor agreement(s)**
-
-1. **Issue a pull request** from your GitHub repo
-
-The same process holds for contributing to this documentation (web site and user guide),
-but see the additional [tips for updating documentation]({{ site.path.guide }}/dev/tips/update-docs.html).
-
-
-### Some Words of Advice
-
-* Do early-stage work in the ``/sandbox``, which means we can pulled it in to ``master`` more often --
- keeping branches short-lived and making it easier to collaborate!
-
-* Include javadoc and tests
-
-* See the [tips here]({{site.path.guide}}/dev/tips/index.html)
-
-* If you get blocked, **[hollar]({{site.path.guide}}/meta/contact.html)**!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
index c6c9e33..31dd7e1 100644
--- a/docs/guide/dev/index.md
+++ b/docs/guide/dev/index.md
@@ -1,7 +1,30 @@
---
-layout: guide-normal
-title: Getting to Code
-toc: /guide/toc.json
+title: Developer Guide
+layout: website-normal
+menu_parent: /website/documentation/
+breadcrumbs:
+- /website/documentation/index.md
+- /guide/dev/index.md
+children:
+- env/
+- code/
+- code/tests.md
+- tips/
+- tips/logging.md
+- tips/debugging-remote-brooklyn.md
---
-{% readj code/index.include.md %}
+The Developer Guide contains information on working with the Brooklyn codebase.
+
+Of particular note to people getting started, there is:
+
+* Help with Maven
+* Help with Git
+* Help setting up IDE's
+
+And for the Brooklyn codebase itself, see:
+
+* Project structure
+* Areas of Special Hairiness
+
+(All links are TODO.)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/links.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/links.md b/docs/guide/dev/links.md
deleted file mode 100644
index 6fd12e2..0000000
--- a/docs/guide/dev/links.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-layout: guide-normal
-title: Development Bookmarks
-toc: ../toc.json
----
-
-{% include fields.md %}
-
-Handy places:
-
-* **Code** is in Github at [https://github.com/apache/incubator-brooklyn/](https://github.com/apache/incubator-brooklyn/)
-
-* **Issues** are in Jira at [https://issues.apache.org/jira/browse/BROOKLYN/](https://issues.apache.org/jira/browse/BROOKLYN/)
-
-* **Maven repositories** are:
- * [Apache releases]({{ apache_releases_repo_groupid_url }})
- * [Apache snapshots]({{ apache_snapshots_repo_groupid_url }})
- * Other repositories are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases
- and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots
-
-* **CI server** is a jenkins server at: [https://builds.apache.org/job/incubator-brooklyn-master-build/](https://builds.apache.org/job/incubator-brooklyn-master-build/)
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/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
new file mode 100644
index 0000000..337aa21
--- /dev/null
+++ b/docs/guide/dev/tips/debugging-remote-brooklyn.md
@@ -0,0 +1,140 @@
+---
+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/a7a317bf/docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md
index e809b7d..9045fe9 100644
--- a/docs/guide/dev/tips/index.md
+++ b/docs/guide/dev/tips/index.md
@@ -1,7 +1,6 @@
---
layout: guide-normal
title: Miscellaneous Tips and Tricks
-toc: /guide/toc.json
---
## General Good Ways of Working
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/local-artifact-repo.md b/docs/guide/dev/tips/local-artifact-repo.md
deleted file mode 100644
index 455a545..0000000
--- a/docs/guide/dev/tips/local-artifact-repo.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-layout: guide-normal
-title: Prepopulating a Local Artifact Repository
-toc: /guide/toc.json
----
-
-On occasion it can be useful to have/control/prepopulate a local repository of entity installers <small>[1]</small>.
-
-The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder:
-
- wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/
-
-Brooklyn's default search behaviour for installation artifacts is as follows:
-
-1. The local `~/.brooklyn/repository/` folder.
-2. The entity's installer's public download url (or an overridden url if one has been specified).
-3. Cloudsoft's fallback repository.
-
-Cloudsoft's fallback repository <small>[2]</small> contains many of the installation artifacts used by current Brooklyn entities.
-
-It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis.
-
-If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from fallback behaviour, allowing out-of-date entities to be more easily identified and updated.
-
-<br />
-<small>
-<ol>
-<li>For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do <small>[3]</small>.</li>
-<li><a href="http://downloads.cloudsoftcorp.com/brooklyn/repository/">downloads.cloudsoftcorp.com/brooklyn/repository</a></li>
-<li>This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.</li>
-</ol>
-</small>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/guide/dev/tips/logging.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/logging.md b/docs/guide/dev/tips/logging.md
index e9e3ffc..7c4543c 100644
--- a/docs/guide/dev/tips/logging.md
+++ b/docs/guide/dev/tips/logging.md
@@ -1,7 +1,6 @@
---
-layout: guide-normal
title: Logging
-toc: /guide/toc.json
+layout: website-normal
---
## Logging: A Quick Overview
@@ -66,6 +65,10 @@ For example:
configuration file, except it should be wrapped in ``<included>`` XML tags rather
than ``<configuration>`` XML tags (because it is included from the ``logback.xml``
which comes with ``brooklyn-logback-xml``.)
+* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``.
+ This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything
+ logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else
+ will end up in ``jclouds.log``.
You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
If you do, logback will detect multiple files with that name and will scream at you.
[11/13] incubator-brooklyn git commit: wholesale replacement by docs
folder from master
Posted by he...@apache.org.
wholesale replacement by docs folder from master
cherrypicking is too conflicted; it now points to wrong version but i'm about to fix that
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/a7a317bf
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/a7a317bf
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/a7a317bf
Branch: refs/heads/0.7.0-M2-incubating-docs
Commit: a7a317bf51d181749fa1fe196155c3a18d0b29ed
Parents: f31c828
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Jan 9 16:01:06 2015 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Jan 9 16:01:06 2015 +0000
----------------------------------------------------------------------
docs/README.md | 19 +-
docs/_build/build.sh | 25 +-
docs/_build/config-exclude-all-but-guide.yml | 2 +-
docs/_build/config-exclude-guide.yml | 2 +-
docs/_build/make-javadoc.sh | 19 +-
docs/_build/quick-make-few-javadoc.sh | 2 +-
docs/_config.yml | 6 +-
.../_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/highlevel1.md | 50 +++
docs/_extra/list-of-blueprints.md | 160 +++++++
docs/_extra/local-artifact-repo.md | 32 ++
docs/_extra/meta/brooklyn-gpg-public-key.asc | 21 +
docs/_extra/meta/contact.include.md | 9 +
docs/_extra/meta/contact.md | 7 +
docs/_extra/meta/irc.md | 31 ++
docs/_extra/meta/toc.json | 8 +
docs/_extra/meta/versions.md | 110 +++++
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/update-docs.md | 14 +
docs/_includes/list-children.html | 7 +
docs/_includes/topmenu.html | 38 +-
docs/_layouts/guide-normal.html | 44 +-
docs/_layouts/guide-old.html | 65 +++
docs/_layouts/website-normal.html | 62 ++-
docs/_plugins/read.rb | 4 +-
docs/_plugins/site_structure.rb | 322 +++++++++++---
docs/guide/concepts/advanced-concepts.md | 14 +
.../concepts/application-parent-membership.md | 25 ++
.../concepts/configuration-sensor-effectors.md | 43 ++
docs/guide/concepts/dependent-configuration.md | 34 ++
docs/guide/concepts/entities.md | 23 +
docs/guide/concepts/execution.md | 36 ++
docs/guide/concepts/index.md | 21 +
.../concepts/lifecycle-managementcontext.md | 44 ++
docs/guide/concepts/location.md | 22 +
docs/guide/concepts/policies.md | 11 +
docs/guide/dev/build/developers-catalog.xml | 87 ----
docs/guide/dev/build/eclipse.include.md | 15 -
docs/guide/dev/build/ide.md | 123 ------
docs/guide/dev/build/index.md | 184 --------
docs/guide/dev/build/tests.md | 26 --
docs/guide/dev/build/toc.json | 8 -
docs/guide/dev/code/entity.md | 91 ----
docs/guide/dev/code/index.include.md | 96 -----
docs/guide/dev/code/index.md | 95 ++++-
docs/guide/dev/code/policy.md | 47 ---
docs/guide/dev/code/tests.md | 26 ++
docs/guide/dev/code/toc.json | 10 -
docs/guide/dev/env/ide/eclipse.include.md | 15 +
docs/guide/dev/env/ide/index.md | 123 ++++++
docs/guide/dev/env/index.md | 13 +
docs/guide/dev/env/maven-build.md | 184 ++++++++
docs/guide/dev/how-to-contrib.md | 38 --
docs/guide/dev/index.md | 31 +-
docs/guide/dev/links.md | 22 -
.../guide/dev/tips/debugging-remote-brooklyn.md | 140 +++++++
docs/guide/dev/tips/index.md | 1 -
docs/guide/dev/tips/local-artifact-repo.md | 32 --
docs/guide/dev/tips/logging.md | 7 +-
docs/guide/dev/tips/release.md | 288 -------------
docs/guide/dev/tips/standards.md | 15 -
docs/guide/dev/tips/toc.json | 14 -
docs/guide/dev/tips/update-docs.md | 14 -
docs/guide/dev/toc.json | 26 --
docs/guide/index.md | 22 +-
docs/guide/java/archetype.md | 64 +++
docs/guide/java/common-usage.md | 42 ++
docs/guide/java/defining-and-deploying.md | 123 ++++++
docs/guide/java/entities.md | 126 ++++++
docs/guide/java/entity.md | 90 ++++
docs/guide/java/index.md | 22 +
docs/guide/java/policies.md | 123 ++++++
docs/guide/java/policy.md | 46 ++
docs/guide/java/service-state.md | 73 ++++
...topology-dependencies-management-policies.md | 69 +++
docs/guide/java/wt-deployed-application-700.png | Bin 0 -> 176494 bytes
docs/guide/java/wt-deployed-application.png | Bin 0 -> 127347 bytes
docs/guide/java/wt-starting-700.png | Bin 0 -> 303892 bytes
docs/guide/java/wt-starting.png | Bin 0 -> 332710 bytes
docs/guide/java/wt-tree-jboss-sensors-700.png | Bin 0 -> 268853 bytes
docs/guide/java/wt-tree-jboss-sensors.png | Bin 0 -> 169929 bytes
docs/guide/license/index.md | 18 -
docs/guide/license/license.md | 194 ---------
docs/guide/license/toc.json | 4 -
docs/guide/meta/brooklyn-gpg-public-key.asc | 21 -
docs/guide/meta/contact.include.md | 9 -
docs/guide/meta/contact.md | 7 -
docs/guide/meta/irc.md | 31 --
docs/guide/meta/toc.json | 8 -
docs/guide/meta/versions.md | 113 -----
docs/guide/misc/download.md | 170 ++++++++
docs/guide/misc/index.md | 20 +
docs/guide/misc/javadoc/index.md | 11 +
docs/guide/misc/known-issues.md | 27 ++
docs/guide/misc/release-notes.md | 52 +++
docs/guide/ops/index.md | 11 +
docs/guide/ops/locations/configuring.md | 105 +++++
docs/guide/ops/locations/index.md | 101 +++++
docs/guide/ops/persistence/index.md | 274 ++++++++++++
docs/guide/ops/webconsole/index.md | 399 ++++++++++++++++++
.../webconsole/webconsole-dashboard-w400.png | Bin 0 -> 137463 bytes
.../ops/webconsole/webconsole-dashboard.png | Bin 0 -> 214723 bytes
.../ops/webconsole/webconsole-detail-w400.png | Bin 0 -> 111993 bytes
docs/guide/ops/webconsole/webconsole-detail.png | Bin 0 -> 165359 bytes
docs/guide/start/_my-web-cluster.yaml | 19 +
docs/guide/start/blueprints.md | 57 +++
docs/guide/start/brooklyn.properties | 324 ++++++++++++++
docs/guide/start/catalog.xml | 22 +
docs/guide/start/config.md | 50 +++
docs/guide/start/docs-summary.include.md | 7 -
docs/guide/start/docs-summary.md | 9 -
docs/guide/start/download.md | 171 --------
...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.include.md | 50 ---
docs/guide/start/index.md | 13 +-
docs/guide/start/known-issues.md | 28 --
docs/guide/start/managing.md | 40 ++
docs/guide/start/policies.md | 36 ++
docs/guide/start/release-notes.md | 51 ---
docs/guide/start/running.md | 104 +++++
docs/guide/start/toc.json | 10 -
docs/guide/start/video.md | 7 -
docs/guide/start/walkthrough/index.md | 240 -----------
.../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
docs/guide/toc-menu.json | 20 -
docs/guide/toc.json | 21 -
docs/guide/use/api/index.md | 11 -
docs/guide/use/contact.md | 7 -
docs/guide/use/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
.../use/examples/global-web-fabric/index.md | 378 -----------------
docs/guide/use/examples/index.md | 18 -
docs/guide/use/examples/messaging/index.md | 181 --------
.../nosql-cassandra/cassandra.include.md | 282 -------------
.../guide/use/examples/nosql-cassandra/index.md | 7 -
docs/guide/use/examples/simple-web-cluster.md | 9 -
docs/guide/use/examples/toc.json | 13 -
docs/guide/use/examples/webcluster.md | 9 -
docs/guide/use/examples/webcluster/index.md | 7 -
.../examples/webcluster/webcluster.include.md | 124 ------
.../use/guide/defining-applications/Chef.png | Bin 36222 -> 0 bytes
.../defining-applications/advanced-concepts.md | 137 ------
.../guide/defining-applications/archetype.md | 64 ---
.../defining-applications/basic-concepts.md | 95 -----
...ooklyn-flow-websequencediagrams.com-w400.png | Bin 58518 -> 0 bytes
.../brooklyn-flow-websequencediagrams.com.png | Bin 106928 -> 0 bytes
.../defining-applications/chef-blueprints.md | 277 ------------
.../guide/defining-applications/common-usage.md | 145 -------
.../defining-applications/creating-yaml.md | 417 -------------------
.../defining-applications/deploying-yaml.md | 37 --
.../example_files/tomcat_multi-location.java | 15 -
.../example_files/tomcat_nginx.java | 17 -
.../example_files/tomcat_simple.java | 9 -
.../appserver-clustered-w-db-concise.yaml | 15 -
.../example_yaml/appserver-clustered-w-db.yaml | 18 -
.../appserver-configured-in-config.yaml | 6 -
.../example_yaml/appserver-configured.yaml | 5 -
.../appserver-w-db-other-flavor.yaml | 17 -
.../example_yaml/appserver-w-db.yaml | 15 -
.../example_yaml/appserver-w-policy.yaml | 26 --
.../example_yaml/cluster-vm.yaml | 12 -
.../example_yaml/mysql-chef-1.yaml | 24 --
.../example_yaml/mysql-chef-2.yaml | 28 --
.../simple-appserver-with-location-byon.yaml | 12 -
.../simple-appserver-with-location.yaml | 8 -
.../example_yaml/simple-appserver.yaml | 4 -
.../example_yaml/simple-vm.yaml | 8 -
.../example_yaml/vanilla-bash-netcat-file.yaml | 6 -
.../vanilla-bash-netcat-restarter.yaml | 20 -
.../vanilla-bash-netcat-w-client.yaml | 72 ----
.../example_yaml/vanilla-bash-netcat.yaml | 18 -
.../use/guide/defining-applications/examples.md | 121 ------
.../defining-applications/service-state.md | 73 ----
.../use/guide/defining-applications/toc.json | 19 -
.../web-console-yaml-700.png | Bin 138229 -> 0 bytes
.../defining-applications/web-console-yaml.png | Bin 661136 -> 0 bytes
.../defining-applications/yaml-reference.md | 183 --------
docs/guide/use/guide/entities/index.md | 133 ------
docs/guide/use/guide/entities/toc.json | 12 -
docs/guide/use/guide/extras/index.md | 160 -------
docs/guide/use/guide/extras/toc.json | 11 -
docs/guide/use/guide/guide_toc.json | 25 --
docs/guide/use/guide/index.md | 33 --
docs/guide/use/guide/locations/index.md | 104 -----
docs/guide/use/guide/locations/toc.json | 1 -
docs/guide/use/guide/management/index.md | 383 -----------------
docs/guide/use/guide/management/toc.json | 18 -
.../management/webconsole-dashboard-w400.png | Bin 137463 -> 0 bytes
.../guide/management/webconsole-dashboard.png | Bin 214723 -> 0 bytes
.../guide/management/webconsole-detail-w400.png | Bin 111993 -> 0 bytes
.../use/guide/management/webconsole-detail.png | Bin 165359 -> 0 bytes
docs/guide/use/guide/persistence/index.md | 260 ------------
docs/guide/use/guide/persistence/toc.json | 16 -
docs/guide/use/guide/policies/index.md | 129 ------
docs/guide/use/guide/policies/toc.json | 8 -
.../use/guide/quickstart/brooklyn.properties | 324 --------------
docs/guide/use/guide/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
.../guide/quickstart/images/my-web-summary.png | Bin 80583 -> 0 bytes
.../use/guide/quickstart/images/my-web.png | Bin 83081 -> 0 bytes
docs/guide/use/guide/quickstart/index.md | 221 ----------
.../use/guide/quickstart/my-web-cluster.yaml | 19 -
.../guide/quickstart/policies-and-catalogs.md | 66 ---
docs/guide/use/guide/quickstart/toc.json | 4 -
docs/guide/use/guide/toc.json | 25 --
docs/guide/use/index.md | 9 -
docs/guide/use/toc.json | 12 -
...ooklyn-flow-websequencediagrams.com-w400.png | Bin 0 -> 58518 bytes
.../brooklyn-flow-websequencediagrams.com.png | Bin 0 -> 106928 bytes
docs/guide/yaml/catalog-maintenance.md | 115 +++++
docs/guide/yaml/chef/about-chef.md | 50 +++
.../yaml/chef/advanced-chef-integration.md | 48 +++
docs/guide/yaml/chef/chef-call-flow.png | Bin 0 -> 36222 bytes
docs/guide/yaml/chef/creating-blueprints.md | 103 +++++
.../yaml/chef/example_yaml/mysql-chef-1.yaml | 24 ++
.../yaml/chef/example_yaml/mysql-chef-2.yaml | 28 ++
docs/guide/yaml/chef/index.md | 18 +
docs/guide/yaml/chef/writing-chef.md | 79 ++++
docs/guide/yaml/clusters-and-policies.md | 42 ++
docs/guide/yaml/clusters.md | 34 ++
docs/guide/yaml/configuring-vms.md | 31 ++
docs/guide/yaml/creating-yaml.md | 75 ++++
docs/guide/yaml/custom-entities.md | 107 +++++
.../appserver-clustered-w-db-concise.yaml | 15 +
.../example_yaml/appserver-clustered-w-db.yaml | 18 +
.../appserver-configured-in-config.yaml | 6 +
.../yaml/example_yaml/appserver-configured.yaml | 5 +
.../appserver-w-db-other-flavor.yaml | 17 +
.../guide/yaml/example_yaml/appserver-w-db.yaml | 15 +
.../yaml/example_yaml/appserver-w-policy.yaml | 26 ++
docs/guide/yaml/example_yaml/cluster-vm.yaml | 12 +
.../simple-appserver-with-location-byon.yaml | 12 +
.../simple-appserver-with-location.yaml | 8 +
.../yaml/example_yaml/simple-appserver.yaml | 4 +
docs/guide/yaml/example_yaml/simple-vm.yaml | 8 +
.../example_yaml/vanilla-bash-netcat-file.yaml | 6 +
.../vanilla-bash-netcat-restarter.yaml | 20 +
.../vanilla-bash-netcat-w-client.yaml | 72 ++++
.../yaml/example_yaml/vanilla-bash-netcat.yaml | 18 +
docs/guide/yaml/index.md | 18 +
docs/guide/yaml/multiple-services.md | 64 +++
docs/guide/yaml/mutlitple-services.md | 100 +++++
docs/guide/yaml/mysql-in-catalog-w700.png | Bin 0 -> 92767 bytes
docs/guide/yaml/mysql-in-catalog.png | Bin 0 -> 168831 bytes
docs/guide/yaml/setting-locations.md | 44 ++
docs/guide/yaml/web-console-yaml-700.png | Bin 0 -> 138229 bytes
docs/guide/yaml/web-console-yaml.png | Bin 0 -> 661136 bytes
docs/guide/yaml/yaml-reference.md | 181 ++++++++
docs/style/css/base.scss | 79 +++-
.../website/community/how-to-contribute-docs.md | 4 +-
docs/website/community/how-to-contribute.md | 7 +-
docs/website/community/links.md | 22 +
docs/website/documentation.md | 19 -
docs/website/documentation/faq.md | 22 +
docs/website/documentation/glossary.md | 92 ++++
docs/website/documentation/index.md | 31 ++
docs/website/documentation/other-docs.md | 11 +
docs/website/documentation/todo.md | 7 +
docs/website/download.md | 40 --
docs/website/download/index.md | 40 ++
docs/website/glossary.md | 92 ----
docs/website/index.md | 31 +-
docs/website/learnmore/index.md | 5 +-
docs/website/learnmore/theory.md | 1 -
docs/website/meta/license.md | 205 +++++++++
docs/website/meta/sitemap.md | 19 +
docs/website/meta/versions.md | 71 ++++
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 | 217 ----------
.../website/quickstart/policies-and-catalogs.md | 67 ---
343 files changed, 8021 insertions(+), 7852 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/README.md
----------------------------------------------------------------------
diff --git a/docs/README.md b/docs/README.md
index 4fb6b5d..4d7c6d5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -160,6 +160,22 @@ but with the correct file structure, is:
_build/build.sh test-both --skip-javadoc --serve
+Preparing for a Release
+-----------------------
+
+When doing a release and changing versions:
+
+* Before branching:
+ * Change the `brooklyn-stable-version` variable in `_config.yml`
+ * Update `website/meta/versions.md` with a bit of info on this release
+* In the branch, with `change-version.sh` run (e.g. from `N.SNAPSHOT` to `N`)
+ * Ensure the `guide/start/release-notes.md` file is current
+ * Build and publish `website-root`, `guide-latest`, and `guide-version`
+* In master, with `change-version.sh` run (e.g. to `N+1-SNAPSHOT`)
+ * Clear old stuff in the `guide/start/release-notes.md` file
+ * Optionally build and public `guide-version`
+
+
Publishing the Website and Guide
--------------------------------
@@ -266,5 +282,4 @@ Archived versions are kept under `/v/` in the website. New versions should be a
the appropriate directory (`guide-version` above will do this). These versions take their
own copy of the `style` files so that changes there will not affect future versions.
-A list of available versions also needs to be updated. This is referenced from the `website`.
-<!-- TODO: where -->
+A list of available versions is in `website/meta/versions.md`.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_build/build.sh
----------------------------------------------------------------------
diff --git a/docs/_build/build.sh b/docs/_build/build.sh
index a56f4c3..69b2bfa 100755
--- a/docs/_build/build.sh
+++ b/docs/_build/build.sh
@@ -1,8 +1,11 @@
-#!/bin/bash
+#!/usr/bin/env bash
#
# this generates the site in _site
# override --url /myMountPoint (as an argument to this script) if you don't like the default set in /_config.yml
+export JAVADOC_SUBPATH=misc/javadoc
+export JAVADOC_BUILD_TARGET_SUBPATH=javadoc
+
if [ ! -x _build/build.sh ] ; then
echo ERROR: script must be run in root of docs dir
exit 1
@@ -54,7 +57,7 @@ function parse_mode() {
DIRS_TO_MOVE_TARGET[1]=v/latest/style
INSTALL_RSYNC_OPTIONS=""
INSTALL_RSYNC_SUBDIR=${DIRS_TO_MOVE_TARGET[0]}/
- JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/use/api/
+ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/
SUMMARY="user guide files in /${DIRS_TO_MOVE_TARGET[0]}"
;;
guide-version)
@@ -67,14 +70,14 @@ function parse_mode() {
DIRS_TO_MOVE_TARGET[1]=${DIRS_TO_MOVE_TARGET[0]}/style
INSTALL_RSYNC_OPTIONS=""
INSTALL_RSYNC_SUBDIR=${DIRS_TO_MOVE_TARGET[0]}/
- JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/use/api/
+ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/
SUMMARY="user guide files in /${DIRS_TO_MOVE_TARGET[0]}"
;;
test-guide-root)
JEKYLL_CONFIG=_config.yml,_build/config-production.yml,_build/config-exclude-all-but-guide.yml,_build/config-guide-root.yml
DIRS_TO_MOVE[0]=guide
DIRS_TO_MOVE_TARGET[0]=""
- JAVADOC_TARGET=use/api/
+ JAVADOC_TARGET=$JAVADOC_SUBPATH/
SUMMARY="user guide files in the root"
;;
test-both)
@@ -83,7 +86,7 @@ function parse_mode() {
DIRS_TO_MOVE_TARGET[0]=v/latest
DIRS_TO_MOVE[1]=website
DIRS_TO_MOVE_TARGET[1]=""
- JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/use/api/
+ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/
SUMMARY="all files, website in root and guide in /${DIRS_TO_MOVE_TARGET[0]}"
;;
test-both-sub)
@@ -94,7 +97,7 @@ function parse_mode() {
DIRS_TO_MOVE_TARGET[1]=brooklyn
DIRS_TO_MOVE[2]=style
DIRS_TO_MOVE_TARGET[2]=brooklyn/style
- JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/use/api/
+ JAVADOC_TARGET=${DIRS_TO_MOVE_TARGET[0]}/$JAVADOC_SUBPATH/
SUMMARY="all files in /brooklyn"
;;
original)
@@ -160,7 +163,7 @@ function make_javadoc() {
return
fi
pushd _build > /dev/null
- rm -rf target/apidocs
+ rm -rf target/$JAVADOC_BUILD_TARGET_SUBPATH
if [ "$QUICK_JAVADOC" == "true" ]; then
./quick-make-few-javadoc.sh || { echo ERROR: failed javadoc build ; exit 1 ; }
else
@@ -172,7 +175,7 @@ function make_javadoc() {
echo "ERROR: javadoc target directory _site/$JAVADOC_TARGET gone; is there a jekyll already watching?"
return 1
fi
- mv _build/target/apidocs/* _site/$JAVADOC_TARGET
+ mv _build/target/$JAVADOC_BUILD_TARGET_SUBPATH/* _site/$JAVADOC_TARGET
fi
}
@@ -199,14 +202,14 @@ function make_install() {
if [ ! -z ${JAVADOC_TARGET+SET} ]; then
if [ ! -z ${SKIP_JAVADOC+SET} ]; then
- echo 'grep "Generated by javadoc" '$SITE_DIR/$INSTALL_RSYNC_SUBDIR/use/api/index.html
- export JAVADOC_LAST_DATE=`grep "Generated by javadoc" $SITE_DIR/$INSTALL_RSYNC_SUBDIR/use/api/index.html`
+ echo 'grep "Generated by javadoc" '$SITE_DIR/$INSTALL_RSYNC_SUBDIR/$JAVADOC_SUBPATH/index.html
+ export JAVADOC_LAST_DATE=`grep "Generated by javadoc" $SITE_DIR/$INSTALL_RSYNC_SUBDIR/$JAVADOC_SUBPATH/index.html`
if [ -z "$JAVADOC_LAST_DATE" ]; then
echo "ERROR: installing with skipped javadoc, but no previous javadoc exists"
return 1
fi
echo "Installing with skipped javadoc, reusing old: $JAVADOC_LAST_DATE"
- RSYNC_COMMAND_BASE="$RSYNC_COMMAND_BASE --exclude use/api"
+ RSYNC_COMMAND_BASE="$RSYNC_COMMAND_BASE --exclude $JAVADOC_SUBPATH"
fi
fi
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_build/config-exclude-all-but-guide.yml
----------------------------------------------------------------------
diff --git a/docs/_build/config-exclude-all-but-guide.yml b/docs/_build/config-exclude-all-but-guide.yml
index 8acf536..08e4d78 100644
--- a/docs/_build/config-exclude-all-but-guide.yml
+++ b/docs/_build/config-exclude-all-but-guide.yml
@@ -1 +1 @@
-exclude: ['/Gemfile*','/README.md','/index.md','/website']
+exclude: ['/Gemfile*','/README.md','/index.md','/website/']
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_build/config-exclude-guide.yml
----------------------------------------------------------------------
diff --git a/docs/_build/config-exclude-guide.yml b/docs/_build/config-exclude-guide.yml
index 7f61a6d..984cd5d 100644
--- a/docs/_build/config-exclude-guide.yml
+++ b/docs/_build/config-exclude-guide.yml
@@ -1 +1 @@
-exclude: ['/Gemfile*','/README.md','/index.md','/guide']
+exclude: ['/Gemfile*','/README.md','/index.md','/guide/']
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_build/make-javadoc.sh
----------------------------------------------------------------------
diff --git a/docs/_build/make-javadoc.sh b/docs/_build/make-javadoc.sh
index d7f862c..ccc1772 100755
--- a/docs/_build/make-javadoc.sh
+++ b/docs/_build/make-javadoc.sh
@@ -1,4 +1,7 @@
-#!/bin/bash
+#!/usr/bin/env bash
+
+JAVADOC_TARGET1_SUBPATH=javadoc
+JAVADOC_TARGET2_SUBPATH=misc/javadoc
if [ ! -x make-javadoc.sh ]; then
echo This command must be run from the _build directory, not its parent.
@@ -13,17 +16,19 @@ else
export SOURCE_PATHS=$BROOKLYN_JAVADOC_SOURCE_PATHS
fi
-rm -rf target/apidocs/
+rm -rf target/$JAVADOC_TARGET1_SUBPATH/
export DATESTAMP=`date "+%Y-%m-%d"`
+# BROOKLYN_VERSION_BELOW
+export BROOKLYN_JAVADOC_CLASSPATH=../../usage/all/target/brooklyn-all-0.7.0-SNAPSHOT-with-dependencies.jar
echo "building javadoc at $DATESTAMP from:
$SOURCE_PATHS"
javadoc -sourcepath $SOURCE_PATHS \
-public \
- -d target/apidocs/ \
+ -d target/$JAVADOC_TARGET1_SUBPATH/ \
-subpackages "org.apache.brooklyn:io.brooklyn:brooklyn" \
- -classpath ../../usage/all/target/brooklyn-all-0.7.0-SNAPSHOT-with-dependencies.jar \
+ -classpath "$BROOKLYN_JAVADOC_CLASSPATH" \
-doctitle "Apache Brooklyn" \
-windowtitle "Apache Brooklyn" \
-header "Apache Brooklyn" \
@@ -33,12 +38,12 @@ javadoc -sourcepath $SOURCE_PATHS \
if ((${PIPESTATUS[0]})) ; then echo ; echo ; echo "ERROR: javadoc process exited non-zero" ; exit 1 ; fi
echo ; echo
-if [ ! -f target/apidocs/brooklyn/entity/Entity.html ]; then echo "ERROR: missing expected content. Are the paths right?" ; exit 1 ; fi
+if [ ! -f target/$JAVADOC_TARGET1_SUBPATH/brooklyn/entity/Entity.html ]; then echo "ERROR: missing expected content. Are the paths right?" ; exit 1 ; fi
if [ ! -z "`grep warnings target/javadoc.log`" ] ; then echo "WARNINGs occurred during javadoc build. See target/javadoc.log for more information." ; fi
-if [ -d ../_site/guide/use/api/ ] ; then
+if [ -d ../_site/guide/$$JAVADOC_TARGET2_SUBPATH/ ] ; then
echo "API directory detected in test structure _site, copying docs there so they can be served with serve-site.sh"
- cp -r target/apidocs/* ../_site/guide/use/api/
+ cp -r target/$JAVADOC_TARGET1_SUBPATH/* ../_site/guide/$JAVADOC_TARGET2_SUBPATH/
fi
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_build/quick-make-few-javadoc.sh
----------------------------------------------------------------------
diff --git a/docs/_build/quick-make-few-javadoc.sh b/docs/_build/quick-make-few-javadoc.sh
index db228df..e78d79b 100755
--- a/docs/_build/quick-make-few-javadoc.sh
+++ b/docs/_build/quick-make-few-javadoc.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
export BROOKLYN_JAVADOC_SOURCE_PATHS="../../api/src/main/java"
echo LIMITING build to $BROOKLYN_JAVADOC_SOURCE_PATHS for speed
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/docs/_config.yml
----------------------------------------------------------------------
diff --git a/docs/_config.yml b/docs/_config.yml
index ac3c342..8e36167 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -36,10 +36,14 @@ dependency_urls:
bootstrap.js: https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js
jquery.js: https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js
+root_menu_page: /website/index.md
+
# These files should not be included in the final build (in addition to _* contents)
exclude: ['/Gemfile*','/README.md']
-brooklyn-version: 0.7.0-M2-incubating # BROOKLYN_VERSION
+brooklyn-stable-version: 0.7.0-M2
+
+brooklyn-version: 0.7.0-SNAPSHOT # BROOKLYN_VERSION
brooklyn-snapshot-git-branch: master # if line above is SNAPSHOT this should point to corresponding git branch (e.g. master, 0.4)
# This is auto-detected, but you can override it if needed.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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:
+
+[](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:
+
+[](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:
+
+[](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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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/a7a317bf/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.