Merge pull request #1328 from jdtoy/gs-update-squash
Updates to docs for 0.7.0. Includes YAML GS and new Location section.
diff --git a/docs/_scripts/help.txt b/docs/_scripts/help.txt
index 5fc7e75..0a41a7b 100644
--- a/docs/_scripts/help.txt
+++ b/docs/_scripts/help.txt
@@ -9,76 +9,8 @@
will build the site in _site including javadoc for offline browsing
+Release Process
+===============
-###############################################################################
-# Deprecation Warning #
-# #
-# The following content has been superseded, and will be removed shortly #
-# Please view /dev/tips/release.md or see: #
-# http://brooklyncentral.github.io/v/0.6.0-SNAPSHOT/dev/tips/release.html #
-# #
-###############################################################################
-
-
-GO LIVE (SNAPSHOT)
-------------------
-
-to make the docs live you build.sh then push _site to github brooklyncentral/brooklyncentral.github.com
-the following instructions cover this, assuming brooklyncentral.github.com is a sibling dir to the brooklyn project
-
-updating a snapshot version, in /v/VERSION/ on the server:
-
-
-export TARGET=`pwd -P`/../../brooklyncentral.github.com
-export BV=0.7.0-M1 # BROOKLYN_VERSION
-
-
-# build, copy
-if [ ! -f $TARGET/index.html ] ; then echo "could not find docs in $TARGET" ; exit 1 ; fi
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-rm -rf $TARGET/v/$BV
-mkdir $TARGET/v/$BV
-cp -r _site/* $TARGET/v/$BV/
-
-# and push
-pushd $TARGET
-git add -A .
-git commit -m "updated version docs for version $BV"
-git push
-popd
-
-
-RELEASE
--------
-
-when we do a RELEASE we must run the above for e.g. BV=0.4.0
-AND must update the files in the root dir of brooklyncentral.github.com
-
-the commands below do this (basically like the process above but
-with / in place of /v/$BV and overriding url in _config.yml
-with the --url arg below):
-
-
-# remove old root files
-pushd $TARGET
-if [ -f start/index.html ] ; then
- for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
-else
- echo IN WRONG DIRECTORY $TARGET - export TARGET to continue
- exit 1
-fi
-popd
-
-# build for hosting of / rather than /v/VERSION/
-_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
-cp -r _site/* $TARGET/
-
-# and git push
-pushd $TARGET
-git add -A .
-git commit -m "updated root docs for version $BV"
-git push
-popd
-
-
-// END
+Docs release instructions can be found at:
+http://brooklyncentral.github.io/dev/tips/release.html
diff --git a/docs/use/guide/locations/index.md b/docs/use/guide/locations/index.md
index 9570aa4..1c0668e 100644
--- a/docs/use/guide/locations/index.md
+++ b/docs/use/guide/locations/index.md
@@ -11,9 +11,11 @@
Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`.
-### Must have an SSH key
+## Setting up an SSH key
-To access any locations, Brooklyn must have access to an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`.
+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:
@@ -28,60 +30,67 @@
## Localhost
-To allow Brooklyn to access locahost the SSH key must be added to the `authorized_keys` on that machine.
+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.)
+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](http://www.jclouds.org/documentation/reference/supported-providers/).
+[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.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
+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
-# Specify image, user and minimum ram size (ie instance size)
+# (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
-# Snippet from ~/.brooklyn/brooklyn.properties.
+
{% endhighlight %}
-This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line: `AWS\ Virginia\ Large\ Centos`.
+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
-Bring-ing your own nodes (BYON) to Brooklyn is straightforward.
+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
-# Snippet from ~/.brooklyn/brooklyn.properties.
{% endhighlight %}
diff --git a/docs/use/guide/quickstart/brooklyn.properties b/docs/use/guide/quickstart/brooklyn.properties
index 8cb680c..cd2a6c2 100644
--- a/docs/use/guide/quickstart/brooklyn.properties
+++ b/docs/use/guide/quickstart/brooklyn.properties
@@ -26,16 +26,16 @@
# 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.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
+brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
## Rackspace Credentials
-brooklyn.jclouds.rackspace-cloudservers-us.identity = ACCOUNT_USERNAME
-brooklyn.jclouds.rackspace-cloudservers-us.credential = 0xApiKeyFromAccountSettingsAsHexString
+brooklyn.location.jclouds.rackspace-cloudservers-us.identity = ACCOUNT_USERNAME
+brooklyn.location.jclouds.rackspace-cloudservers-us.credential = 0xApiKeyFromAccountSettingsAsHexString
# For UK you need a *different* account, at rackspace.co.uk account (disabled by default)
-#brooklyn.jclouds.rackspace-cloudservers-uk.identity = ACCOUNT_USERNAME
-#brooklyn.jclouds.rackspace-cloudservers-uk.credential = 0xApiKeyFromAccountSettingAsHexString
+#brooklyn.location.jclouds.rackspace-cloudservers-uk.identity = ACCOUNT_USERNAME
+#brooklyn.location.jclouds.rackspace-cloudservers-uk.credential = 0xApiKeyFromAccountSettingAsHexString
## Geoscaling Service (Used for global web fabric demo) https://www.geoscaling.com/dns2/
brooklyn.geoscaling.username = USERNAME
@@ -129,20 +129,20 @@
##
## Comment out those that you don't need.
## Remember to define your identity and credential for each provider
-## e.g: brooklyn.jclouds.aws-ec2.identity = ?
-## brooklyn.jclouds.aws-ec2.credential = ?
-## brooklyn.jclouds.cloudservers-us.identity = ?
-## brooklyn.jclouds.cloudservers-us.credential = ?
+## e.g: brooklyn.location.jclouds.aws-ec2.identity = ?
+## brooklyn.location.jclouds.aws-ec2.credential = ?
+## brooklyn.location.jclouds.cloudservers-us.identity = ?
+## brooklyn.location.jclouds.cloudservers-us.credential = ?
##
# Note: For the convenience of new users, we have specified Ubuntu 12.04 LTS AMIs within
# AWS, deploying to m1.smalls, minimum. Ubuntu requires user = ubuntu.
# Please change these to better suit your requirements.
# (Note: If no parameters are set jclouds will pick AMIs at random, user=root, t1.micros.)
-#brooklyn.jclouds.aws-ec2.identity = YOURAPIKEY
-#brooklyn.jclouds.aws-ec2.credential = YOURSECRETKEY
-brooklyn.jclouds.aws-ec2.minRam = 1600
-brooklyn.jclouds.aws-ec2.user=brooklyn
+#brooklyn.location.jclouds.aws-ec2.identity = YOURAPIKEY
+#brooklyn.location.jclouds.aws-ec2.credential = YOURSECRETKEY
+brooklyn.location.jclouds.aws-ec2.minRam = 1600
+brooklyn.location.jclouds.aws-ec2.user=brooklyn
brooklyn.location.named.AWS\ Virginia\ (us-east-1) = jclouds:aws-ec2:us-east-1
brooklyn.location.named.AWS\ Virginia\ (us-east-1).imageId = us-east-1/ami-d0f89fb9
brooklyn.location.named.AWS\ Virginia\ (us-east-1).user = ubuntu
@@ -170,8 +170,8 @@
# Similarly, here are definitions for HP Cloud - also Ubuntu 12.04 LTS
# You specify your HP Credentials like this:
-# brooklyn.jclouds.hpcloud-compute.identity = projectname:username
-# brooklyn.jclouds.hpcloud-compute.credential = password
+# 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
@@ -234,12 +234,12 @@
## if you need to use Rackspace "first gen" API
## (note the "next gen" api configured above seems to be faster)
-# brooklyn.jclouds.cloudservers-us.identity = YOURAPIKEY
-# brooklyn.jclouds.cloudservers-us.credential = YOURSECRETKEY
+# 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.jclouds.cloudservers-uk.identity = YOURAPIKEY
-# brooklyn.jclouds.cloudservers-uk.credential = YOURSECRETKEY
+# 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
diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
new file mode 100644
index 0000000..b566b1a
--- /dev/null
+++ b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
new file mode 100644
index 0000000..05e9b0c
--- /dev/null
+++ b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
new file mode 100644
index 0000000..c13fdd8
--- /dev/null
+++ b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png
new file mode 100644
index 0000000..ebb6f42
--- /dev/null
+++ b/docs/use/guide/quickstart/images/add-application-catalog-web-cluster-with-db.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/add-application-modal-yaml.png b/docs/use/guide/quickstart/images/add-application-modal-yaml.png
new file mode 100644
index 0000000..c50b7ab
--- /dev/null
+++ b/docs/use/guide/quickstart/images/add-application-modal-yaml.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png b/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png
new file mode 100644
index 0000000..3d84477
--- /dev/null
+++ b/docs/use/guide/quickstart/images/jboss7-cluster-policies-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/jboss7-cluster-policies.png b/docs/use/guide/quickstart/images/jboss7-cluster-policies.png
new file mode 100644
index 0000000..2f85328
--- /dev/null
+++ b/docs/use/guide/quickstart/images/jboss7-cluster-policies.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-db-activities-large.png b/docs/use/guide/quickstart/images/my-db-activities-large.png
new file mode 100644
index 0000000..c214d9e
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-db-activities-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-db-activities.png b/docs/use/guide/quickstart/images/my-db-activities.png
new file mode 100644
index 0000000..0f2327c
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-db-activities.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web-cluster-starting.png b/docs/use/guide/quickstart/images/my-web-cluster-starting.png
new file mode 100644
index 0000000..c389b0b
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web-cluster-starting.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png
new file mode 100644
index 0000000..c9bdab6
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png
new file mode 100644
index 0000000..179b00a
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web-cluster-stop-confirm.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web-summary-large.png b/docs/use/guide/quickstart/images/my-web-summary-large.png
new file mode 100644
index 0000000..fc4bffe
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web-summary-large.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web-summary.png b/docs/use/guide/quickstart/images/my-web-summary.png
new file mode 100644
index 0000000..e85752f
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web-summary.png
Binary files differ
diff --git a/docs/use/guide/quickstart/images/my-web.png b/docs/use/guide/quickstart/images/my-web.png
new file mode 100644
index 0000000..2bd6ac3
--- /dev/null
+++ b/docs/use/guide/quickstart/images/my-web.png
Binary files differ
diff --git a/docs/use/guide/quickstart/index.md b/docs/use/guide/quickstart/index.md
index f6c81fa..289acd8 100644
--- a/docs/use/guide/quickstart/index.md
+++ b/docs/use/guide/quickstart/index.md
@@ -7,30 +7,12 @@
{% include fields.md %}
-This guide will walk you through deploying an application to a public cloud, and managing that application.
+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 %}
-name: My Web Cluster
-location: localhost
-
-services:
-
-- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
- name: My Web
- location: localhost
- brooklyn.config:
- wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0-M2/brooklyn-example-hello-world-sql-webapp-0.6.0-M2.war
- java.sysprops:
- brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
- component("db").attributeWhenReady("database.url"), "visitors", "brooklyn", "br00k11n")
-
-- serviceType: brooklyn.entity.database.mysql.MySqlNode
- id: db
- name: My DB
- brooklyn.config:
- creationScriptUrl: classpath://visitors-creation-script.sql
+{% readj my-web-cluster.yaml %}
{% endhighlight %}
(This is written in YAML, following the [camp specification](https://www.oasis-open.org/committees/camp/). )
@@ -58,12 +40,14 @@
This will create a `brooklyn-{{ site.brooklyn-version }}` folder.
-Note: you'll also need Java JRE or SDK installed (version 6 or later).
+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)"
@@ -78,7 +62,10 @@
Brooklyn will output the address of the management interface:
-`... Started Brooklyn console at http://127.0.0.1:8081/` ([link](http://127.0.0.1:8081/))
+
+`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.
@@ -86,19 +73,23 @@
## Configuring a Location
-Brooklyn deploys applications to Locations. Locations can be clouds, machines with fixed IPs or localhost (for testing).
+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:
+Create a `.brooklyn` folder in your home directory and download the template [brooklyn.properties](brooklyn.properties) to that folder.
{% highlight bash %}
$ mkdir ~/.brooklyn
+$ cd ~/.brooklyn
+$ wget {{site.url}}/use/guide/quickstart/brooklyn.properties
{% endhighlight %}
-Download the template [brooklyn.properties](brooklyn.properties) and place this in `~/.brooklyn`.
+Open brooklyn.properties in a text editor and add your cloud credentials.
-Open the file in a text editor and add your cloud credentials. If you would rather test Brooklyn on localhost, follow [these instructions]({{site.url}}/use/guide/locations/) to ensure that your Brooklyn can access your machine.
+If you would rather test Brooklyn on localhost, follow [these instructions]({{site.url}}/use/guide/locations/) to ensure that your Brooklyn can access your machine.
Restart Brooklyn:
@@ -108,66 +99,83 @@
## Launching an Application
-There are several ways to deploy a YAML 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).
-1. We can supply a blueprint file at startup: `brooklyn launch --app /path/to/myblueprint.yaml`
-1. We can deploy using the web-console.
-1. We can deploy using the brooklyn REST api.
+For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
-We will use the second option to deploy a 3-tier web-app, using the YAML file at the top of this page.
+Open the web console ([127.0.0.1:8081](http://127.0.0.1:8081)). As Brooklyn is not currently managing any applications the 'Create Application' dialog opens automatically. Select the YAML tab.
-On the home page of the Brooklyn web-console, click the "add application" button (if no applications are currently running, this will be opened automatically). Select the YAML tab and paste your YAML code.
+
-### Chose your cloud / location
-Edit the yaml to use the location you configured, e.g. replace:
+### 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 %}
-with:
+**My Web Cluster Blueprint**
+
{% highlight yaml %}
-location: google-compute-engine:europe-west1-a
+{% readj my-web-cluster.yaml %}
{% endhighlight %}
-Click "finish". You should see your application listed, with status "STARTING".
+Paste the modified YAML into the dialog and click 'Finish'.
+The dialog will close and Brooklyn will begin deploying your application.
-## Monitoring and managing applications
+Your application will be shown as 'Starting' on the web console's front page.
-In the Brooklyn web-console clicking on an application listed on the home page, or the Applications tab, will show all the applications currently running.
-
-We can explore the management hierarchy of an application, which will show us the entities it is composed of. If you have deployed the above YAML, then you'll see a standard 3-tier web-app. Clicking on the ControlledDynamicWebAppCluster will show if the cluster is ready to serve and, when ready, will provide a web address for the front of the loadbalancer.
-
-If the service.isUp, you can view the demo web application in your browser at the webapp.url.
-
-Through the Activities tab, you can drill into the activities each entity is doing or has recently done. Click on the task to see its details, and to drill into its "Children Tasks". For example, if you drill into MySqlNode's start operation, you can see the "Start (processes)", then "launch", and then the ssh command used including the stdin, stdout and stderr.
+
-## Stopping the application
+## Monitoring and Managing Applications
-To stop an application, select the application in the tree view, click on the Effectors tab, and invoke the "Stop" effector. This will cleanly shutdown all components in the application.
+Click on the application name, or open the Applications tab.
-### Testing the Policies
+We can explore the management hierarchy of the application, which will show us the entities it is composed of.
-Brooklyn at its heart is a policy driven management plane which can implement business and technical policies.
+ * My Web Cluster (A `BasicApplication`)
+ * My DB (A `MySqlNode`)
+ * My Web (A `ControlledDynamicWebAppCluster`)
+ * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`)
+ * NginxController (An `NginxController`)
-The Web Cluster with DB demo comes pre-configured with an `AutoScalerPolicy`, attached to
-the cluster of JBoss7 servers and a `targets` policy attached to the loadbalancer. You can
- observe policies this in the management console using the Policy tab of the relevant
- entity (e.g. `DynamicWebAppCluster` shows the `AutoScalerPolicy`.
-The cluster autoscaler policy will automatically scale the cluster up or down to be the
-right size for the current load. ('One server' is the minimum size allowed by the policy.)
-The loadbalancer will automatically be updated by the targets policy as the cluster size
-changes.
-Sitting idle, your cluster will only contain one server, but you can check that the policy
-works using a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint
-to create load on the cluster.
+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
-The [Elastic Web Cluster Example]({{site.url}}/use/examples/webcluster/index.html) page
-details how to build the demo application from scratch. It shows how Brooklyn can
-complement your application with policy driven management, and how an application can be
-run without using the service catalog.
+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)
diff --git a/docs/use/guide/quickstart/my-web-cluster.yaml b/docs/use/guide/quickstart/my-web-cluster.yaml
new file mode 100644
index 0000000..bbafa00
--- /dev/null
+++ b/docs/use/guide/quickstart/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.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
diff --git a/docs/use/guide/quickstart/policies-and-catalogs.md b/docs/use/guide/quickstart/policies-and-catalogs.md
new file mode 100644
index 0000000..efa06ff
--- /dev/null
+++ b/docs/use/guide/quickstart/policies-and-catalogs.md
@@ -0,0 +1,66 @@
+---
+title: Getting Started - Policies and Catalogs
+layout: page
+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}}/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-largea.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/brooklyncentral/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.url}}/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.
+
+
diff --git a/docs/use/guide/quickstart/toc.json b/docs/use/guide/quickstart/toc.json
new file mode 100644
index 0000000..d65eddb
--- /dev/null
+++ b/docs/use/guide/quickstart/toc.json
@@ -0,0 +1,4 @@
+[{ "title": "Download & Deploy",
+ "file": "{{ site.url }}/use/guide/quickstart/index.html" },
+{ "title": "Policies & Catalogs",
+ "file": "{{ site.url }}/use/guide/quickstart/policies-and-catalogs.html" }]
diff --git a/docs/use/guide/toc.json b/docs/use/guide/toc.json
index 8bdb955..7c4aa13 100644
--- a/docs/use/guide/toc.json
+++ b/docs/use/guide/toc.json
@@ -1,12 +1,15 @@
[
{ "title": "Quick Start",
- "file": "{{ site.url }}/use/guide/quickstart/index.html" },
+ "file": "{{ site.url }}/use/guide/quickstart/index.html",
+ "children": {% readj ./quickstart/toc.json %} },
{ "title": "Defining Applications",
"file": "{{ site.url }}/use/guide/defining-applications/basic-concepts.html",
"children": {% readj ./defining-applications/toc.json %} },
{ "title": "Management",
"file": "{{ site.url }}/use/guide/management/index.html" ,
"children": {% readj ./management/toc.json %} },
+{ "title": "Locations",
+ "file": "{{ site.url }}/use/guide/locations/index.html" },
{ "title": "Policies",
"file": "{{ site.url }}/use/guide/policies/index.html",
"children": {% readj ./policies/toc.json %} },
