Mailing-List: contact commits-help@brooklyn.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: heneveld@apache.org
To: commits@brooklyn.incubator.apache.org
Date: Fri, 09 Jan 2015 15:34:55 -0000
Message-Id: <5dbbb8e52931425b8ba1a17210632194@git.apache.org>
In-Reply-To: <e629ffa16cd74b3a8260519c77e06aec@git.apache.org>
References: <e629ffa16cd74b3a8260519c77e06aec@git.apache.org>
Subject: [26/44] incubator-brooklyn git commit: docs set url_basepath,
 menu supports different href_path, pages tidied/reorged a bit more

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/creating-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/creating-yaml.md b/docs/guide/yaml/defining-applications/creating-yaml.md
deleted file mode 100644
index 3cbd532..0000000
--- a/docs/guide/yaml/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](web-console-yaml-700.png "YAML via Web Console")](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/f2494d7f/docs/guide/yaml/defining-applications/deploying-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/deploying-yaml.md b/docs/guide/yaml/defining-applications/deploying-yaml.md
deleted file mode 100644
index e4c3cf1..0000000
--- a/docs/guide/yaml/defining-applications/deploying-yaml.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Deploying YAML Blueprints
-layout: guide-normal
----
-
-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:8081/](http://127.0.0.1:8081/) 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](web-console-yaml-700.png "YAML via Web Console")](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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db-concise.yaml
deleted file mode 100644
index 518f65a..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-clustered-w-db.yaml
deleted file mode 100644
index 10592d8..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-configured-in-config.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-configured-in-config.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-configured-in-config.yaml
deleted file mode 100644
index 50c1873..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-configured.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-configured.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-configured.yaml
deleted file mode 100644
index 04ec858..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db-other-flavor.yaml
deleted file mode 100644
index 6a4a81d..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-w-db.yaml
deleted file mode 100644
index a043f1a..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/appserver-w-policy.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/appserver-w-policy.yaml b/docs/guide/yaml/defining-applications/example_yaml/appserver-w-policy.yaml
deleted file mode 100644
index cada61f..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/cluster-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/cluster-vm.yaml b/docs/guide/yaml/defining-applications/example_yaml/cluster-vm.yaml
deleted file mode 100644
index a0a50da..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-1.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-1.yaml b/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-1.yaml
deleted file mode 100644
index bdac530..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-2.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-2.yaml b/docs/guide/yaml/defining-applications/example_yaml/mysql-chef-2.yaml
deleted file mode 100644
index ced2dbe..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml b/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location-byon.yaml
deleted file mode 100644
index 7ba5b0c..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location.yaml b/docs/guide/yaml/defining-applications/example_yaml/simple-appserver-with-location.yaml
deleted file mode 100644
index c241ab2..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/simple-appserver.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/simple-appserver.yaml b/docs/guide/yaml/defining-applications/example_yaml/simple-appserver.yaml
deleted file mode 100644
index 3850b26..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/simple-vm.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/simple-vm.yaml b/docs/guide/yaml/defining-applications/example_yaml/simple-vm.yaml
deleted file mode 100644
index 149a1b9..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml b/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-file.yaml
deleted file mode 100644
index 7950b8c..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml b/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-restarter.yaml
deleted file mode 100644
index 1fd70c3..0000000
--- a/docs/guide/yaml/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

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml b/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat-w-client.yaml
deleted file mode 100644
index 50051db..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat.yaml b/docs/guide/yaml/defining-applications/example_yaml/vanilla-bash-netcat.yaml
deleted file mode 100644
index d4cb37b..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/defining-applications/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/mysql-in-catalog-w700.png b/docs/guide/yaml/defining-applications/mysql-in-catalog-w700.png
deleted file mode 100644
index f370249..0000000
Binary files a/docs/guide/yaml/defining-applications/mysql-in-catalog-w700.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/mysql-in-catalog.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/mysql-in-catalog.png b/docs/guide/yaml/defining-applications/mysql-in-catalog.png
deleted file mode 100644
index 685455d..0000000
Binary files a/docs/guide/yaml/defining-applications/mysql-in-catalog.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/web-console-yaml-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/web-console-yaml-700.png b/docs/guide/yaml/defining-applications/web-console-yaml-700.png
deleted file mode 100644
index d6a2249..0000000
Binary files a/docs/guide/yaml/defining-applications/web-console-yaml-700.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/web-console-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/web-console-yaml.png b/docs/guide/yaml/defining-applications/web-console-yaml.png
deleted file mode 100644
index 3d65a99..0000000
Binary files a/docs/guide/yaml/defining-applications/web-console-yaml.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/guide/yaml/defining-applications/yaml-reference.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/defining-applications/yaml-reference.md b/docs/guide/yaml/defining-applications/yaml-reference.md
deleted file mode 100644
index df19dd3..0000000
--- a/docs/guide/yaml/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/f2494d7f/docs/guide/yaml/deploying-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/deploying-yaml.md b/docs/guide/yaml/deploying-yaml.md
new file mode 100644
index 0000000..e4c3cf1
--- /dev/null
+++ b/docs/guide/yaml/deploying-yaml.md
@@ -0,0 +1,35 @@
+---
+title: Deploying YAML Blueprints
+layout: guide-normal
+---
+
+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:8081/](http://127.0.0.1:8081/) 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](web-console-yaml-700.png "YAML via Web Console")](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/f2494d7f/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/f2494d7f/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/f2494d7f/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

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/docs/guide/yaml/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/index.md b/docs/guide/yaml/index.md
index 8914250..d023ddb 100644
--- a/docs/guide/yaml/index.md
+++ b/docs/guide/yaml/index.md
@@ -2,10 +2,11 @@
 title: YAML
 layout: website-normal
 children:
-- defining-applications/creating-yaml.md
-- defining-applications/deploying-yaml.md
-- defining-applications/catalog-maintenance.md
-- defining-applications/chef-blueprints.md
-- defining-applications/yaml-reference.md
+- creating-yaml.md
+- deploying-yaml.md
+- catalog-maintenance.md
+- chef/
+- { path: yaml-reference.md, title: YAML Blueprint Reference }
 ---
 
+{% include list-children.html %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/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/f2494d7f/docs/website/documentation/faq.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/faq.md b/docs/website/documentation/faq.md
index 26a3fa8..25d3864 100644
--- a/docs/website/documentation/faq.md
+++ b/docs/website/documentation/faq.md
@@ -3,5 +3,20 @@ title: FAQ
 layout: website-normal
 ---
 
-TODO
+## 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/f2494d7f/docs/website/documentation/other-docs.md
----------------------------------------------------------------------
diff --git a/docs/website/documentation/other-docs.md b/docs/website/documentation/other-docs.md
index d25b6ff..a6d01df 100644
--- a/docs/website/documentation/other-docs.md
+++ b/docs/website/documentation/other-docs.md
@@ -8,5 +8,4 @@ children:
 - { path: ../meta/sitemap.md }
 ---
 
-TODO
-
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/f2494d7f/docs/website/index.md
----------------------------------------------------------------------
diff --git a/docs/website/index.md b/docs/website/index.md
index f210d6e..eb84e9f 100644
--- a/docs/website/index.md
+++ b/docs/website/index.md
@@ -10,8 +10,8 @@ children:
   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 }
-  - { path: /guide/java/index.md, title_in_menu: Java Blueprints }
+  - { 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, href_path: /guide/java/walkthrough/ }
   - { 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 }