You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2015/01/09 16:34:44 UTC
[15/44] incubator-brooklyn git commit: moving docs/guide files around
and menuing
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/download.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/download.md b/docs/guide/start/download.md
deleted file mode 100644
index 34e07ff..0000000
--- a/docs/guide/start/download.md
+++ /dev/null
@@ -1,171 +0,0 @@
----
-layout: guide-normal
-title: Downloads
-toc: ../toc.json
----
-{% include fields.md %}
-
-First time user? The [getting started]({{ site.path.guide }}/use/guide/quickstart/index.html) guide will walk you through downloading Brooklyn, setup of your `brooklyn.properties` and `catalog.xml` files, and then trying the [examples](#examples).
-
-## Download Version {{ site.brooklyn-version }}
-
-<table>
- <tr>
- <th style='text-align:left'>Download</th>
- <th style='text-align:left'>File/Format</th>
- <th>checksums <small><a href="/meta/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
- </tr>
- <tr>
- <td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
- <td style='text-align:left'><a href='{{ this_dist_url_zip }}' title='Download ZIP archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.zip</a></td>
- <td><small><a href='{{ this_dist_url_zip }}.asc'>PGP</a>, <a href='{{ this_dist_url_zip }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'><a href='{{ this_dist_url_tgz }}' title='Download TGZ archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz</a></td>
- <td ><small><a href='{{ this_dist_url_tgz }}.asc'>PGP</a>, <a href='{{ this_dist_url_tgz }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'>All Jar</td>
- <td style='text-align:left'><a href='{{ this_alljar_url_jar }}' title='Download the ALL JAR'>brooklyn-all-{{ site.brooklyn-version }}-with-dependencies.jar</a></td>
- <td><small><a href='{{ this_alljar_url_jar }}.asc'>PGP</a>, <a href='{{ this_alljar_url_jar }}.sha1'>SHA1</a></small></td>
- </tr>
- <tr>
- <td style='text-align:left'>Apache Repo</td>
- <td style='text-align:left'>
- <a href='{{ this_anything_url_search }}' title='Search'><i>GUI</i></a>
- —
- <a href='{{ this_dist_url_list }}' title='List'><i>dir</i></a>
- </td>
- <td> — </td>
- </tr>
- <tr>
- <td style='text-align:left'>Release Notes</td>
- <td style='text-align:left'><a href='{{ site.path.guide }}/start/release-notes.html'>{{ site.brooklyn-version }}</a></td>
- <td> — </td>
- </tr>
-</table>
-
-
-<a name="distro"></a>
-
-## The Distro
-
-The distribution archive contains Brooklyn as a standalone executable package.
-
-* [This version ZIP]({{ this_dist_url_zip }})
-* [This version TGZ]({{ this_dist_url_tgz }})
-* [Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-dist/)
-* [Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-dist/)
-
-Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-dist/) for stable releases
-and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-dist/) for snapshot versions.
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-**Please note**: You are reading the documentation for a snapshot version of Brooklyn.
-You should always confirm that the source and date for snapshot artifacts.
-{% endif %}
-
-
-<a name="alljar"></a>
-
-## The All Jar
-
-This is a single JAR containing all of Brooklyn and its dependencies, for developing Brooklyn into your own applications. If not using maven, just add it to your classpath.
-
-* [This version]({{ this_alljar_url_jar }})
-* [All Apache stable versions]({{ apache_releases_repo_groupid_url }}/brooklyn-all/)
-* [All Apache snapshot versions]({{ apache_snapshots_repo_groupid_url }}/brooklyn-all/)
-
-Very old versions are available at [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-all/) for stable releases
-and [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-all/) for snapshot versions.
-
-{% if site.brooklyn-version contains 'SNAPSHOT' %}
-**Again**, check the source and date for SNAPSHOT JARs.
-{% endif %}
-
-## Release Notes
-
-Release notes can be found [here]({{ site.path.guide }}/start/release-notes.html).
-
-
-<a name="examples"></a>
-
-## Examples
-
-Examples can be found in the main Brooklyn codebase, in the `/examples` directory.
-
-A good example to start with is the [Elastic Web Cluster]({{site.path.guide}}/use/examples/webcluster.html).
-
-
-<a name="maven"></a>
-
-## Maven
-
-If you use Maven, you can add Brooklyn with the following in your pom:
-
-<!-- the comment is included due to a jekyll/highlight bug which
- removes indentation on the first line in a highlight block;
- we want the actual XML indented so you can cut and paste into a pom.xml sensibly -->
-{% highlight xml %}
-<!-- include all Brooklyn items in our project -->
- <dependencies>
- <dependency>
- <groupId>org.apache.brooklyn</groupId>
- <artifactId>brooklyn-all</artifactId>
- <version>{{ site.brooklyn-version }}</version>
- </dependency>
- </dependencies>
-{% endhighlight %}
-
-`brooklyn-all` (used above) brings in all dependencies, including jclouds.
-If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``,
-and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``brooklyn-software-messaging``, or others
-(browse the full list [here]({{ this_anything_url_search }})).
-
-If you wish to use the Apache snapshot repo and/or Cloudsoft repositories,
-you can add some of the following sections:
-
-{% highlight xml %}
-<!-- include repos for snapshot items and other dependencies -->
- <repositories>
- <repository>
- <id>apache-nexus-snapshots</id>
- <name>Apache Nexus Snapshots</name>
- <url>https://repository.apache.org/content/repositories/snapshots</url>
- <releases> <enabled>false</enabled> </releases>
- <snapshots> <enabled>true</enabled> </snapshots>
- </repository>
- <repository>
- <id>cloudsoft-cloudfront-releases-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/releases/</url>
- </repository>
- <repository>
- <id>cloudsoft-cloudfront-snapshots-repo</id>
- <url>http://developers.cloudsoftcorp.com/maven/snapshots/</url>
- <snapshots>
- <enabled>true</enabled>
- <updatePolicy>never</updatePolicy>
- <checksumPolicy>fail</checksumPolicy>
- </snapshots>
- </repository>
- </repositories>
-{% endhighlight %}
-
-{% if SNAPSHOT %}
-**Please note**: to use a snapshot version of Brooklyn, you must either have Brooklyn built locally
-or one of the additional snapshot repositories above.
-{% endif %}
-
-
-<a name="source"></a>
-
-## Source Code
-
-Full source is at [github.com/apache/incubator-brooklyn](http://github.com/apache/incubator-brooklyn).
-Information on working with the source is [here]({{ site.path.guide }}/dev/code).
-
-Alternatively you can download archives of the source directly:
-
-<a href="https://github.com/apache/incubator-brooklyn/tarball/master"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
-<a href="https://github.com/apache/incubator-brooklyn/zipball/master"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.include.md b/docs/guide/start/index.include.md
deleted file mode 100644
index 3dfafb4..0000000
--- a/docs/guide/start/index.include.md
+++ /dev/null
@@ -1,50 +0,0 @@
-## What is Brooklyn?
-
-**brooklyn** is a library that simplifies application deployment and management.
-
-For **deployment**, it is designed to tie in with other tools,
-giving single-click deploy and adding the concepts of
-manageable clusters and fabrics:
-
-* many common software entities available out-of-the-box
-* integrates with [Apache Whirr](http://whirr.apache.org)
- to deploy well-known services such as Hadoop and elasticsearch
- (or use POBS, plain-old-bash-scripts)
-* use PaaS's such as OpenShift, alongside self-built clusters, for maximum flexibility
-
-Brooklyn makes roll-out an integral part of the DevOps chain,
-as code which can be version-controlled and programmatically tested,
-and portable across many clouds or fixed IP machines,
-using [jclouds](http://jclouds.org) --
-or just hitting ``localhost`` for quick dev/test.
-
-Brooklyn's main emphasis is post-deployment, **managing** an application once it is live:
-management policies are an integral part of the deployment descriptor,
-and at runtime policies have access to all aspects of the deployment.
-They are aware of the deployment topology (hierarchical) and
-locations (machines, PaaSes, and jurisdictions),
-as well as scripts, instrumentation, and operational goals and constraints.
-This means they're all set, once the application is launched,
-to keep the application running optimally,
-based on whatever *optimally* means in that context.
-
-These deployment patterns and management policies are expressed as Java (and Groovy) classes,
-open-sourced here and giving you full control over what you want to happen.
-More importantly, however, this code can be shared, improved, and extended.
-
-We're still near the beginning of figuring this out:
-[join us to make it better]({{site.path.guide}}/meta/contact.html).
-
-
-## To Get Started
-
-* See the [developer's walkthrough]({{site.path.guide}}/start/walkthrough/index.html) for a quick tour
-* Check out the [examples]({{site.path.guide}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
-* Jump in to the [user guide]({{site.path.guide}}/use/guide/) describing the
- [concepts]({{site.path.guide}}/use/guide/defining-applications/basic-concepts.html)
- and including a [tutorial]({{site.path.guide}}/use/guide/quickstart/)
-* Or dive straight in to the code, either [reading]({{site.path.guide}}/dev/code/) about it
- or [gitting](http://github.com/apache/incubator-brooklyn/) it
-
-If you like it, or if you have ideas how it could be better,
-[join the discussion]({{site.path.guide}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.md b/docs/guide/start/index.md
index eda9390..1875d53 100644
--- a/docs/guide/start/index.md
+++ b/docs/guide/start/index.md
@@ -1,8 +1,10 @@
---
layout: guide-normal
-title: Overview
-toc: /guide/toc.json
-categories: [start]
+title: Getting Started
+children:
+- quickstart/
+- walkthrough/
---
-{% readj index.include.md %}
+TODO
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/known-issues.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/known-issues.md b/docs/guide/start/known-issues.md
deleted file mode 100644
index 65c4986..0000000
--- a/docs/guide/start/known-issues.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-layout: guide-normal
-title: Known Issues
-toc: ../toc.json
----
-
-## Unable to Provision certain types of Debian VMs
-
-*Symptom*: Brooklyn fails to provision Debian VMs (e.g. in aws-ec2).
-
-*Cause*: `sudo` is not available on path, causing Brooklyn to fail to confirm that the VM is ssh'able.
-
-*Workaround*: Choose an image that does have sudo (see [wiki.debian.org/Cloud/AmazonEC2Image](http://wiki.debian.org/Cloud/AmazonEC2Image)).
-
-*Fix*: is [Pull #600](https://github.com/brooklyncentral/brooklyn/pull/600); you may also want to run with `brooklyn.location.jclouds.aws-ec2.user=root` if subsequent commands give permission errors.
-
-*Versions Affected*: 0.5.0-M2
-
-
-### Unable to Provision Ubuntu 8 VMs
-
-*Symptom: Brooklyn fails to provision Ubuntu 8 VMs (e.g. in aws-ec2) with the following error 'Cannot insert the iptables rule for port 22. Error: sudo: illegal option `-n''.
-
-*Cause: Ubuntu 8 is too old; the sudo command doesn't support the -n setting.
-
-*Workaround: Choose Ubuntu 10 or higher.
-
-*Versions Affected*: 0.5.0-M2
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/brooklyn.properties
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/brooklyn.properties b/docs/guide/start/quickstart/brooklyn.properties
new file mode 100644
index 0000000..08bb4a3
--- /dev/null
+++ b/docs/guide/start/quickstart/brooklyn.properties
@@ -0,0 +1,324 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# This is Brooklyn's dot-properties file.
+# It should be located at "~/.brooklyn/brooklyn.properties" for automatic loading,
+# or can be specified as a CLI option with --localProperties /path/to/these.properties.
+
+################################## Welcome! ############################################
+
+# It's great to have you here.
+
+# Getting Started options have been pulled to the top. There's a formatting guide at the
+# very bottom.
+
+############################ Getting Started Options ####################################
+
+## GUI Security
+
+## NOTE: in production it is highly recommended to set this, as otherwise it will not require login,
+## not will it be encrypted (though for safety if security is not set it will only bind to loopback)
+
+## Edit the name(s) and passwords as appropriate to your system:
+
+# brooklyn.webconsole.security.users=admin,bob
+# brooklyn.webconsole.security.user.admin.password=password
+# brooklyn.webconsole.security.user.bob.password=bobsword
+
+## If you prefer to run with https (on port 8443 by default), uncomment this:
+
+# brooklyn.webconsole.security.https.required=true
+
+
+# By default we have AWS set up (but with invalid credentials!). Many, many other
+# providers are supported.
+
+## Amazon EC2 Credentials
+# These should be an "Access Key ID" and "Secret Access Key" for your account.
+# This is configured at https://console.aws.amazon.com/iam/home?#security_credential .
+
+brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
+
+# Beware of trailing spaces in your cloud credentials. This will cause unexpected
+# 401: unauthorized responses.
+
+## Using Other Clouds
+# 1. Cast your eyes down this document to find your preferred cloud in the Named Locations
+# section, and the examples.
+# 2. Uncomment the relevant line(s) for your provider.
+# 3. ADD -.identity and -.credential lines for your provider, similar to the AWS ones above,
+# replacing 'aws-ec2' with jcloud's id for your cloud.
+
+
+## Deploying to Localhost
+## see: info on locations at brooklyn.io
+#
+## ~/.ssh/id_rsa is Brooklyn's default location
+# brooklyn.location.localhost.privateKeyFile = ~/.ssh/id_rsa
+## Passphrases are supported, but not required
+# brooklyn.location.localhost.privateKeyPassphrase = s3cr3tpassphrase
+
+## Geoscaling Service - used for the Global Web Fabric demo
+## see: the global web example at brooklyn.io
+## https://www.geoscaling.com/dns2/
+## other services may take similar configuration similarly; or can usually be set in YAML
+# brooklyn.geoscaling.username = USERNAME
+# brooklyn.geoscaling.password = PASSWORD
+# brooklyn.geoscaling.primaryDomain = DOMAIN
+
+
+########################## Getting Started Complete! ###################################
+
+# That's it, although you may want to read through these options...
+
+################################ Brooklyn Options ########################################
+
+## Brooklyn Management Base Directory: specify where management data should be stored on this server;
+## ~/.brooklyn/ is the default but you could use something like /opt/brooklyn/state/
+## (provided this process has write permissions)
+# brooklyn.base.dir=~/.brooklyn/
+
+## Brooklyn On-Box Directory: specify where data should be stored on managed hosts;
+## for most locations a directory off home is the default (but using /tmp/brooklyn-user/ on localhost),
+## however you could specify something like /opt/brooklyn-managed-process/ (creation and permissions are handled)
+# onbox.base.dir=~/brooklyn-managed-process/
+
+## Additional security: Allow all - if you know what you are doing!
+## (Or you can also plug in e.g. LDAP security etc here)
+# brooklyn.webconsole.security.provider = brooklyn.rest.security.provider.AnyoneSecurityProvider
+
+## Optionally disallow deployment to localhost (or any other location)
+# brooklyn.location.localhost.enabled=false
+
+## Scripting Behaviour
+
+## keep scripts around after running them (usually in /tmp)
+# brooklyn.ssh.config.noDeleteAfterExec = true
+
+## Misc Cloud Settings
+## brooklyn will fail a node if the cloud machine doesn't come up, but you can tell it to retry:
+# brooklyn.location.jclouds.machineCreateAttempts = 3
+## many cloud machines don't have sufficient entropy for lots of encrypted networking, so fake it:
+# brooklyn.location.jclouds.installDevUrandom=true
+
+## Sets a minimium ram property for all jclouds locations. Recommended to avoid getting m1.micros on AWS!
+brooklyn.location.jclouds.minRam = 2048
+
+## When setting up a new cloud machine Brooklyn creates a user with the same name as the user running
+## Brooklyn on the management server, but you can force a different user here:
+# brooklyn.location.jclouds.user=brooklyn
+## And you can force a password or key (by default it will use the keys in ~/.ssh/id_rsa{,.pub}
+# brooklyn.location.jclouds.password=s3cr3t
+
+################################ Named Locations ########################################
+
+# Named locations appear in the web console. If using the command line or YAML it may be
+# just as easy to use the jclouds:<provider> locations and specify additional properties there.
+
+## Example: AWS Virginia using Rightscale 6.3 64bit Centos AMI and Large Instances
+# brooklyn.location.named.aws-va-centos-large = jclouds:aws-ec2:us-east-1
+# brooklyn.location.named.aws-va-centos-large.imageId=us-east-1/ami-7d7bfc14
+# brooklyn.location.named.aws-va-centos-large.user=brooklyn
+# brooklyn.location.named.aws-va-centos-large.minRam=4096
+
+## You can also nest these:
+# brooklyn.location.named.aws-acct-two = jclouds:aws-ec2
+# brooklyn.location.named.aws-acct-two.identity = AKA_ACCT_TWO
+# brooklyn.location.named.aws-acct-two.credential = <access-key-hex-digits>
+# brooklyn.location.named.aws-acct-two-singapore = named:aws-acct-two
+# brooklyn.location.named.aws-acct-two-singapore.region = ap-southeast-1
+# brooklyn.location.named.aws-acct-two-singapore.displayName = AWS Singapore (Acct Two)
+
+# For convenience some common defaults:
+brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
+brooklyn.location.named.aws-oregon = jclouds:aws-ec2:us-west-2
+brooklyn.location.named.aws-ireland = jclouds:aws-ec2:eu-west-1
+brooklyn.location.named.aws-tokyo = jclouds:aws-ec2:ap-northeast-1
+
+## Google Compute
+## Note at present you have to create and download the P12 key from the Google "APIs & auth -> Registered Apps" interface,
+## then convert to PEM private key format using `openssl pkcs12 -in Certificates.p12 -out Certificates.pem -nodes`
+## then embed that on one line as the 'credential, replacing new lines with \n as below
+## (hopefully this will be improved in jclouds in the future)
+# brooklyn.location.jclouds.google-compute-engine.identity=1234567890-somet1mesArand0mU1Dhere@developer.gserviceaccount.com
+# brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN PRIVATE KEY----- \nMIIblahablahblah \nblahblahblah \n-----END PRIVATE KEY-----
+# brooklyn.location.named.Google\ US = jclouds:google-compute-engine
+# brooklyn.location.named.Google\ US.region=us-central1-a
+# brooklyn.location.named.Google\ EU = jclouds:google-compute-engine
+# brooklyn.location.named.Google\ EU.region=europe-west1-a
+## the following flags for GCE are recommended
+## specify the network to use - otherwise it creates new networks each time and you hit quotas pretty quickly
+## you may have to manually create this network AND enable a firewall rule EG tcp:1-65535;udp:1-65535;icmp
+## (fix for this is in progress)
+# brooklyn.location.jclouds.google-compute-engine.networkName=brooklyn-default-network
+## gce images have bad entropy, this ensures they have noisy /dev/random (even if the "randomness" is not quite as random)
+# brooklyn.location.jclouds.google-compute-engine.installDevUrandom=true
+## gce images often start with iptables turned on; turn it off
+# brooklyn.location.jclouds.google-compute-engine.stopIptables=true
+
+## HP Cloud - also Ubuntu 12.04 LTS
+## You specify your HP Credentials like this:
+# brooklyn.location.jclouds.hpcloud-compute.identity = projectname:username
+# brooklyn.location.jclouds.hpcloud-compute.credential = password
+## where username and password are the same as logging in to the web console, and
+## projectname can be found here: https://account.hpcloud.com/projects
+#�brooklyn.location.named.HP\ Cloud\ Arizona-1 = jclouds:hpcloud-compute:az-1.region-a.geo-1
+# brooklyn.location.named.HP\ Cloud\ Arizona-1.imageId = az-1.region-a.geo-1/75845
+# brooklyn.location.named.HP\ Cloud\ Arizona-1.user = ubuntu
+
+## Softlayer - need a key from the gui, under "administrative -> user administration -> api-access
+# brooklyn.location.jclouds.softlayer.identity=username
+# brooklyn.location.jclouds.softlayer.credential=<private-key-hex-digits>
+## locations
+# brooklyn.location.named.Softlayer\ Dallas=jclouds:softlayer:dal05
+# brooklyn.location.named.Softlayer\ Seattle=jclouds:softlayer:sea01
+# brooklyn.location.named.Softlayer\ Washington\ DC=jclouds:softlayer:wdc01
+# brooklyn.location.named.Softlayer\ Singapore\ 1=jclouds:softlayer:sng01
+# brooklyn.location.named.Softlayer\ Amsterdam\ 1=jclouds:softlayer:ams01
+
+
+## Brooklyn uses the jclouds multi-cloud library to access many clouds.
+## http://www.jclouds.org/documentation/reference/supported-providers/
+
+## Templates for many other clouds, but remember to add identity and credentials:
+
+# brooklyn.location.named.Bluelock = jclouds:bluelock-vcloud-zone01
+
+# brooklyn.location.named.CloudSigma\ Nevada = jclouds:cloudsigma-lvs
+# brooklyn.location.named.CloudSigma\ Zurich = jclouds:cloudsigma-zrh
+
+# brooklyn.location.named.ElasticHosts\ London = jclouds:elastichosts-lon-p
+# brooklyn.location.named.ElasticHosts\ Texas = jclouds:elastichosts-sat-p
+
+# brooklyn.location.named.GleSYS = jclouds:glesys
+
+# brooklyn.location.named.Go2Cloud = jclouds:go2cloud-jhb1
+
+# brooklyn.location.named.GoGrid = jclouds:gogrid
+
+# brooklyn.location.named.Green\ House\ Data = jclouds:greenhousedata-element-vcloud
+
+# brooklyn.location.named.Ninefold = jclouds:ninefold-compute
+
+# brooklyn.location.named.OpenHosting = jclouds:openhosting-east1
+
+# brooklyn.location.named.Rackspace\ Chicago\ (ord) = jclouds:rackspace-cloudservers-us:ORD
+# brooklyn.location.named.Rackspace\ Dallas\ (dfw) = jclouds:rackspace-cloudservers-us:DFW
+# brooklyn.location.named.Rackspace\ Hong\ Kong\ (hkg) = jclouds:rackspace-cloudservers-us:HKG
+# brooklyn.location.named.Rackspace\ Northern\ Virginia\ (iad) = jclouds:rackspace-cloudservers-us:IAD
+# brooklyn.location.named.Rackspace\ Sydney\ (syd) = jclouds:rackspace-cloudservers-us:SYD
+## for UK you will need a separate account with rackspace.co.uk
+# brooklyn.location.named.Rackspace\ London\ (lon) = jclouds:rackspace-cloudservers-uk
+
+## if you need to use Rackspace "first gen" API
+## (note the "next gen" api configured above seems to be faster)
+# brooklyn.location.jclouds.cloudservers-us.identity = YOURAPIKEY
+# brooklyn.location.jclouds.cloudservers-us.credential = YOURSECRETKEY
+# brooklyn.location.named.Rackspace\ US\ (First Gen) = jclouds:cloudservers-us
+## and as with next gen, first gen requires a separate acct for the UK:
+# brooklyn.location.jclouds.cloudservers-uk.identity = YOURAPIKEY
+# brooklyn.location.jclouds.cloudservers-uk.credential = YOURSECRETKEY
+# brooklyn.location.named.Rackspace\ UK\ (First Gen) = jclouds:cloudservers-uk
+
+# brooklyn.location.named.SeverLove = jclouds:serverlove-z1-man
+
+# brooklyn.location.named.SkaliCloud = jclouds:skalicloud-sdg-my
+
+# brooklyn.location.named.Stratogen = jclouds:stratogen-vcloud-mycloud
+
+# brooklyn.location.named.TryStack\ (Openstack) = jclouds:trystack-nova
+
+
+## Production pool of machines for my application (deploy to named:On-Prem\ Iron\ Example)
+# brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+# brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+# brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+
+## Various Private Clouds
+
+## Example: OpenStack Nova
+
+## openstack identity and credential are random strings of letters and numbers (TBC - still the case?)
+# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:https://9.9.9.9:9999/v2.0/
+
+## OpenStack Nova access information can be downloaded from the openstack web interface; for example, as openrc.sh file
+# brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:keystone-url
+# brooklyn.location.named.My\ OpenStack.identity=your-tenant-name:your-user-name
+# brooklyn.location.named.My\ OpenStack.credential=your-password
+# brooklyn.location.named.My\ OpenStack.endpoint=your-keystone-url
+
+## The ID of the image must be configured according to the local OpenStack settings
+## Use the command nova image-list to list all the available images
+## Use the command nova show <image-name> to get more details
+# brooklyn.location.named.My\ OpenStack.imageId=the-region-name/the-image-id
+
+## Virtual Machine flavors must match the ones created upfront according to the local OpenStack settings
+## Use the command nova flavor-list to list all the available options
+## Use the command nova flavor-show <flavor-name> to get more details
+# brooklyn.location.named.My\ OpenStack.hardwareId=the-region-name/the-flavor-id
+
+## (Optional) Configurations
+
+# brooklyn.location.named.My\ OpenStack.user=user-name-inside-the-instance
+
+## The keyPair must by created upfront. Both the following two options are required at the same time.
+# brooklyn.location.named.My\ OpenStack.keyPair=the-key-pair-name
+# brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/keypair.pem
+
+## Security groups must be created upfront (TBC - How to specify many security groups at one ?)
+# brooklyn.location.named.My\ OpenStack.securityGroups=universal
+
+# brooklyn.location.named.My\ OpenStack.openIptables=true
+# brooklyn.location.named.My\ OpenStack.selinux.disabled=true
+# brooklyn.location.named.My\ OpenStack.auto-create-floating-ips=true
+# brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false
+
+## cloudstack identity and credential are rather long random strings of letters and numbers
+## you generate this in the cloudstack gui, under accounts, then "view users", then "generate key"
+## use the "api key" as the identity and "secret key" as the credential
+# brooklyn.location.named.My\ Cloudstack=jclouds:cloudstack:http://9.9.9.9:9999/client/api/
+
+## abiquo identity and credential are your login username/passed
+# brooklyn.location.named.My\ Abiquo=jclouds:abiquo:http://demonstration.abiquo.com/api/
+
+############################### Formatting Guide #######################################
+
+! Both # and ! mark lines as comments
+# The follow syntax are ALL valid.
+# example_key example_value
+# example_key : example_value
+# example_key = example_value
+# example_key=example_value
+
+# The backslash below tells Brooklyn to continue reading the value onto the next line.
+# example_key = A very \
+# long string!
+# Note all white space before 'long...' is ignored. Also '!' is kept as part of the string
+
+
+# Keys with spaces should be escaped with backslashes.
+# This is useful for named locations, as the name displayed in Brooklyn's web
+# interface is derived from the key name.
+# key\ with\ spaces = some\ value
+
+# Encoding for .properties must be ISO-8859-1, aka Latin-1.
+# All non-latin1 characters must be entered using unicode escape characters
+# polish_pangram = P\u00F3jd\u017A\u017Ce, ki\u0144 \
+# t\u0119 chmurno\u015B\u0107 w g\u0142\u0105b flaszy!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/catalog.xml b/docs/guide/start/quickstart/catalog.xml
new file mode 100644
index 0000000..cbb5584
--- /dev/null
+++ b/docs/guide/start/quickstart/catalog.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<catalog>
+ <name>Brooklyn Demos</name>
+
+
+ <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB">
+ <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB">
+ <description>Deploys a demonstration web application to JBoss clusters around the world</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl>
+ </template>
+
+ <classpath>
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION -->
+ </classpath>
+
+
+</catalog>
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-large.png b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-large.png
new file mode 100644
index 0000000..b566b1a
Binary files /dev/null and b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png
new file mode 100644
index 0000000..05e9b0c
Binary files /dev/null and b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location.png b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location.png
new file mode 100644
index 0000000..c13fdd8
Binary files /dev/null and b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db-location.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db.png b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db.png
new file mode 100644
index 0000000..ebb6f42
Binary files /dev/null and b/docs/guide/start/quickstart/images/add-application-catalog-web-cluster-with-db.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/add-application-modal-yaml.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/add-application-modal-yaml.png b/docs/guide/start/quickstart/images/add-application-modal-yaml.png
new file mode 100644
index 0000000..c50b7ab
Binary files /dev/null and b/docs/guide/start/quickstart/images/add-application-modal-yaml.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/jboss7-cluster-policies-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/jboss7-cluster-policies-large.png b/docs/guide/start/quickstart/images/jboss7-cluster-policies-large.png
new file mode 100644
index 0000000..3d84477
Binary files /dev/null and b/docs/guide/start/quickstart/images/jboss7-cluster-policies-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/jboss7-cluster-policies.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/jboss7-cluster-policies.png b/docs/guide/start/quickstart/images/jboss7-cluster-policies.png
new file mode 100644
index 0000000..2f85328
Binary files /dev/null and b/docs/guide/start/quickstart/images/jboss7-cluster-policies.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-db-activities-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-db-activities-large.png b/docs/guide/start/quickstart/images/my-db-activities-large.png
new file mode 100644
index 0000000..c214d9e
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-db-activities-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-db-activities.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-db-activities.png b/docs/guide/start/quickstart/images/my-db-activities.png
new file mode 100644
index 0000000..0f2327c
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-db-activities.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web-cluster-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web-cluster-starting.png b/docs/guide/start/quickstart/images/my-web-cluster-starting.png
new file mode 100644
index 0000000..c389b0b
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web-cluster-starting.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm-large.png b/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm-large.png
new file mode 100644
index 0000000..c9bdab6
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm.png b/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm.png
new file mode 100644
index 0000000..179b00a
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web-cluster-stop-confirm.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web-summary-large.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web-summary-large.png b/docs/guide/start/quickstart/images/my-web-summary-large.png
new file mode 100644
index 0000000..fc4bffe
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web-summary-large.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web-summary.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web-summary.png b/docs/guide/start/quickstart/images/my-web-summary.png
new file mode 100644
index 0000000..e85752f
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web-summary.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/images/my-web.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/images/my-web.png b/docs/guide/start/quickstart/images/my-web.png
new file mode 100644
index 0000000..2bd6ac3
Binary files /dev/null and b/docs/guide/start/quickstart/images/my-web.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/index.md b/docs/guide/start/quickstart/index.md
new file mode 100644
index 0000000..181779f
--- /dev/null
+++ b/docs/guide/start/quickstart/index.md
@@ -0,0 +1,221 @@
+---
+title: Getting Started
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide]
+---
+
+{% include fields.md %}
+
+This guide will walk you through deploying an application to a public cloud.
+
+We will be deploying an example 3-tier web application, described using this blueprint:
+
+{% highlight yaml %}
+{% readj my-web-cluster.yaml %}
+{% endhighlight %}
+
+(This is written in YAML, following the [camp specification](https://www.oasis-open.org/committees/camp/). )
+
+
+## Install Brooklyn
+
+Download the [Brooklyn distribution]({{ this_dist_url_tgz }}) and expand it to your home directory ( `~/` ), or in a location of your choice. (Other [download options]({{site.path.guide}}/start/download.html) are available.)
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
+{% else %}
+Expand the `tar.gz` archive:
+{% endif %}
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+{% highlight bash %}
+$ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-timestamp-dist.tar.gz
+{% endhighlight %}
+{% else %}
+{% highlight bash %}
+$ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
+{% endhighlight %}
+{% endif %}
+
+This will create a `brooklyn-{{ site.brooklyn-version }}` folder.
+
+Note: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers.
+
+## Launch Brooklyn
+
+Let's setup some paths for easy commands.
+
+(Click the clipboard on these code snippets for easier c&p.)
+
+{% highlight bash %}
+$ cd brooklyn-{{ site.brooklyn-version }}
+$ BROOKLYN_DIR="$(pwd)"
+$ export PATH=$PATH:$BROOKLYN_DIR/bin/
+{% endhighlight %}
+
+We can do a quick test drive by launching Brooklyn:
+
+{% highlight bash %}
+$ brooklyn launch
+{% endhighlight %}
+
+Brooklyn will output the address of the management interface:
+
+ INFO Starting brooklyn web-console on loopback interface because no security config is set
+ INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []
+
+But before we really use Brooklyn, we need to configure security and locations.
+In particular, if you are running on a remote server, you'll notice that Brooklyn has
+bound only to the loopback device, not a public network interface, and you won't be able
+to access the server. This is for security reasons; you can override by passing `-b 0.0.0.0`,
+or once you have configured security it will automatically bind to all interfaces by default.
+
+Stop Brooklyn with ctrl-c, or in the web-browser (under "Help"), or with `kill`.
+(The PID is written to a file in the directory where you launch.)
+
+
+<a name="properties"></a>
+## Configuring Brooklyn with brooklyn.properties
+
+Brooklyn reads startup configuration from a file `~/.brooklyn/brooklyn.properties`, by default.
+You can create this from a template [brooklyn.properties]({{brooklyn_properties_url_path}}) file which you edit;
+this file can be installed with:
+
+{% highlight bash %}
+$ mkdir ~/.brooklyn
+$ cd ~/.brooklyn
+$ wget {{brooklyn_properties_url_live}}
+{% endhighlight %}
+
+Open this file in a text editor and follow the instructions there. The main settings are summarized below:
+
+<a name="security"></a>
+## Configuring Security
+
+To configure Brooklyn to run on a public IP address, security should be enabled.
+The simplest way is to define a user and password in `~/.brooklyn/brooklyn.properties`
+(described above):
+
+ brooklyn.webconsole.security.users=admin
+ brooklyn.webconsole.security.user.admin.password=s3cr3t
+
+Other modes, including LDAP, are described in this file.
+
+The other common setting is to run under https (on port 8443 by default):
+
+ brooklyn.webconsole.security.https.required=true
+
+These settings require a restart to Brooklyn.
+
+
+<a name="location"></a>
+## Configuring a Location
+
+Brooklyn deploys applications to ``locations''. These locations
+can be clouds, machines with fixed IPs or localhost (for testing).
+Their configuration can be specified in `~/.brooklyn/brooklyn.properties` (described above),
+and then these locations can be easily selected within Brooklyn.
+Alternatively this information can be specified in the YAML when applications are deployed,
+without needing to set it in `brooklyn.properties`.
+
+Some sample settings for this are:
+
+ brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+ brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
+ brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
+ brooklyn.location.named.aws-california.displayName = AWS US West 1 (CA)
+
+ brooklyn.location.jclouds.softlayer.identity = username
+ brooklyn.location.jclouds.softlayer.credential = <private-key-hex-digits>
+ brooklyn.location.named.softlayer-dal05 = jclouds:softlayer:dal05
+ brooklyn.location.named.softlayer-dal05.displayName = Softlayer Dallas
+
+If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/use/guide/locations/)
+to ensure that your Brooklyn can access your machine.
+
+Once updated, restart Brooklyn (or reload the properties within the web GUI).
+
+
+## Launching an Application in Brooklyn
+
+There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
+
+For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
+
+Open the web console ([127.0.0.1:8081](http://127.0.0.1:8081)). As Brooklyn is not currently managing any applications the 'Create Application' dialog opens automatically. Select the YAML tab.
+
+
+
+
+### Chose your Cloud / Location
+
+Edit the 'location' parameter in the YAML template (repeated below) to use the location you configured.
+
+For example, replace:
+{% highlight yaml %}
+location: location
+{% endhighlight %}
+
+with (one of):
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+location: rackspace-cloudservers-us:ORD
+location: google-compute-engine:europe-west1-a
+location: localhost
+{% endhighlight %}
+
+**My Web Cluster Blueprint**
+
+{% highlight yaml %}
+{% readj my-web-cluster.yaml %}
+{% endhighlight %}
+
+Paste the modified YAML into the dialog and click 'Finish'.
+The dialog will close and Brooklyn will begin deploying your application.
+
+Your application will be shown as 'Starting' on the web console's front page.
+
+
+
+
+## Monitoring and Managing Applications
+
+Click on the application name, or open the Applications tab.
+
+We can explore the management hierarchy of the application, which will show us the entities it is composed of.
+
+ * My Web Cluster (A `BasicApplication`)
+ * My DB (A `MySqlNode`)
+ * My Web (A `ControlledDynamicWebAppCluster`)
+ * Cluster of JBoss7 Servers (A `DynamicWebAppCluster`)
+ * NginxController (An `NginxController`)
+
+
+
+Clicking on the 'My Web' entity will show the Summary tab. Here we can see if the cluster is ready to serve and, when ready, grab the web address for the front of the loadbalancer.
+
+
+
+
+The Activity tab allows us to drill down into what activities each entity is currently doing or has recently done. It is possible to drill down to all child tasks, and view the commands issued, and any errors or warnings that occured.
+
+Drill into the 'My DB' start operation. Working down through 'Start (processes)', then 'launch', we can discover the ssh command used including the stdin, stdout and stderr.
+
+[](images/my-db-activities-large.png)
+
+
+## Stopping the Application
+
+To stop an application, select the application in the tree view (the top/root entity), click on the Effectors tab, and invoke the 'Stop' effector. This will cleanly shutdown all components in the application and return any cloud machines that were being used.
+
+[](images/my-web-cluster-stop-confirm-large.png)
+
+
+### Next
+
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, but this a very small part of Brooklyn's capabilities!
+
+Brooklyn's real power is in using Policies to automatically *manage* applications. There is also the (very useful) ability to store a catalog of application blueprints, ready to go.
+
+[Getting Started - Policies and Catalogs](policies-and-catalogs.html)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/my-web-cluster.yaml b/docs/guide/start/quickstart/my-web-cluster.yaml
new file mode 100644
index 0000000..bbafa00
--- /dev/null
+++ b/docs/guide/start/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
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/policies-and-catalogs.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/policies-and-catalogs.md b/docs/guide/start/quickstart/policies-and-catalogs.md
new file mode 100644
index 0000000..3412333
--- /dev/null
+++ b/docs/guide/start/quickstart/policies-and-catalogs.md
@@ -0,0 +1,66 @@
+---
+title: Getting Started - Policies and Catalogs
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide]
+---
+
+{% include fields.md %}
+
+In the [previous step](index.html) we downloaded Brooklyn and used it to deploy an application to a cloud, but at its heart Brooklyn is a policy driven *management* plane.
+
+Here we will introduce Polices using a simple demo app, which we will load from a Service Catalog.
+
+## Service Catalogs
+
+Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
+
+{% highlight bash %}
+$ cd ~/.brooklyn
+$ wget {{site.url_root}}{{site.path.guide}}/use/guide/quickstart/catalog.xml
+
+$ brooklyn launch
+{% endhighlight %}
+
+Now when we open the web console, two applications are displayed from the catalog.
+
+Select the 'Demo Web Cluster with DB' and click 'Next'.
+
+[](add-application-catalog-web-cluster-with-db-large.png)
+
+Select the Location that Brooklyn should deploy to, and name your application:
+
+[](images/add-application-catalog-web-cluster-with-db-location-large.png)
+
+Click 'Finish' to launch the application as before.
+
+
+### Exploring and Testing Policies
+
+The Demo Web Cluster with DB application is pre-configured with two polices.
+
+The app server cluster has an `AutoScalerPolicy`, and the loadbalancer has a `targets` policy.
+
+Use the Applications tab in the web console to drill down into the Policies section of the ControlledDynamicWebAppCluster's Cluster of JBoss7Servers.
+
+You will see that the `AutoScalerPolicy` is running.
+
+[](images/jboss7-cluster-policies-large.png)
+
+
+This policy automatically scales the cluster up or down to be the right size for the cluster's current load. (One server is the minimum size allowed by the policy.)
+
+The loadbalancer's `targets` policy ensures that the loadbalancer is updated as the cluster size changes.
+
+Sitting idle, this cluster will only contain one server, but you can use a tool like [jmeter](http://jmeter.apache.org/) pointed at the nginx endpoint to create load on the cluster. (Download a [jmeter test plan](https://github.com/apache/incubator-brooklyn/blob/master/examples/simple-web-cluster/resources/jmeter-test-plan.jmx).)
+
+As load is added, Brooklyn requests a new cloud machine, creates a new app server, and adds it to the cluster. As load is removed, servers are removed from the cluster, and the infrastructure is handed back to the cloud.
+
+### Next
+
+The [Elastic Web Cluster Example]({{site.path.guide}}use/examples/webcluster/index.html) page
+details how to build this demo application from scratch in Java. It shows in more detail how Brooklyn can
+complement your application with policy driven management, and how applications can be
+run from the command line.
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/quickstart/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/start/quickstart/toc.json b/docs/guide/start/quickstart/toc.json
new file mode 100644
index 0000000..eee07d6
--- /dev/null
+++ b/docs/guide/start/quickstart/toc.json
@@ -0,0 +1,4 @@
+[{ "title": "Download & Deploy",
+ "file": "{{ site.path.guide }}/use/guide/quickstart/index.html" },
+{ "title": "Policies & Catalogs",
+ "file": "{{ site.path.guide }}/use/guide/quickstart/policies-and-catalogs.html" }]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/release-notes.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/release-notes.md b/docs/guide/start/release-notes.md
deleted file mode 100644
index 44f5bb7..0000000
--- a/docs/guide/start/release-notes.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-layout: guide-normal
-title: Release Notes
-toc: ../toc.json
----
-
-## Brooklyn Version ({{ site.brooklyn-version }})
-
-{% if SNAPSHOT %}
-**You are viewing a SNAPSHOT release (master branch), so this list is incomplete.**
-{% endif %}
-
-* Introduction
-* New Features
-* Backwards Compatibility
-* Community Activity
-
-### Introduction
-
-This version includes many big features,
-incorporating a lot of improvements and feedback from our community. Thank you!
-
-Thanks also go to Brooklyn's commercial users who have funded this development and
-made some major contributions.
-
-For more information, please visit [brooklyn.io](http://brooklyn.io).
-
-
-### New Features
-
-* A huge expansion of what can be done in YAML.
-
-* First-class Chef integration
-
-* New clouds: GCE, Softlayer
-
-* Networking
-
-* Docker support: see [clocker.io](clocker.io)
-
-
-### Backwards Compatibility
-
-* Persistence has been radically overhauled. In most cases the state files from previous versions are compatible,
- but some items have had to change. For most users this should not be an issue as persistence in the previous version
- was not working well in any case.
-
-
-### Community Activity
-
-Brooklyn has moved into the Apache Software Foundation.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/start/toc.json b/docs/guide/start/toc.json
deleted file mode 100644
index 532ce68..0000000
--- a/docs/guide/start/toc.json
+++ /dev/null
@@ -1,10 +0,0 @@
-[
-{ "title": "Overview",
- "file": "{{ site.path.guide }}/index.html" },
-{ "title": "Walkthrough",
- "file": "{{ site.path.guide }}/start/walkthrough/index.html" },
-{ "title": "Download",
- "file": "{{ site.path.guide }}/start/download.html" },
-{ "title": "Documentation",
- "file": "{{ site.path.guide }}/start/docs-summary.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/video.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/video.md b/docs/guide/start/video.md
deleted file mode 100644
index c45dd4c..0000000
--- a/docs/guide/start/video.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: guide-normal
-title: Video
-toc: ../toc.json
----
-
-TODO
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/start/walkthrough/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/index.md b/docs/guide/start/walkthrough/index.md
index eaabd14..3c29484 100644
--- a/docs/guide/start/walkthrough/index.md
+++ b/docs/guide/start/walkthrough/index.md
@@ -1,7 +1,6 @@
---
layout: guide-normal
title: Walkthrough
-toc: /guide/toc.json
---
{% include fields.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/toc-menu.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc-menu.json b/docs/guide/toc-menu.json
deleted file mode 100644
index 6c1e3c3..0000000
--- a/docs/guide/toc-menu.json
+++ /dev/null
@@ -1,20 +0,0 @@
-[
-{ "title": "Overview",
- "file": "{{ site.path.guide }}/index.html" },
-{ "title": "Download",
- "file": "{{ site.path.guide }}/start/download.html" },
-{ "title": "Getting Started",
- "file": "{{ site.path.guide }}/use/guide/quickstart/index.html" },
-{ "title": "Walkthrough",
- "file": "{{ site.path.guide }}/start/walkthrough/index.html" },
-{ "title": "User Guide",
- "file": "{{ site.path.guide }}/use/guide/index.html",
- "children": {% readj use/guide/toc.json %} },
-{ "title": "Examples",
- "file": "{{ site.path.guide }}/use/examples/index.html",
- "children": {% readj use/examples/toc.json %} },
-{ "title": "Contributing",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "exclude": true,
- "children": {% readj dev/toc.json %} }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc.json b/docs/guide/toc.json
deleted file mode 100644
index 07d4c5c..0000000
--- a/docs/guide/toc.json
+++ /dev/null
@@ -1,21 +0,0 @@
-[
-{ "title": "Start",
- "file": "{{ site.path.guide }}/start/index.html",
- "exclude": true,
- "children": {% readj start/toc.json %} },
-{ "title": "Using brooklyn",
- "file": "{{ site.path.guide }}/use/index.html",
- "children": {% readj use/toc.json %} },
-{ "title": "Contributing",
- "file": "{{ site.path.guide }}/dev/code/index.html",
- "exclude": true,
- "children": {% readj dev/toc.json %} },
-{ "title": "License",
- "file": "{{ site.path.guide }}/license/index.html",
- "exclude": true,
- "children": {% readj license/toc.json %} },
-{ "title": "Meta",
- "file": "{{ site.path.guide }}/meta/versions.html",
- "exclude": true,
- "children": {% readj meta/toc.json %} }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/api/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/api/index.md b/docs/guide/use/api/index.md
deleted file mode 100644
index c44b6e3..0000000
--- a/docs/guide/use/api/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-layout: guide-normal
-title: API Reference
-toc: ../../toc.json
----
-
-*Javadoc is not available as part of this build.*
-
-Please see the [source code]({{site.path.guide}}/dev/code) to view javadoc.
-
-<!-- This page is normally overwritten by generated javadoc. -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/contact.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/contact.md b/docs/guide/use/contact.md
deleted file mode 100644
index 622cf0a..0000000
--- a/docs/guide/use/contact.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: guide-normal
-title: Contact
-toc: ../toc.json
----
-
-{% readj ../meta/contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/before-begin.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/before-begin.include.md b/docs/guide/use/examples/before-begin.include.md
deleted file mode 100644
index e05f9f1..0000000
--- a/docs/guide/use/examples/before-begin.include.md
+++ /dev/null
@@ -1,56 +0,0 @@
-{% include fields.md %}
-
-## Before You Begin
-
-To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven`` (v3) installed.
-
-### Installing Brooklyn
-
-(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.)
-
-{% if SNAPSHOT %}
-
-First, grab a copy of the Brooklyn snapshot distribution you wish to use from
-[the Sonatype snapshot repo]({{ sonatype_repo_groupid_url }}brooklyn-dist/)
-(or build it yourself following instructions [here]({{ site.path.guide }}/dev/build/)),
-unpack it to your favourite location (e.g. `$(pwd)`),
-and export `BROOKLYN_HOME`:
-
-{% highlight bash %}
-% curl -L -o brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz "{{ this_dist_url_tgz }}"
-% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
-% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
-{% endhighlight %}
-
-{% else %}
-
-Grab a copy of the Brooklyn distribution and set up `BROOKLYN_HOME`:
-
-{% highlight bash %}
-% curl -LO "{{ this_dist_url_tgz }}"
-% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
-% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
-{% endhighlight %}
-
-{% endif %}
-
-### Installing the Examples
-
-Grab a copy of the brooklyn-examples source code and build it with Maven:
-
-{% highlight bash %}
-% git clone https://github.com/apache/incubator-brooklyn.git
-% cd incubator-brooklyn/examples
-% mvn clean install
-{% endhighlight %}
-
-{% if SNAPSHOT %}
-Please note, these instructions are for a SNAPSHOT release of Brooklyn,
-so proceed with caution.
-For the latest stable version, go [here](/meta/versions.html).
-{% endif %}
-
-For more information on ways to download Brooklyn please
-see the [download page]({{site.path.guide}}/start/download.html).
-For more information on the Brooklyn CLI and launching apps,
-please visit [this section of the user guide]({{site.path.guide}}/use/guide/management/index.html#cli).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
deleted file mode 100644
index c34217f..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
deleted file mode 100644
index f47226a..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/console-map-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map-w700.png b/docs/guide/use/examples/global-web-fabric/console-map-w700.png
deleted file mode 100644
index af353a9..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-map-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/console-map.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map.png b/docs/guide/use/examples/global-web-fabric/console-map.png
deleted file mode 100644
index cd0f811..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/console-map.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
deleted file mode 100644
index 33c811d..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
deleted file mode 100644
index 4e743e3..0000000
Binary files a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/global-web-fabric/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/index.md b/docs/guide/use/examples/global-web-fabric/index.md
deleted file mode 100644
index b59eae0..0000000
--- a/docs/guide/use/examples/global-web-fabric/index.md
+++ /dev/null
@@ -1,378 +0,0 @@
----
-layout: guide-normal
-title: Global Web Fabric
-toc: /guide/toc.json
----
-
-This example shows how to build a multi-site web application *fabric*
-with DNS configured on the front-end to combine the sites,
-routing users to the location closest to them.
-
-It can combine with the [Simple Web Cluster](../webcluster) example
-or the [Portable Cloud Foundry](https://github.com/cloudsoft/brooklyn-cloudfoundry) example,
-but does not assume knowledge of either of these.
-
-{% readj ../before-begin.include.md %}
-
-Now, go to this particular example's directory:
-
-{% highlight bash %}
-% cd global-web-fabric
-{% endhighlight %}
-
-The CLI needs to know where to find your compiled examples. You can set this up by exporting
-the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
-
-{% highlight bash %}
-% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
-{% endhighlight %}
-
-The project ``global-web-fabric`` contains the code used
-in this example under ``src/main/java``.
-
-
-### Setting Up Geographic DNS
-
-This example uses [geoscaling.com](http://www.geoscaling.com) to provide **free** geographic-dependent DNS services.
-This will forward a domain name of your choice to various IPs depending on a script,
-e.g. computing the nearest IP based on latitude and longitude of the requester and the targets.
-Brooklyn will automatically generate and update this script, but you do need to
-create and configure a Geoscaling account:
-
- 1. Create the free account [here](https://www.geoscaling.com/dns2/?module=register).
- 1. Click the link in the email you receive.
- 1. Enter the domain name you wish to use into geoscaling (see below).
-
-The simplest domain name to choose is something unique under `geopaas.org`, e.g. `yourname.geopaas.org`,
-which we have already configured for Geoscaling to manage.
-If you are using your own domain name,
-set its nameservers as advised by geoscaling (e.g. `ns{1,2,3,4}.geoscaling.com`).
-
-Next we need to supply this information to Brooklyn at runtime.
-The simplest way is to create or add the following fields to `~/.brooklyn/brooklyn.properties`:
-
-{% highlight bash %}
-brooklyn.geoscaling.username=yourname
-brooklyn.geoscaling.password=s3cr3t
-brooklyn.geoscaling.primaryDomain=yourname.geopaas.org
-{% endhighlight %}
-
-Replace the values of these fields as appropriate, of course!
-You can, if you prefer, supply (or override) these values in your Brooklyn application.
-
-
-### Setting Up the Locations Database
-
-In order to generate the "closest-IP" script,
-Brooklyn needs a way to find out the latitude and longitude of the
-servers you are using.
-The simplest way to do this is do download the free GeoCityLite binary flatfile
-from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/#Downloads),
-unpack it, and copy it to `~/.brooklyn/GeoLite2-City.mmdb`.
-
-This will be picked up automatically if it is installed.
-You can instead specify to use an online lookup service, such as
-[utrace.de](http://www.utrace.de) by specifying
-`-Dbrooklyn.location.geo.HostGeoLookup=brooklyn.location.geo.UtraceHostGeoLookup`;
-but note this has a cap of 100 per day.
-
-This information is also used to display locations on the map
-in the Brooklyn dashboard.
-Note however that these free services are not 100% accurate;
-they are handy for dev/test but in a production system
-you may wish to specify the geographical information manually in your application,
-or purchase a commercial locations-database subscription.
-
-
-## The Code
-
-Now let's start writing our application.
-The heavy lifting will be done by off-the-shelf Brooklyn classes:
-
- * `DynamicFabric` will create the entity specified by `factory` in each location it is given
- * `GeoscalingDnsService` monitors children of a specified entity (the `DynamicFabric`)
- and adds them as DNS targets for the region they are in
-
-First, however, let's create the Java class -- call it `GlobalWebFabricExample`.
-This will extend the Brooklyn `AbstractApplication`:
-
-{% highlight java %}
-package brooklyn.demo;
-
-import static com.google.common.base.Preconditions.checkNotNull;
-import brooklyn.entity.basic.AbstractApplication;
-
-public class GlobalWebFabricExample extends AbstractApplication {
- @Override
- public void init() {
- // TODO create our app!
- }
-}
-{% endhighlight %}
-
-### The Fabric
-
-The `DynamicFabric` by default has no knowledge of what it will build,
-other than the `factory` it is given to create an entity in each region.
-We'll use the class `ElasticJavaWebAppService.Factory` which creates
-an elastic Java Web App service,
-such as the `ControlledDynamicWebAppCluster` used in the
-[Simple Web Cluster](../webcluster) example, if deploying to VMs,
-or perhaps a `CloudFoundryJavaWebAppCluster` if deploying to a Cloud Foundry location
-(see [brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry)).
-
-{% highlight java %}
- DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
- .displayName("Web Fabric")
- .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
- .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH));
-{% endhighlight %}
-
-Here we have specified the WAR to use with `configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)`.
-The war configuration used in the previous example is only available on web-aware entities;
-configuration specified with a ConfigKey can be done on any entity,
-and is inherited at runtime, so this provides a useful way to specify the WAR to use
-even though the web-aware entities are only constructed at runtime.
-
-
-### Stitching the Fabric together with DNS
-
-To stitch these together seamlessly, another entity will run a policy
-which collects the public-facing IP address of each cluster created by the fabric,
-as it comes online, by watching for `SERVICE_UP` sensors.
-First, however, let's make sure any load-balancer proxies (e.g. nginx) in these clusters
-are listening on port 80:
-
-{% highlight java %}
- DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
- .displayName("Web Fabric")
- .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
- .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)
- .configure(AbstractController.PROXY_HTTP_PORT, PortRanges.fromInteger(80)));
-{% endhighlight %}
-
-Let's now define the Geoscaling entity which does the stitching.
-We need to supply the username, password, and primaryDomainName for Geoscaling;
-we'll take this from the `brooklyn.properties` file mentioned above.
-We'll also specify a `smartSubdomainName`, to use Geoscaling's facility for
-lightweight sub-domains to prevent DNS caching and multiple instances of our application
-from confusing us -- e.g. `brooklyn-1234.yourname.geopaas.org`.
-
-{% highlight java %}
- StringConfigMap config = getManagementContext().getConfig();
-
- GeoscalingDnsService geoDns = addChild(EntitySpec.create(GeoscalingDnsService.class)
- .displayName("GeoScaling DNS")
- .configure("username", checkNotNull(config.getFirst("brooklyn.geoscaling.username"), "username"))
- .configure("password", checkNotNull(config.getFirst("brooklyn.geoscaling.password"), "password"))
- .configure("primaryDomainName", checkNotNull(config.getFirst("brooklyn.geoscaling.primaryDomain"), "primaryDomain"))
- .configure("smartSubdomainName", "brooklyn"));
-{% endhighlight %}
-
-Lastly we need to tell this instance what entity it should monitor
-for children to include as targets:
-
-{% highlight java %}
- geoDns.setTargetEntityProvider(webFabric);
-{% endhighlight %}
-
-
-
-### Cloud Foundry and other PaaS Targets
-
-At this point our core application is ready, and can be deployed to AWS or another VM cloud.
-This may take between 15 and 30 minutes to run,
-mainly spent downloading software
-(unless of course you specify a pre-configured `imageId` which contains the software).
-
-A quicker alternative is to deploy to a Java Web App platform-as-a-service
-such as Cloud Foundry. A major advantage here is that they can provision very quickly,
-in a matter of seconds. Code for this can be found in the
-[brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry),
-along with an example global-web-fabric app.
-
-
-### Imports
-
-Your imports should look as follows:
-
-{% highlight java %}
-import static com.google.common.base.Preconditions.checkNotNull;
-
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import brooklyn.config.StringConfigMap;
-import brooklyn.entity.basic.AbstractApplication;
-import brooklyn.entity.basic.Attributes;
-import brooklyn.entity.dns.geoscaling.GeoscalingDnsService;
-import brooklyn.entity.group.DynamicFabric;
-import brooklyn.entity.proxy.AbstractController;
-import brooklyn.entity.proxying.EntitySpec;
-import brooklyn.entity.webapp.ElasticJavaWebAppService;
-import brooklyn.location.basic.PortRanges;
-{% endhighlight %}
-
-
-### Use of main method (optional)
-
-In this example, we will use the brooklyn CLI launcher. However, it is possible to write your own main method.
-
-The following static constants are assumed (most of these as in the [Simple Web Cluster](../webcluster) example and others):
-
- * `WAR_PATH`, pointing to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
- * `DEFAULT_LOCATIONS`, containing a string spec of the locations to deploy to if none are supplied on the command-line;
- for this example `localhost` will frequently not work unless Geoscaling can see it
- (i.e. it has a public IP and appropriate firewall settings)
-
-The code (which can safely be omitted) is as follows:
-
-{% highlight java %}
-import brooklyn.launcher.BrooklynLauncher;
-import brooklyn.util.CommandLineUtil;
-
-import com.google.common.base.Joiner;
-import com.google.common.collect.ImmutableList;
-import com.google.common.collect.Lists;
-
-// class definition, and rest of class goes here...
-
- public static final Logger log = LoggerFactory.getLogger(GlobalWebFabricExample.class);
-
- // points to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
- public static final String WAR_PATH = "classpath://hello-world-webapp.war";
-
- // locations to deploy to if none are supplied on the command-line; for this example `localhost` will
- // frequently not work unless Geoscaling can see it (i.e. it has a public IP and appropriate firewall settings)
- static final List<String> DEFAULT_LOCATIONS = ImmutableList.of(
- "aws-ec2:eu-west-1",
- "aws-ec2:ap-southeast-1",
- "aws-ec2:us-west-1" );
-
- public static void main(String[] argv) {
- List<String> args = Lists.newArrayList(argv);
- String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
- String locations = CommandLineUtil.getCommandLineOption(args, "--locations", Joiner.on(",").join(DEFAULT_LOCATIONS));
-
- BrooklynLauncher launcher = BrooklynLauncher.newInstance()
- .application(EntitySpec.create(StartableApplication.class, GlobalWebFabricExample.class).displayName("Brooklyn Global Web Fabric Example"))
- .webconsolePort(port)
- .locations(Arrays.asList(locations))
- .start();
-
- Entities.dumpInfo(app);
- }
-{% endhighlight %}
-
-
-
-## Running the Example
-
-Now let's run this example.
-
-{% highlight bash %}
-${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.GlobalWebFabricExample \
---location jclouds:aws-ec2:eu-west-1,jclouds:aws-ec2:ap-southeast-1,jclouds:aws-ec2:us-west-1
-{% endhighlight %}
-
-The management web console will start,
-followed by the web-app services in the locations specified
-creating the VM's as needed.
-Let's look at the management web console, on port 8081:
-
-[](console-map.png)
-
-This shows the targets (e.g. Ireland (AWS eu-west-1), Singapore (AWS ap-southeast-1), and California (AWS us-west-1)).
-This also shows the current status of the application.
-
-Navigating to the "applications" tab, we can view sensors, invoke effectors, control policies,
-and track activity,
-for instance if a cluster is slow to start and you want to find out what is going on
-(you'll find additional information in the `brooklyn.log` file).
-Let's drill down on the Geoscaling DNS entity's sensors:
-
-[](console-geoscaling-details.png)
-
-Here we see it has chosen `brooklyn-vOZ7b4BL.martincloudsoft.geopaas.org` as the geo-load-balanced domain name.
-(Yours will be under `yourname.geopaas.org`, unless you chose a different domain earlier.)
-We can also see the hosts it is forwarding to, one for each cluster, corresponding to the
-children of the Web Fabric (propagated from the nginx hostnames, in the case of the ControlledDynamicWebAppCluster instances).
-
-
-### Checking the Web App
-
-Once Geoscaling reports at least one target, you should be able to access it on the geo-load-balanced domain name:
-
-[](geopaas-deployed-app.png)
-
-Under the covers you are being routed to one of the clusters that has been deployed --
-whichever one is closest to you.
-(Due to DNS caching, at your machine or your ISP, clusters which come online after your first lookup
-will not be picked up until TTL expires, typically 10m, although often more if DNS services don't respect TTL.)
-
-
-### Checking DNS Information
-
-Let's find out exactly where we were routed:
-
-{% highlight bash %}
-% dig brooklyn-csgFCzTm.geopaas.org
-
-; <<>> DiG 9.4.3-P3 <<>> brooklyn-csgFCzTm.geopaas.org
-
-;; QUESTION SECTION:
-;brooklyn-csgFCzTm.geopaas.org. IN A
-
-;; ANSWER SECTION:
-brooklyn-csgFCzTm.geopaas.org. 120 IN CNAME ec2-46-137-138-4.eu-west-1.compute.amazonaws.com.
-ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. 215 IN A 46.137.138.4
-{% endhighlight %}
-
-This was run from Scotland so it seems a sensible choice.
-(Some portions of the output from `dig` have been removed for readability.)
-
-We can get more information by looking at the TXT records:
-
-{% highlight bash %}
-% dig +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
-
-; <<>> DiG 9.4.3-P3 <<>> +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
-
-...
-
-geopaas.org. 86400 IN NS ns1.geoscaling.com.
-geopaas.org. 86400 IN NS ns2.geoscaling.com.
-geopaas.org. 86400 IN NS ns3.geoscaling.com.
-geopaas.org. 86400 IN NS ns4.geoscaling.com.
-;; Received 133 bytes from 199.249.112.1#53(a2.org.afilias-nst.info) in 45 ms
-
-brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "Request from [54,-2]-(GB) directed to Ireland (IE)"
-brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "GeoScaling config auto-updated by Brooklyn 2012-04-26 12:27:25 UTC"
-;; Received 189 bytes from 80.87.128.195#53(ns3.geoscaling.com) in 60 ms
-{% endhighlight %}
-
-
-## Next Steps
-
-This example has shown how to create a multi-region fabric, using the abstractions from
-[jclouds](http://jclouds.org) under the covers to make it easy to access different hosting providers
-simultaneously, and using higher-level abstractions in Brooklyn to mix PaaS systems with
-bare-VM (or even bare-metal, if you specify fixed IPs).
-
-This is meant as just the beginning however.
-Here are some questions to think about and code challenges to give you a steer for what to explore next.
-
-
- 1. The routines used at Geoscaling optimize for latency between the user and the location of the web-cluster.
- What other strategies might be used? Cost? Compliance? How would you code these?
-
- 2. This example ignores data, but you clearly can't do that in the real world.
- When big-data is involved, does this introduce other considerations for optimizing geo-location?
-
- 3. Add a data tier to this system, such as MySQL or Mongo, or even Hadoop.
- You might start with a single instance or cluster,
- but the real fun starts with a fabric, and defining the synchronization/replication strategies
- between the different clusters.
- This isn't for the faint-hearted, but whatever you create will certainly be of interest
- to people in the Brooklyn community.
- Please [let us know]({{ site.path.guide }}/meta/contact.html) what you've built!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/1d6ce7cf/docs/guide/use/examples/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/index.md b/docs/guide/use/examples/index.md
deleted file mode 100644
index f55643f..0000000
--- a/docs/guide/use/examples/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-layout: guide-normal
-title: Examples
-toc: /guide/toc.json
----
-
-We currently have the following examples on the site:
-
-{% capture ltocs %}{% readj toc.json %}{% endcapture %}
-{% jsonball ltoc from var ltocs %}
-
-{% for x in ltoc %}
-* <a href="{{ x.file }}">{{ x.title }}</a>
-{% endfor %}
-
-There are examples in the code also, just check out the examples/ project.
-
-**Have one of your own?** [Add it here!]({{site.path.guide}}/dev/tips/update-docs.html)