brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [09/11] incubator-brooklyn git commit: wholesale copy of master docs (from #458) with version changed to 0.7.0-M2-incubating
Date Tue, 20 Jan 2015 16:29:19 GMT
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/cli.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/cli.md b/docs/guide/ops/cli.md
new file mode 100644
index 0000000..3e44c62
--- /dev/null
+++ b/docs/guide/ops/cli.md
@@ -0,0 +1,143 @@
+---
+title: CLI
+layout: website-normal
+---
+
+To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
+
+{% highlight bash %}
+% bin/brooklyn launch
+{% endhighlight %}
+
+With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
+No password is set, but the server is listening only on the loopback network interface for security.
+Once [security is configured](brooklyn_properties.html), Brooklyn will listen on all network interfaces by default.
+
+You may wish to [add Brooklyn to your path](#path-setup);
+assuming you've done this, to get information the supported CLI options 
+at any time, just run `brooklyn help`:
+
+{% highlight bash %}
+% bin/brooklyn help
+
+usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
+
+The most commonly used brooklyn commands are:
+    help     Display help information about brooklyn
+    info     Display information about brooklyn
+    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
+
+See 'brooklyn help <command>' for more information on a specific command.
+{% endhighlight %}
+
+
+
+## Configuration
+
+Brooklyn can read configuration from a variety of places:
+        
+* the file `~/.brooklyn/brooklyn.properties` (unless `--noGlobalBrooklynProperties` is specified)
+* another file, if the `--localBrooklynProperties <local brooklyn.properties file>`
+* ``-D`` defines on the brooklyn (java) command-line
+* shell environment variables
+
+These properties are described in more detail [here](brooklyn_properties.html).
+
+
+
+## Path Setup
+
+In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory:
+
+{% highlight bash %}
+BROOKLYN_HOME=/path/to/brooklyn/
+export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
+{% endhighlight %}
+
+
+## Running from a Source Build
+
+Here is an example of the commands you might run to get the Brooklyn code, 
+compile it and launch an application:
+
+{% highlight bash %}
+git clone https://github.com/apache/incubator-brooklyn.git
+cd brooklyn
+mvn clean install -DskipTests
+BROOKLYN_HOME=$(pwd)
+export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
+export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
+brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
+{% endhighlight %}
+
+
+## Extending the Classpath
+
+You can add things to the Brooklyn classpath in a number of ways:
+
+* Add ``.jar`` files to Brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath.
+* Add ``.jar`` files to Brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath.
+* Add resources to Brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath.
+* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the Brooklyn classpath.
+
+
+## Cloud Explorer
+
+The `brooklyn` command line tool includes support for querying (and managing) cloud
+compute resources and blob-store resources. 
+
+For example, `brooklyn cloud-compute list-instances --location aws-ec2:eu-west-1`
+will use the AWS credentials from `brooklyn.properties` and list the VM instances
+running in the given EC2 region.
+
+Use `brooklyn help` and `brooklyn help cloud-compute` to find out more information.
+
+This functionality is not intended as a generic cloud management CLI, but instead 
+solves specific Brooklyn use-cases. The main use-case is discovering the valid 
+configuration options on a given cloud, such as for `imageId` and `hardwareId`.
+
+
+### Cloud Compute
+
+The command `brooklyn cloud-compute` has the following options:
+
+* `list-images`: lists VM images within the given cloud, which can be chosen when
+  provisioning new VMs.
+  This is useful for finding the possible values for the `imageId` configuration.
+
+* `get-image <imageId1> <imageId2> ...`: retrieves metadata about the specific images.
+
+* `list-hardware-profiles`: lists the ids and the details of the hardware profiles
+  available when provisioning. 
+  This is useful for finding the possible values for the `hardwareId` configuration.
+
+* `default-template`: retrieves metadata about the image and hardware profile that will
+  be used by Brooklyn for that location, if no additional configuration options
+  are supplied.
+
+* `list-instances`: lists the VM instances within the given cloud.
+
+* `terminate-instances <instanceId1> <instanceId2> ...`: Terminates the instances with
+  the given ids.
+
+
+## Blob Store
+
+The command `brooklyn cloud-blobstore` is used to access a given object store, such as S3
+or Swift. It has the following options:
+
+* `list-containers`: lists the containers (i.e. buckets in S3 terminology) within the 
+  given object store.
+
+* `list-container <containerName>`: lists all the blobs (i.e. objects) contained within 
+  the given container.
+
+* `blob --container <containerName> --blob <blobName>`: retrieves the given blob
+  (i.e. object), including metadata and its contents.
+
+
+## Other Topics
+
+The CLI arguments for [persistence and HA](persistence/)
+are described separately,
+as is [detailed configuration](brooklyn_properties.html).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index 27da59f..6b523f6 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -2,10 +2,12 @@
 title: Operations
 layout: website-normal
 children:
-- locations/index.md
-- locations/configuring.md
+- cli.md
+- brooklyn_properties.md
+- locations/
 - persistence/
-- webconsole/
+- catalog/
+- logging.md
 ---
 
 {% include list-children.html %}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/locations/configuring.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/configuring.md b/docs/guide/ops/locations/configuring.md
deleted file mode 100644
index 3a02260..0000000
--- a/docs/guide/ops/locations/configuring.md
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Configuring Locations
-layout: guide-normal
----
-
-<a id="locations"></a>
-
-Brooklyn supports deploying to any machine which admits SSH access, as well as to
-a huge variety of external and on-premise clouds.  You can also connect to services,
-or use whatever technique for deployment suits you best (such as Xebia Overthere, in development!).
-
-Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the following:
-
-{% highlight bash %}
-# use this key for localhost (this is the default, although if you have a passphrase you must set it)
-brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa
-
-brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
-   
-# use a special key when connecting to public clouds, and a particularly special one for AWS
-brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa
-
-# AWS credentials (when deploying to location jclouds:aws-ec2)
-brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
-brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
-
-# credentials for 'geoscaling' service
-brooklyn.geoscaling.username=cloudsoft  
-brooklyn.geoscaling.password=xxx
-{% endhighlight %}
-
-These can also be set as environment variables (in the shell) or system properties (java command line).
-(There are also ``BROOKLYN_JCLOUDS_PRIVATE_KEY_FILE`` variants accepted.)
-
-For any jclouds provider you will typically need to set ``identity`` and ``credential``
-in the ``brooklyn.location.jclouds.provider`` namespace.
-
-To deploy to sets of machines with known IP's, assuming you have the credentials,
-use the syntax ``byon:(hosts="user@10.9.1.1,user@10.9.1.2,user@10.9.1.3")``
-(this requires your default private key to have access; 
-see the ``prod1`` example below for specifying other credentials). 
-
-A wide range of other fields is available, because in the real world sometimes things do get complicated.
-The following is supported from the configuration file (with whatever customization you might want available in code): 
-
-- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
-  ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``, or other places
-  where ``privateKeyFile`` is valid).  If you don't like keys, you can just use a plain old ``password``.
-
-- Hardware requirements such as ``minRam`` and ``minCores`` can be supplied, or a ``hardwareId``  (jclouds only)
-
-- Specific Secury Groups can be specified using `securityGroups`, if you want to reuse set of existing ones (jclouds only)
-
-- Specific KeyPair can be specified using `keyPair`, if you want to reuse an existing keypair (jclouds only).
-
-- Specific VM images can be specified using ``imageId`` or ``imageNameRegex`` (jclouds only)
-
-- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"`` (jclouds only)
-
-- A ``user`` can be specified, with the property that -- in a jclouds world -- the user will be *created* on the machine,
-  with admin rights, authorizing the relevant public key (corresponding to the private key, or as described below). 
-  Login for the root account will be disabled, as will login by password if a public key is supplied. 
-  (This is skipped if ``user`` is the ``root`` or other initial login user.)
-  
-- You can specify the user account to use to login to jclouds initially with the ``loginUser`` property.
-  Typically this is auto-detected by jclouds
-  (often ``root``, or ``ubuntu`` or ``ec2-user`` for known Ubuntu or Amazon Linux images), 
-  but the strategy isn't foolproof, particularly in some private cloud setups. (jclouds only). In some cases, you may need to specify a `loginUser.privateKeyFile` if the image you are using doesn't allow ssh password login.
-
-- Public keys can be specified using ``publicKeyFile``, 
-  although these can usually be omitted if they follow the common pattern of being
-  the private key file with the suffix ``.pub`` appended.
-  (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
-  or might not even have, the private key of the ``root`` user in order to log in.)
-
-- You can specify the number of attempts Brooklyn should make to create
-  machines with ``machineCreateAttempts`` (jclouds only). This is useful for
-  working around the rare occasions in which cloud providers give machines that
-  are dead on arrival.
-
-You can also define named locations for commonly used groups of properties, 
-with the syntax ``brooklyn.location.named.your-group-name.``
-followed by the relevant properties.
-These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment location.
-
-Some more advanced examples showing the syntax and properties above are as follows:
-
-{% highlight bash %}
-# Production pool of machines for my application (deploy to named:prod1)
-brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
-brooklyn.location.named.prod1.user=produser1
-brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
-brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
-
-# AWS using my company's credentials and image standard, then labelling images so others know they're mine
-brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
-brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
-brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
-brooklyn.location.named.company-jungle.imageId=ami-12345
-brooklyn.location.named.company-jungle.minRam=2048
-brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
-brooklyn.location.named.company-jungle.machineCreateAttempts=2
-{% endhighlight %}
-

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md
index 4fc3b98..810f7b8 100644
--- a/docs/guide/ops/locations/index.md
+++ b/docs/guide/ops/locations/index.md
@@ -1,101 +1,268 @@
 ---
-title: Locations Intro
-layout: guide-normal
+title: Locations
+layout: website-normal
+children:
+- { section: Clouds }
+- { section: Inheritance and Named Locations, title: Named Locations }
+- { section: Localhost }
+- { section: BYON }
+- more-locations.md
+- ssh-keys.md
 ---
 
-Locations are the environments to which Brooklyn deploys applications.
-These can be clouds (public or private), fixed infrastructure environments, or your laptop.
+Locations are the environments to which Brooklyn deploys applications, including:
 
-Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`.
+Brooklyn supports a wide range of locations:
 
-## Setting up an SSH key
+* <a href="#clouds">Clouds</a>, where it will provision machines
+* <a href="#localhost">Localhost</a> (e.g. your laptop), 
+  where it will deploy via `ssh` to `localhost` for rapid testing
+* <a href="#byon">BYON</a>, where you "bring your own nodes",
+  specifying already-existing hosts to use
+* And many others, including object stores and online services
 
-While some locations can be accessed using *user:password* credentials it is more common to use authentication keys.
+Configuration can be set in `~/.brooklyn/brooklyn.properties`
+or directly in YAML when specifying a location.
+On some entities, config keys determining maching selection and provisioning behavior
+can also be set `in `provisioning.properties`.  
 
-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:
+### Clouds
 
-{% highlight bash %}
-$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
-{% endhighlight %}
+For most cloud provisioning tasks, Brooklyn uses
+<a href="http://jclouds.org">Apache jclouds</a>.
+The identifiers for some of the most commonly used jclouds-supported clouds are
+(or [see the full list](http://jclouds.apache.org/reference/providers/)):
 
-If you wish to use an existing key SSH, or an SSH key
-that has a passphrase, or a location other than `~/.ssh`, you can specify this in
-`brooklyn.properties` using `brooklyn.location.localhost.privateKeyFile` and
-`brooklyn.location.localhost.privateKeyPassphrase`.
+* `jclouds:aws-ec2:<region>`: Amazon EC2, where `:<region>` might be `us-east-1` or `eu-west-1` (or omitted)
+* `jclouds:softlayer:<region>`: IBM Softlayer, where `:<region>` might be `dal05` or `ams01` (or omitted)
+* `jclouds:google-compute-engine`: Google Compute Engine
+* `jclouds:openstack-nova:<endpoint>`: OpenStack, where `:<endpoint>` is the access URL (required)
+* `jclouds:cloudstack:<endpoint>`: Apache CloudStack, where `:<endpoint>` is the access URL (required)
 
-## Localhost
+For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`:
 
-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 yaml %}
+location:
+  jclouds:aws-ec2:
+    identity: ABCDEFGHIJKLMNOPQRST
+    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %} 
+
+The above YAML can be embedded directly in blueprints, either at the root or on individual services.
+If you prefer to keep the credentials separate, these can be set instead in `brooklyn.properties` 
+in the `jclouds.<provider>` namespace:
 
 {% highlight bash %}
-# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
-$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
+brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
 {% endhighlight %}
 
-MacOS user? In addition to the above, enable 'Remote Login' in System Preferences >
- Sharing.
+And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`.
 
+The Getting Started [template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties) contains more examples 
+of configuring cloud endpoints, including information on credential types used in different clouds.
 
-## Cloud Endpoints (via jclouds)
 
-[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/) is available on jclouds.apache.org.
+#### OS Initial Login and Setup
 
-Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key on the management machine.
+Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.
 
-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.)
+The credentials for the initial OS log on are typically discovered from the cloud, 
+but in some environments this is not possible.
+The keys `loginUser` and either `loginUser.password` or `loginUser.privateKeyFile` can be used to force
+Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.
+(This is particularly useful when using a custom image templates where the cloud-side account management logic is not enabled.)
 
-### Example: AWS Virginia Large Centos
+Following a successful logon, Brooklyn performs the following steps to configure the machine:
 
-{% highlight bash %}
-## Snippet from ~/.brooklyn/brooklyn.properties.
+1. to create a new user with the same name as the user `brooklyn` is running as locally
+  (this can be overridden with `user`, below)
+
+1. to install the local user's `~/.ssh/id_rsa.pub` as an `authorized_keys` on the new machine,
+   to make it easy for the operator to `ssh` in
+   (override with `privateKeyFile`; or if there is no `id_{r,d}sa{,.pub}` an ad hoc keypair will be generated;
+   if there is a passphrase on the key, this must be supplied)  
+
+1. give `sudo` access to the newly created user (override with `grantUserSudo: false`)
+
+1. disable direct `root` login to the machine
+
+These steps can be skipped or customized as described below.
+
+
+
+#### jclouds Config Keys
+
+The following is a subset of the most commonly used configuration keys used to customize 
+cloud provisioning.
+For more keys and more detail on the keys below, see 
+{% include java_link.html class_name="JcloudsLocationConfig" package_path="brooklyn/location/jclouds" project_subpath="locations/jclouds" %}.
+
+###### OS Setup
+
+- `user` and `password` can be used to configure the operating user created on cloud-provisioned machines
+
+- The `loginUser` config key (and subkeys) control the initial user to log in as,
+  in cases where this cannot be discovered from the cloud provider
+ 
+- Private keys can be specified using ``privateKeyFile``; 
+  these are not copied to provisioned machines, but are required if using a local public key
+  or a pre-defined `authorized_keys` on the server.
+  (For more information on SSH keys, see [here](ssh-keys.html).) 
+
+- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course!
+  ``privateKeyPassphrase`` does the trick (as in ``brooklyn.location.jclouds.privateKeyPassphrase``, or other places
+  where ``privateKeyFile`` is valid).  If you don't like keys, you can just use a plain old ``password``.
+
+- Public keys can be specified using ``publicKeyFile``, 
+  although these can usually be omitted if they follow the common pattern of being
+  the private key file with the suffix ``.pub`` appended.
+  (It is useful in the case of ``loginUser.publicKeyFile``, where you shouldn't need,
+  or might not even have, the private key of the ``root`` user in order to log in.)
+
+- Use `dontCreateUser` to have Brooklyn run as the initial `loginUser` (usually `root`),
+  without creating any other user.
+
+- A post-provisioning `setup.script` can be specified (as a URL) to run an additional script,
+  before making the `Location` available to entities,
+  optionally also using `setup.script.vars` (set as `key1:value1,key2:value2`)
+
+
+###### VM Creation
+    
+- Most providers require exactly one of either `region` (e.g. `us-east-1`) or `endpoint` (the URL, usually for private cloud deployments)
+
+- Hardware requirements can be specified, including 
+  ``minRam``, ``minCores``, and `os64Bit`; or as a specific ``hardwareId``
+
+- VM image constraints can be set using `osFamily` (e.g. `Ubuntu`, `CentOS`, `Debian`, `RHEL`)
+  and `osVersionRegex`, or specific VM images can be specified using ``imageId`` or ``imageNameRegex``
+
+- Specific VM images can be specified using ``imageId`` or ``imageNameRegex``
+
+- Specific Security Groups can be specified using `securityGroups`, as a list of strings (the existing security group names),
+  or `inboundPorts` can be set, as a list of numeric ports (selected clouds only)
 
-# Provide jclouds with AWS API credentials.
-brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString
+- A specific existing key pair for the cloud to set for `loginUser` can be specified using `keyPair`
+  (selected clouds only)
 
-# 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
+- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"``
 
-# (Using the same name) specify image, user and minimum ram size (ie instance size)
+- You can specify the number of attempts Brooklyn should make to create
+  machines with ``machineCreateAttempts`` (jclouds only). This is useful for
+  working around the rare occasions in which cloud providers give machines that
+  are dead on arrival.
+
+- If you want to investigate failures, set `destroyOnFailure` to `false`
+  to keep failed VM's around. (You'll have to manually clean them up.)
+
+
+### Inheritance and Named Locations
+
+Named locations can be defined for commonly used groups of properties, 
+with the syntax ``brooklyn.location.named.your-group-name.``
+followed by the relevant properties.
+These can be accessed at runtime using the syntax ``named:your-group-name`` as the deployment location.
+
+Some illustrative examples using named locations and
+showing the syntax and properties above are as follows:
+
+{% highlight bash %}
+# Production pool of machines for my application (deploy to named:prod1)
+brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.prod1.user=produser1
+brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase
+
+# AWS using my company's credentials and image standard, then labelling images so others know they're mine
+brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
+brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
+brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
+brooklyn.location.named.company-jungle.imageId=ami-12345
+brooklyn.location.named.company-jungle.minRam=2048
+brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
+brooklyn.location.named.company-jungle.machineCreateAttempts=2
+
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2
+brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
 brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096
+{% endhighlight %}
 
+If you are confused about inheritance order, the following test may be useful:
 
+{% highlight bash %}
+brooklyn.location.jclouds.KEY=VAL1
+brooklyn.location.jclouds.aws-ec2.KEY=VAL2
+brooklyn.location.named.my-aws=jclouds:aws-ec2
+brooklyn.location.named.my-aws.KEY=VAL3
 {% endhighlight %}
 
-This will  appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line as:  `AWS\ Virginia\ Large\ Centos`.
+In the above example, if you deploy to `location: named:my-aws`,
+Brooklyn will get `VAL3` for `KEY`;
+this overrides `VAL2` which applies by default to all `aws-ec2` locations,
+which in turn overrides `VAL1`, which applies to all jclouds locations. 
 
-See the Getting Started [template brooklyn.properties](../start/brooklyn.properties) for more examples of using cloud endpoints.
 
+### Localhost
 
-## Fixed Infrastructure
+If passwordless ssh login to `localhost` is enabled on your machine,
+you should be able to deploy blueprints with no special configuration,
+just by specifying `location: localhost` in YAML.
 
-Bringing your own nodes (BYON) to Brooklyn is straightforward.
+If you use a passpharse or prefer a different key, these can be configured as follows: 
 
-You will need the IP addresses of the nodes and the access credentials. Both SSH and password based login are supported.
+{% highlight bash %}
+brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
+brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE
+{% endhighlight %}
 
-### Example: On-Prem Iron
+If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup). 
 
-{% 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
 
+### BYON
+
+"Bring-your-own-nodes" mode is useful in production, were machines have been provisioned by someone else, 
+and during testing, to cut down provisioning time.
+
+To deploy to machines with known IP's in a blueprint, use the following syntax:
+
+{% highlight yaml %}
+location:
+  byon:
+    user: brooklyn
+    privateKeyFile: ~/.ssh/brooklyn.pem
+    hosts:
+    - 192.168.0.18
+    - 192.168.0.19
 {% endhighlight %}
 
+Some of the login properties as described above for jclouds are supported,
+but not `loginUser` (as no users are created), and not any of the
+VM creation parameters such as `minRam` and `imageId`.
+(These clearly do not apply in the same way, and they are *not* 
+by default treated as constraints, although an entity can confirm these
+where needed.)
+As before, if the brooklyn user and its default key are authorized for the hosts,
+those fields can be omitted.
 
-## Advanced Options
+Named locations can also be configured in your `brooklyn.properties`,
+using the format ``byon:(key=value,key2=value2)``.
+For convenience, for hosts wildcard globs are supported.
 
-Unusual provider? 'Featureful' API? Brooklyn can cope.
+{% highlight bash %}
+brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
+brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
+brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase
+{% endhighlight %}
 
-[This spreadsheet](https://docs.google.com/a/cloudsoftcorp.com/spreadsheet/ccc?key=0Avy7Tdf2EOIqdGQzSlNiT2M0V19SejBScDhSdzMtT2c) provides explanation, guidance, and examples for the majority of location options.
 
 
+### Other Location Topics
 
+* [More Locations](more-locations.html)
+* [SSH Keys](ssh-keys.html)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/locations/more-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/more-locations.md b/docs/guide/ops/locations/more-locations.md
new file mode 100644
index 0000000..994eaf7
--- /dev/null
+++ b/docs/guide/ops/locations/more-locations.md
@@ -0,0 +1,55 @@
+---
+title: More Locations
+layout: website-normal
+children:
+- { section: Single Host }
+- { section: The Multi Location }
+- { section: The Server Pool }
+---
+
+Some additional location types are supported for specialized situations:
+
+### Single Host
+
+The spec `host`, taking a string argument (the address) or a map (`host`, `user`, `password`, etc.),
+provides a convenient syntax when specifying a single host.
+For example:
+
+{% highlight yaml %}
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server 
+  location:
+    host: 192.168.0.1
+{% endhighlight %}
+
+Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`.
+
+
+### The Multi Location
+
+The spec `multi` allows multiple locations, specified as `targets`,
+to be combined and treated as one location.
+When the first target is full, the next is tried, and so on:
+
+{% highlight yaml %}
+location:
+  multi:
+    targets:
+    - byon:(hosts=192.168.0.1)
+    - jclouds:aws-ec2:
+      identity: acct1
+    - jclouds:aws-ec2:
+      identity: acct2      
+{% endhighlight %}
+
+The example above provisions the first node to `192.168.0.1`,
+then it provisions into `acct1` at Amazon if possible,
+and then to `acct2`.
+
+
+
+### The Server Pool
+
+The {% include java_link.html class_name="ServerPool" package_path="brooklyn/entity/pool" project_subpath="software/base" %}
+entity type allows defining an entity which becomes available as a location.
+

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/locations/ssh-keys.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/locations/ssh-keys.md b/docs/guide/ops/locations/ssh-keys.md
new file mode 100644
index 0000000..f805253
--- /dev/null
+++ b/docs/guide/ops/locations/ssh-keys.md
@@ -0,0 +1,85 @@
+---
+title: SSH Keys
+layout: website-normal
+---
+
+SSH keys are one of the simplest and most secure ways to access remote servers.
+They consist of two parts:
+
+* A private key (e.g. `id_rsa`) which is known only to one party or group
+  
+* A public key (e.g. `id_rsa.pub`) which can be given to anyone and everyone,
+  and which can be used to confirm that a party has a private key
+  (or has signed a communication with the private key)
+  
+In this way, someone -- such as you -- can have a private key,
+and can install a public key on a remote machine (in an `authorized_keys` file)
+for secure automated access.
+Commands such as `ssh` (and Brooklyn) can log in without
+revealing the private key to the remote machine,
+the remote machine can confirm it is you accessing it (if no one else has the private key),
+and no one snooping on the network can decrypt of any of the traffic.
+ 
+
+### Creating an SSH Key
+
+If you don't have an SSH key, create one with:
+
+{% highlight bash %}
+$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
+{% endhighlight %}
+
+
+### Localhost Setup
+
+If you want to deploy to `localhost`, ensure that you have a public and private key,
+and that your key is authorized for ssh access:
+
+{% highlight bash %}
+# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
+$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+{% endhighlight %}
+
+Now verify that your setup by running the command: `ssh localhost echo hello world`
+
+If your setup is correct, you should see `hello world` printed back at you.
+
+On the first connection, you may see a message similar to this:
+
+<pre>
+The authenticity of host 'localhost (::1)' can't be established.
+RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
+Are you sure you want to continue connecting (yes/no)?
+</pre>
+
+Simply answer 'yes' and then repeat the command again.
+
+If this isn't the case, see below. 
+
+
+
+
+### Potential Problems
+
+* **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
+
+* **Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase`
+  as described [here](index.html#os-setup).
+  If you're not sure, or you don't know what a passphrase is, you can test this by executing `ssh-keygen -y`.
+  If it does *not* ask for a passphrase, then your key has no passphrase.
+  If your key does have a passphrase, you can remove it by running `ssh-keygen -p`.
+
+* Check that you have an `~/.ssh/id_rsa` file (or `id_dsa`) and a corresponding public key with a `.pub` extension;
+  if not, create one as described above
+  
+* `~/.ssh/` or files in that directory may have permissions they shouldn't: 
+  they should be visible only to the user (apart from public keys),
+  both on the source machine and the target machine.
+  You can verify this with `ls -l ~/.ssh/`:  lines should start with `-rw-------` or `-r--------` (or `-rwx------` for directories). 
+  If it does not, execute `chmod go-rwx ~/.ssh ~/.ssh/*`.
+ 
+* Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers;
+  if command-line `ssh` and `scp` work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.
+
+* Missing entropy: creating and using ssh keys requires randomness available on the servers,
+  usually in `/dev/random`; see [here]({{ site.path.website }}/documentation/increase-entropy.html) for more information

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/logging.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/logging.md b/docs/guide/ops/logging.md
new file mode 100644
index 0000000..fc1da3c
--- /dev/null
+++ b/docs/guide/ops/logging.md
@@ -0,0 +1,46 @@
+---
+title: Logging
+layout: website-normal
+---
+
+
+Brooklyn uses the SLF4J logging facade, which allows use of many popular frameworks including `logback`, 
+`java.util.logging` and `log4j`.
+
+The convention for log levels is as follows:
+
+* `ERROR` and above:  exceptional situations which indicate that something has unexpectedly failed or
+some other problem has occured which the user is expected to attend to
+* `WARN`:  exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response
+* `INFO`:  a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer
+* `DEBUG` and lower:  detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances.
+
+Loggers follow the ``package.ClassName`` naming standard.  
+
+## Standard Configuration
+
+A `logback.xml` file is included in the `conf/` directly of the Brooklyn distro;
+this is read by `brooklyn` at launch time.  Changes to the logging configuration,
+such as new appenders or different log levels, can be made directly in this file
+or in a new file included from this.
+
+
+## Advanced Configuration
+
+The default `logback.xml` file references a collection of other log configuration files
+included in the Brooklyn jars. It is necessary to understand the source structure
+in the [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project.
+
+For example, to change the debug log inclusions, create a folder `brooklyn` under `conf`
+and create a file `logback-debug.xml` based on the
+[brooklyn/logback-debug.xml]({{ site.brooklyn.url.git }}/usage/logback-includes/src/main/resources/brooklyn/logback-debug.xml)
+from that project.
+
+
+## For More Information
+
+The following resources may be useful when configuring logging:
+
+* The [logback-includes]({{ site.brooklyn.url.git }}/usage/logback-includes) project
+* [Brooklyn Developer Guide]({{ site.path.guide }}/dev/tips/logging.html) logging tips
+* The [Logback Project](http://logback.qos.ch/) home page

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/persistence/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md
index be19606..cbb3112 100644
--- a/docs/guide/ops/persistence/index.md
+++ b/docs/guide/ops/persistence/index.md
@@ -1,6 +1,13 @@
 ---
 title: Persistence
-layout: guide-normal
+layout: website-normal
+children:
+- { section: Command Line Options }
+- { section: File-based Persistence }
+- { section: Object Store Persistence }
+- { section: Rebinding to State }
+- { section: High Availability }
+- { section: Writing Persistable Code }
 ---
 
 Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted, 
@@ -92,8 +99,8 @@ brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLoc
 {% endhighlight %}
 
 
-Rebind
-------
+Rebinding to State
+------------------
 
 When Brooklyn starts up pointing at existing state, it will recreate the entities, locations 
 and policies based on that persisted state.
@@ -104,8 +111,7 @@ HTTP or JMX). This new state will be reported in the web-console and can also tr
 any registered policies.
 
 
-Copying Persistence State
--------------------------
+## CLI Commands for Copying State
 
 Brooklyn includes a command to copy persistence state easily between two locations.
 The `copy-state` CLI command takes the following arguments:
@@ -122,10 +128,11 @@ The `copy-state` CLI command takes the following arguments:
   The local transformations file to be applied to the copy of the data before uploading it.
 
 
-Handling Rebind Failures
-------------------------
-If rebind were to fail for any reason, details of the underlying failures will be reported 
-in the brooklyn.debug.log. There are several approaches to resolving problems.
+## Handling Rebind Failures
+
+If rebind fails fail for any reason, details of the underlying failures will be reported 
+in the `brooklyn.debug.log`. There are several approaches to resolving problems.
+
 
 ### Determine Underlying Cause
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/webconsole/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/index.md b/docs/guide/ops/webconsole/index.md
deleted file mode 100644
index 9764ae9..0000000
--- a/docs/guide/ops/webconsole/index.md
+++ /dev/null
@@ -1,399 +0,0 @@
----
-title: Runtime Management
-layout: guide-normal
----
-
-brooklyn uses many of the ideas from autonomic computing to implement management of entities in a structured and reusable fashion (including provisioning, 
-healing, and optimising).
-
-Each external system, process or service is represented as an entity within brooklyn, with collections of these being represented and
-managed by other entities, and so forth through a hierarchy rooted in entities referred to as "Applications". Each entity has:
-
-- provisioning and tear-down logic for the external system(s) it represents
-- sensors which it publishes to report on its state and activity
-- effectors which can be invoked to change it
-- policies which perform analysis, enrichment (sensors), and execution (effectors). It is the policies in brooklyn which
-  perform the self-management (in autonomic terms) by monitoring sensors and invoking effectors.
-
-There are several ways to launch applications with brooklyn, and useful configuration options,
-as well as a debug-view web console.
-This chapter describes these high-level runtime concepts, then proceeds to present more
-detailed information on the underlying implementation of management within brooklyn.
-
-
-Startup Configuration
----------------------
-
-brooklyn can read configuration from a variety of places:
-
-* the file ``~/.brooklyn/brooklyn.properties``
-* ``-D`` defines on the brooklyn (java) command-line
-* shell environment variables
-
-Default properties are described in the Javadoc and code of the class ``BrooklynProperties``,
-but some of the most common ones are:
- 
-{% highlight properties %}
-brooklyn.location.jclouds.aws-ec2.identity=AKA50M30N3S1DFR0MAW55
-brooklyn.location.jclouds.aws-ec2.credential=aT0Ps3cr3tC0D3wh1chAW5w1llG1V3y0uTOus333
-brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/path/to/id_rsa       # use specified key (default is ~/.ssh/id_rsa)
-brooklyn.location.jclouds.aws-ec2.publicKeyFile=~/path/to/id_rsa.pub    # (optional, inferred from previous if omitted)
-{% endhighlight %} 
-
-These can be specified as a shell environment variable or as a Java system property,
-although in those contexts the conventional format ``BROOKLYN_JCLOUDS_AWS_EC2_IDENTITY`` 
-is supported and recommended. 
-
-
-
-Command Line Interface
-----------------------
-
-Brooklyn comes with a Command Line Interface (cli) that makes it easier to launch an application.
-
-In order to have easy access to the cli it is useful to configure the PATH environment variable to also point to the cli's bin directory:
-
-{% highlight bash %}
-BROOKLYN_HOME=/path/to/brooklyn/
-export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
-{% endhighlight %}
-
-If you have set this up correctly you should be able to invoke the ```brooklyn``` command:
-
-{% highlight bash %}
-brooklyn
-{% endhighlight %}
-
-To get information about all the supported cli options just run:
-
-{% highlight bash %}
-brooklyn help
-usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
-
-The most commonly used brooklyn commands are:
-    help     Display help information about brooklyn
-    info     Display information about brooklyn
-    launch   Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
-
-See 'brooklyn help <command>' for more information on a specific command.
-{% endhighlight %}
-
-Here is an example of the commands you might run to get the Brooklyn code, compile it and launch an application:
-
-{% highlight bash %}
-git clone https://github.com/apache/incubator-brooklyn.git
-cd brooklyn
-mvn clean install -DskipTests
-BROOKLYN_HOME=$(pwd)
-export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
-export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
-brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost
-{% endhighlight %}
-
-You can add things to the brooklyn classpath in a number of ways:
-
-* Add ``.jar`` files to brooklyn's ``./lib/dropins/`` directory. These are added at the end of the classpath.
-* Add ``.jar`` files to brooklyn's ``./lib/patch/`` directory. These are added at the front of the classpath.
-* Add resources to brooklyn's ``./conf/`` directory. This directory is at the very front of the classpath.
-* Use the ``BROOKLYN_CLASSPATH`` environment variable. If set, this is prepended to the brooklyn classpath.
-
-
-Management Web Console
-----------------------
-
-The web-based management console that comes with brooklyn serves as a way to observe and manage brooklyn entities.
-It provides low-level details of activity (including stack-traces), sensor values, and policies,
-and some visual widgets for observing what is happening.
-This console is not designed as a management dashboard or portal -- 
-many good options exist in that space --
-but what could be useful is to embed widgets from the brooklyn portal for selected high-level views.
-
-<!-- FIXME Update to use new construction pattern, rather than calling app's constructor -->
-To start a management console from your own code, use ``BrooklynLaucher.launch``:
-{% highlight java %}
-public static void main(String[] argv) {
-	Application app = new MyApplicationExample(displayName:"myapp")
-    BrooklynServerDetails server = BrooklynLauncher.newLauncher()
-            .managing(app)
-            .launch();
-	// ...
-}
-{% endhighlight %}
-
-This will start an embedded brooklyn management node, including the web console.
-The URL for the web console defaults to http://127.0.0.1:8081, .
-
-The mechanism for launching brooklyn management will change in a future release. For this release, the brooklyn management node is embedded.
-
-The console contains two main views: Dashboard and Detail. These update in real-time.
-
-**Dashboard**
-
-The dashboard is a high level overview of the state of the application:
-
-[![Screenshot of the Webconsole Dashboard](webconsole-dashboard-w400.png "Screenshot of the Webconsole Dashboard")](webconsole-dashboard.png)
-
-
-**Detail**
-
-The Detail view gives an in-depth view of the application and its entities. 
-Child-parent relationships between entities are navigable using the entity tree;
-each entity is shown with its children (or, in the case of childless group entities, the members). 
-Selecting a specific entity allows you to access detailed information about that entity.
-
-[![Screenshot of the Webconsole Detail](webconsole-detail-w400.png "Screenshot of the Webconsole Detail")](webconsole-detail.png)
-
-The Detail view contains a breadcrumb trail, showing the current entitiy's position in the heirarchy, and six tabs:
-
-**Summary:** Description of the selected entity.
-
-**Sensors:** Lists the attribute sensors that the entity has and their values.
-
-**Effectors:** Lists the effectors that can be invoked on the selected entity.
-
-**Activity:** Current and historic activity of the entity, currently running effectors, finished effectors.
-
-**Location:** The geographical location of the selected entity.
-
-**Policies:** Lists the policies associated with the current entity. Policies can be suspended, resumed and removed through the UI.
-
-### Security
-
-Security providers can be configured by specifying `brooklyn.webconsole.security.provider` equal 
-to the name of a class implementing `SecurityProvider`.
-An implementation of this could point to Spring, LDAP, OpenID or another identity management system.
-
-The default implementation, `ExplicitUsersSecurityProvider`, reads from a list of users and passwords
-which should be specified as configuration parameters e.g. in `brooklyn.properties`.
-This configuration could look like:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-The `users` line should contain a comma-separated list. The special value `*` is accepted to permit all users.
-
-To generate this, the brooklyn CLI can be used:
-{% highlight bash %}
-brooklyn generate-password --user admin
-
-Enter password: 
-Re-enter password: 
-
-Please add the following to your brooklyn.properies:
-
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.salt=OHDf
-brooklyn.webconsole.security.user.admin.sha256=91e16f94509fa8e3dd21c43d69cadfd7da6e7384051b18f168390fe378bb36f9
-{% endhighlight %}
-
-For legacy and dev purposes, the password can also be stored in plain text:
-
-{% highlight properties %}
-brooklyn.webconsole.security.users=admin
-brooklyn.webconsole.security.user.admin.password=mypassword
-{% endhighlight %}
-
-If not using the web console, you can specify
-`brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.BlackholeSecurityProvider` to prevent inadvertant logins.
-During dev/test you can specify `brooklyn.webconsole.security.provider=brooklyn.rest.security.provider.AnyoneSecurityProvider`
-to allow logins with no credentials. 
-
-To enable https, you will need a server certificate in a java keystore. To create a self-signed certificate, you can use the
-following command:
-
-`keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048`
-
-You will then be prompted to enter you name and organization details. This will create a keystore with the password `mypassword`
-- you should use your own secure password, which will be the same password used in your brooklyn.properties (below). 
-You will also need to replace `<path-to-keystore-directory>` with the full path of the folder where you wish to store your
-keystore. 
-
-The certificate generated will be a self-signed certificate and will not have a CN field identifying the website server 
-name, which will cause a warning to be displayed by the browser when viewing the page. For production servers, a valid signed 
-certificate from a trusted certifying authority should be used instead
-
-To enable HTTPS in Brooklyn, add the following to your brooklyn.properties:
-
-```
-# HTTPS
-brooklyn.webconsole.security.https.required=true
-brooklyn.webconsole.security.keystore.url=<path-to-keystore-directory>/server.key
-brooklyn.webconsole.security.keystore.password=mypassword
-brooklyn.webconsole.security.keystore.certificate.alias=brooklyn
-```
-
-In order to access the Brooklyn console, you will also need to enable security, and setup a user as described above
-
-Other Ways to Observe Activity
-------------------------------
-
-### Java API
-
-``ManagementContext`` provides a Java programmatic API. 
-
-More information can be found in the javadoc for ``ManagementContext``.
-
-### Command-line Console
-
-*Not available yet.*
-
-### Management REST API
-
-Brooklyn does not yet expose a REST API. This was to allow the APi to be designed to align with emerging standards.
-
-Selected management operations are possible remotely using links exposed by the GUI (after authenticating with the GUI).
-
-### Logging
-
-Brooklyn uses the SLF4J logging facade,  which allows use of many popular frameworks including java.util.logging, log4j, and logback.
-
-The convention for log levels is as follows:
-* ERROR and above:  exceptional situations which indicate that something has unexpectedly failed or
-some other problem has occured which the user is expected to attend to
-* WARN:  exceptional situations which the user may which to know about but which do not necessarily indicate failure or require a response
-* INFO:  a synopsis of activity, but which should not generate large volumes of events nor overwhelm a human observer
-* DEBUG and lower:  detail of activity which is not normally of interest, but which might merit closer inspection under certain circumstances.
-
-Loggers follow the ``package.ClassName`` naming standard.  
-
-It is possible for entities to emit logging activity sensors so that an operator can observe what is occurring within their application through the web console or via programmatic means.
-
-Examples for testing can be found in some of the poms.
-
-
-<!---
-
-<a name="distributed-management"></a>
-Distributed Management
-----------------------
-
-TODO Describe how and when objects become "live", pushed out to other nodes.
--->
-
-<!---
-
-<a name="resilience"></a>
-Resilience
-----------
-TODO
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
--->
-
-
-Key APIs
---------
-<!---
-TODO - brief overview of key APIs
--->
-*This section still needs to be written. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-- ``ManagementContext`` (Java management API)
-- ``EntityLocal`` (used by policies)
-
-
-<!---
-TODO - describe how to simply configure logging slf4j
--->
-
-Sensors and Effectors
----------------------
-
-### Sensors
-
-Sensors are typically defined as static named fields on the Entity subclass. These define the channels of events and activity that interested parties can track remotely. For example:
-{% highlight java %}
-/** a sensor for saying hi (illustrative), carrying a String value 
-	which is typically the name of the person to whom we are saying hi */
-public static final Sensor<String> HELLO_SENSOR = ...
-
-{% endhighlight %}
-
-If the entity is local (e.g. to a policy) these can be looked up using ``get(Sensor)``. If it may be remote, you can subscribe to it through various APIs.
-
-<!---
-TODO probably say about events now, quick reference about SubscriptionManager (either here or in next section on management context)
-TODO remaining section on Sensors perhaps should be moved to Writing Entities section? as reader won't need to know too much detail of sensor types to understand policies... though perhaps saying some is right. (Talking about JSON is almost certainly overkill...)
--->
-
-Sensors are used by operators and policies to monitor health and know when to invoke the effectors. The sensor data forms a nested map (i.e. JSON), which can be subscribed to through the ``ManagementContext``.
-
-Often ``Policy`` instances will subscribe to sensor events on their associated entity or its children; these events might be an ``AttributeValueEvent`` – an attribute value being reported on change or periodically – or something transient such as ``LogMessage`` or a custom ``Event`` such as "TOO_HOT".
-
-<!---
-TODO check classes above; is this much detail needed here?
--->
-
-Sensor values form a map-of-maps. An example of some simple sensor information is shown below in JSON:
-		
-	{
-	  config : {
-		url : "jdbc:mysql://ec2-50-17-19-65.compute-1.amazonaws.com:3306/mysql"
-		status : "running"
-	  }
-	  workrate : {
-		msgsPerSec : 432
-	  }
-	}
-
-Sensor values are defined as statics, which can be used to programmatically drive the subscription.
-<!---
-TODO , etc., example
--->
-
-### SubscriptionManager
-
-*This section is not complete. Feel free to [fork]({{site.path.guide}}/dev/code) the docs and lend a hand.*
-
-*See the* ``SubscriptionManager`` *class.*
-<!---
-TODO
--->
-
-### Effectors
-
-Like sensors and config info, effectors are also static fields on the Entity class. These describe actions available on the entity, similar to methods. Their implementation includes details of how to invoke them, typically this is done by calling a method on the entity. Effectors are typically defined as follows:
-
-{% highlight java %}
-/** an effector which returns no value,
-	but which causes the entity to emit a HELLO sensor event */
-public static Effector<Void> SAY_HI = ...
-
-{% endhighlight %}
-
-Effectors are invoked by calling ``invoke(SAY_HI, name:"Bob")`` or similar. The method may take an entity if context is not clear, and it takes parameters as named parameters or a Map.
-
-Invocation returns a ``Task`` object (extending ``Future``). This allows the caller to understand progress and errors on the task, as well as ``Task.get()`` the return value. Be aware that ``task.get()`` is a blocking function that will wait until a value is available before returning.
-
-The management framework ensures that execution occurs on the machine where the ``Entity`` is mastered, with progress, result, and/or any errors reported back to the caller. It does this through the ``ExecutionManager`` which, where necessary, creates proxy ``Task`` instances. The ``ExecutionManager`` associates ``Tasks`` with the corresponding ``Entity`` so that these can be tracked externally (and relocated if the Entity is remastered to a different location).
-
-It is worth noting that where a method corresponds to an effector, direct invocation of that method on an ``Entity`` will implicitly generate the ``Task`` object as though the effector had been invoked. For example, invoking ``Cluster.resize(int)``, where ``resize`` provides an ``Effector RESIZE``, will generate a ``Task`` which can be observed remotely.
-
-### ExecutionManager
-
-The ``ExecutionManager`` is responsible for tracking simultaneous executing tasks and associating these with given **tags**.
-Arbitrary tasks can be run by calling ``Task submit(Runnable)`` (similarly to the standard ``Executor``, although it also supports ``Callable`` arguments including Groovy closures, and can even be passed ``Task`` instances which have not been started). ``submit`` also accepts a few other named parameters, including ``description``, which allow additional metadata to be kept on the ``Task``. The main benefit then is to have rich metadata for executing tasks, which can be inspected through methods on the ``Task`` interface.
-
-By using the ``tag`` or ``tags`` named parameters on ``submit`` (or setting ``tags`` in a ``Task`` that is submitted), execution can be associated with various categories. This allows easy viewing can be examined by calling
-``ExecutionManager.getTasksWithTag(...)``.
-
-The following example uses Groovy, with time delays abused for readability. brooklyn's test cases check this using mutexes, which is recommended.
-	
-	ExecutionManager em = []
-	em.submit(tag:"a", description:"One Mississippi", { Thread.sleep(1000) })
-	em.submit(tags:["a","b"], description:"Two Mississippi", { Thread.sleep(1000) })
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> !t.isDone() }
-	Thread.sleep(1500)
-	assert em.getTasksWithTag("a").size()==2
-	assert em.getTasksWithTag("a").every { Task t -> t.isDone() }
-
-It is possible to define ParallelTasks and SequentialTasks and to specify inter-task relationships with TaskPreprocessors. This allows building quite sophisticated workflows relatively easily. 
-
-Continuing the example above, submitting a SequentialTasks or specifying ``em.setTaskPreprocessorForTag("a", SingleThreadedExecution.class)`` will cause ``Two Mississippi`` to run after ``One Mississippi`` completes.
-
-For more information consult the javadoc on these classes and associated tests.
-
-Note that it is currently necessary to prune dead tasks, either periodically or by the caller. By default they are kept around for reference. It is expected that an enhancement in a future release will allow pruning completed and failed tasks after a specified amount of time.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png b/docs/guide/ops/webconsole/webconsole-dashboard-w400.png
deleted file mode 100644
index 6364dc5..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-dashboard-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/webconsole/webconsole-dashboard.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-dashboard.png b/docs/guide/ops/webconsole/webconsole-dashboard.png
deleted file mode 100644
index cac5567..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-dashboard.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/webconsole/webconsole-detail-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail-w400.png b/docs/guide/ops/webconsole/webconsole-detail-w400.png
deleted file mode 100644
index b372e55..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-detail-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/ops/webconsole/webconsole-detail.png
----------------------------------------------------------------------
diff --git a/docs/guide/ops/webconsole/webconsole-detail.png b/docs/guide/ops/webconsole/webconsole-detail.png
deleted file mode 100644
index 17829cd..0000000
Binary files a/docs/guide/ops/webconsole/webconsole-detail.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/_my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/docs/guide/start/_my-web-cluster.yaml b/docs/guide/start/_my-web-cluster.yaml
index 3b6134b..166c497 100644
--- a/docs/guide/start/_my-web-cluster.yaml
+++ b/docs/guide/start/_my-web-cluster.yaml
@@ -1,18 +1,20 @@
 name: My Web Cluster
-location: location
+
+location: localhost
+
 services:
 
-- serviceType: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+- type: brooklyn.entity.webapp.ControlledDynamicWebAppCluster
   name: My Web
   brooklyn.config:
-    wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/{{ site.data.brooklyn.version }}/brooklyn-example-hello-world-sql-webapp-{{ site.data.brooklyn.version }}.war
+    wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
     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
+- type: brooklyn.entity.database.mysql.MySqlNode
   id: db
   name: My DB
   brooklyn.config:

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints.md b/docs/guide/start/blueprints.md
index c6c0bc3..d50cd94 100644
--- a/docs/guide/start/blueprints.md
+++ b/docs/guide/start/blueprints.md
@@ -1,57 +1,63 @@
 ---
-title: Launching Applications
-title_in_menu: Launching Applications
-layout: guide-normal
+title: Deploying Blueprints
+layout: website-normal
 menu_parent: index.md
+children:
+- { section: Launching from a Blueprint, title: Blueprint } 
+- { section: Launching from the Catalog, title: Catalog } 
 ---
 
 {% include fields.md %}
 
-### Launching from the Catalog
 
+## Launching from a Blueprint
 
-Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
+We'll start by deploying an application from a YAML blueprint.
 
-Now when we open the web console, two applications are displayed from the catalog.
+![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-application-modal-yaml.png)
 
-Select the 'Demo Web Cluster with DB' and click 'Next'.
+Copy the blueprint below into the large text box on the YAML tab. 
+But *before* you submit it, we need to make a modification.
 
-[![Viewing Catalog entries in Add Application dialog.](images/add-application-catalog-web-cluster-with-db.png)](add-application-catalog-web-cluster-with-db-large.png)
+{% highlight yaml %}
+{% readj _my-web-cluster.yaml %}
+{% endhighlight %}
 
-Select the Location that Brooklyn should deploy to, and name your application then click 'Finish' to launch the application as before.
+Find the line near the top of the blueprint that starts `location:`. 
+Change this to have the right values for your preferred target; for example: 
 
-## Launching from a blueprint
+{% highlight yaml %}
+location:
+  jclouds:aws-ec2:
+    identity: ABCDEFGHIJKLMNOPQRST
+    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
 
-There are several ways to deploy a YAML blueprint (including specifying the blueprint on the command line or submitting it via the REST API).
+(Alternatively, if you have `ssh localhost` [configured](../ops/locations/#localhost) you can leave it as is.
+See [Locations](../ops/locations) in the Operations section of the User Guide for detail on setting up 
+cloud providers, including putting credentials in a file on disk rather than in the blueprint.)
 
-For now, we will simply copy-and-paste the raw YAML blueprint into the web console.
+With the modified YAML in the dialog, click "Finish". The dialog will close and Brooklyn will begin deploying your
+application. Your application will be shown as "Starting" on the web console's front page.
 
-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.
 
-![Brooklyn web console, showing the YAML tab of the Add Application dialog.](images/add-application-modal-yaml.png)
+### Launching from the Catalog
 
-Copy this document into the large text box on the YAML tab, labelled `Enter CAMP Plan YAML code here`. But *before* you
-submit it, we need to make a modification.
+Instead of pasting the YAML blueprint each time,
+this blueprint can be [added to the catalog](../ops/catalog/).
+Or, even easier, you can download a sample [catalog.xml](catalog.xml).
+Install this to your `~/.brooklyn/` folder and relaunch Brooklyn
+(navigating to the "Help" tab in order to shutdown Brooklyn *and* the application you launched in the previous step).
 
-{% highlight yaml %}
-{% readj _my-web-cluster.yaml %}
-{% endhighlight %}
+Now when the web console is re-opened, the catalog contains our blueprints.
+Select the "Demo Web Cluster with DB" and click "Next".
 
-Find the line near the top of the blueprint that starts `location:`. Change the line to name a location. For example,
-one of these lines:
-
-{% highlight yaml %}
-location: aws-ec2:us-east-1
-location: rackspace-cloudservers-us:ORD
-location: google-compute-engine:europe-west1-a
-location: localhost
-{% endhighlight %}
+[![Viewing Catalog entries in Add Application dialog.](images/add-application-catalog-web-cluster-with-db.png)](images/add-application-catalog-web-cluster-with-db-large.png)
 
-**My Web Cluster Blueprint**
+Select the location to use, give your application a name, and then click "Finish".
 
-With the modified YAML in the dialog, click 'Finish'. The dialog will close and Brooklyn will begin deploying your
-application. Your application will be shown as 'Starting' on the web console's front page.
 
-### Next 
+## 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!
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider, 
+but this just the beginning.  **[Start managing this application.](managing.html)**

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/config.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/config.md b/docs/guide/start/config.md
deleted file mode 100644
index 016834d..0000000
--- a/docs/guide/start/config.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: Configuring Brooklyn
-title_in_menu: Configuring Brooklyn
-layout: guide-normal
-menu_parent: index.md
----
-
-Brooklyn reads startup configuration from a file `~/.brooklyn/brooklyn.properties`, by default.
-You can create this from a template [brooklyn.properties]({{brooklyn_properties_url_path}}) file which you edit.
-
-## Configuring Security
-
-To configure Brooklyn to run on a public IP address, security should be enabled.
-The simplest way is to define a user and password in `~/.brooklyn/brooklyn.properties`
-(described above): 
-
-    brooklyn.webconsole.security.users=admin
-    brooklyn.webconsole.security.user.admin.password=s3cr3t
-
-Other modes, including LDAP, are described in this file.
-
-The other common setting is to run under https (on port 8443 by default):
-
-    brooklyn.webconsole.security.https.required=true
-
-## Configuring a Location
-
-Brooklyn deploys applications to locations. These locations
-can be clouds, machines with fixed IPs or localhost (for testing).
-Their configuration can be specified in `~/.brooklyn/brooklyn.properties` (described above),
-and then these locations can be easily selected within Brooklyn.
-Alternatively this information can be specified in the YAML when applications are deployed,
-without needing to set it in `brooklyn.properties`.
-
-Some sample settings for this are:
-
-    brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
-    brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
-    brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
-    brooklyn.location.named.aws-california.displayName = AWS US West 1 (CA)
-
-    brooklyn.location.jclouds.softlayer.identity = username
-    brooklyn.location.jclouds.softlayer.credential = <private-key-hex-digits>
-    brooklyn.location.named.softlayer-dal05 = jclouds:softlayer:dal05
-    brooklyn.location.named.softlayer-dal05.displayName = Softlayer Dallas
-
-If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/ops/locations/) 
-to ensure that your Brooklyn can access your machine.
-
-Once updated, restart Brooklyn (or reload the properties within the web GUI).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.md b/docs/guide/start/index.md
index 4967dd7..41ab28b 100644
--- a/docs/guide/start/index.md
+++ b/docs/guide/start/index.md
@@ -1,10 +1,9 @@
 ---
-layout: guide-normal
+layout: website-normal
 title: Getting Started
 menu_parent: ../index.md
 children:
 - running.md
-- config.md
 - blueprints.md
 - managing.md
 - policies.md

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/managing.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/managing.md b/docs/guide/start/managing.md
index 44645f7..e01edbf 100644
--- a/docs/guide/start/managing.md
+++ b/docs/guide/start/managing.md
@@ -1,7 +1,7 @@
 ---
 title: Monitoring and Managing Applications
 title_in_menu: Monitoring and Managing Applications
-layout: guide-normal
+layout: website-normal
 menu_parent: index.md
 ---
 
@@ -17,24 +17,40 @@ We can explore the management hierarchy of the application, which will show us t
 
 
 
-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.
+Clicking on the "My Web" entity will show the "Summary" tab,
+giving a very high level of what that component is doing. 
 
 ![Exploring My Web.](images/my-web.png)
 
 
-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.
+## Sensors
 
-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.
+Now click on the "Sensors" tab:
+these data feeds drive the real-time picture of the application.
+As you navigate in the tree at the left, you can see more targeted statistics coming in in real-time.
+
+Explore the sensors and the tree to find a URL where the webapp we just deployed is running
+and open that in a new tab. Quickly return to the "Sensors" tab and observe the requests-per-second sensor increase.  
+
+
+## Activities
+
+The Activity tab allows us to drill down into the 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.
 
 [![My DB Activities.](images/my-db-activities.png)](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.
+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.
 
 [![My DB Activities.](images/my-web-cluster-stop-confirm.png)](images/my-web-cluster-stop-confirm-large.png)
 
+
 ### Next
 
-Brooklyn's real power is in using [Policies](policies.html)  to automatically *manage* applications. 
+Brooklyn's real power is in using **[Policies](policies.html)**  to automatically *manage* applications. 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/policies.md b/docs/guide/start/policies.md
index 1b665df..31b6e27 100644
--- a/docs/guide/start/policies.md
+++ b/docs/guide/start/policies.md
@@ -1,7 +1,7 @@
 ---
 title: Getting Started - Policies
 title_in_menu: Policies
-layout: guide-normal
+layout: website-normal
 ---
 
 ### Exploring and Testing Policies
@@ -25,12 +25,27 @@ Sitting idle, this cluster will only contain one server, but you can use a tool
 
 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.
 
+
+### Under the Covers
+
+The `AutoScalerPolicy` here is configured to respond to the sensor
+reporting requests per second per node, invoking the default `resize` effector.
+By clicking on the policy, you can configure it to respond to a much lower threshhold
+or set long stabilization delays (the period before it scales out or back).
+
+An even simpler test is to manually suspend the policy, by clicking "Suspend" in the policies list.
+You can then switch to the "Effectors" tab and manually trigger a `resize`.
+On resize, new nodes are created and configured, 
+and in this case a policy on the nginx node reconfigures nginx whenever the set of active
+targets changes.
+
+
 ### Next
 
 This guide has given a quick overview to writing blueprints for applications, deploying applications, and
 managing them. Next, learn more about any of:
 
-* [Writing blueprints with YAML](../yaml/) 
-* [Writing blueprints with Java](../java/) 
+* [Writing Blueprints with YAML](../yaml/) 
+* [Writing Blueprints with Java](../java/) 
 * [Operating Brooklyn](../ops/) 
 

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/start/running.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/running.md b/docs/guide/start/running.md
index cb1cfe7..6de22c6 100644
--- a/docs/guide/start/running.md
+++ b/docs/guide/start/running.md
@@ -1,7 +1,7 @@
 ---
 title: Running Brooklyn
 title_in_menu: Running Brooklyn
-layout: guide-normal
+layout: website-normal
 menu_parent: index.md
 ---
 
@@ -21,84 +21,48 @@ Expand the `tar.gz` archive:
 
 {% if brooklyn_version contains 'SNAPSHOT' %}
 {% highlight bash %}
-$ tar -zxf brooklyn-dist-{{ site.data.brooklyn.version }}-timestamp-dist.tar.gz
+$ tar -zxf brooklyn-dist-{{ site.brooklyn-version }}-timestamp-dist.tar.gz
 {% endhighlight %}
 {% else %}
 {% highlight bash %}
-$ tar -zxf brooklyn-{{ site.data.brooklyn.version }}-dist.tar.gz
+$ tar -zxf brooklyn-{{ site.brooklyn-version }}-dist.tar.gz
 {% endhighlight %}
 {% endif %}
 
-This will create a `brooklyn-{{ site.data.brooklyn.version }}` folder.
-
-Note: You'll need a Java JRE or SDK installed (version 6 or later), as Brooklyn is Java under the covers.
-
-## Verify SSH
-
-Brooklyn uses SSH extensively and therefore it is worth making sure that you have a known working SSH setup before
-starting.
-
-Please check the following items:
-
-- If you are using Mac OSX, open System Preferences, go to the Sharing item, and enable 'Remote Login'.
-- You have two files named `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`.
-  - If these files do not exist, they can be created with `ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa`.
-- `~/.ssh/id_rsa` is NOT readable by any other user.
-  - You can verify this with `ls -l ~/.ssh/id_rsa` - the line should start with `-rw-------` or `-r--------`. If it
-    does not, execute `chmod 0600 ~/.ssh/id_rsa`.
-- The file `~/.ssh/authorized_keys` exists and contains a copy of your public key from `~/.ssh/id_rsa.pub`.
-  - Note that it is normal for it to contain other items as well.
-- The key in `~/.ssh/id_rsa` does *not* have a passphrase.
-  - You can test this by executing `ssh-keygen -y`. If it does *not* ask for a passphrase, then your key is OK.
-  - If your key does have a passphrase, remove it. You can do this by running `ssh-keygen -p`. Enter the passphrase,
-    then when prompted for the new passphrase, hit Enter.
-
-Now verify your setup by running the command: `ssh localhost echo hello world`
-
-If you see a message similar to this:
-
-<pre>
-The authenticity of host 'localhost (::1)' can't be established.
-RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
-Are you sure you want to continue connecting (yes/no)?
-</pre>
-
-then answer 'yes', and then repeat the command run again.
-
-If the response is `hello world`, with no other output or prompts, then your SSH setup is good and Brooklyn should be
-able to use it without a problem.
-
-If these steps are not working, [these instructions]({{ site.path.guide }}/ops/locations/) may be
-useful.
+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.
 
+**Node #2**: If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/ops/locations/#localhost) 
+to ensure that your Brooklyn can access your machine.
 
 
 ## Launch Brooklyn
 
-Let's setup some paths for easy commands.
-
-(Click the clipboard on these code snippets for easier c&p.)
+Now start Brooklyn with the following command:
 
 {% highlight bash %}
-$ cd brooklyn-{{ site.data.brooklyn.version }}
-$ BROOKLYN_DIR="$(pwd)"
-$ export PATH=$PATH:$BROOKLYN_DIR/bin/
-{% endhighlight %}
-
-We can do a quick test drive by launching Brooklyn:
-
-{% highlight bash %}
-$ brooklyn launch
+$ cd brooklyn-{{ site.brooklyn.version }}
+$ bin/brooklyn launch
 {% endhighlight %}
 
 Brooklyn will output the address of the management interface:
 
+<pre>
+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 []
+</pre>
 
-`INFO  Starting brooklyn web-console on loopback interface because no security config is set`
-
-`INFO  Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []`
 
 ### Next
 
-Now that Brooklyn is up and running we can look at getting it to manage some applications. 
+Next, open the web console on [127.0.0.1:8081](http://127.0.0.1:8081). 
+No application shave been deployed yet, so the "Create Application" dialog opens automatically:
+let's remedy this by **[deploying a blueprint](blueprints.html)**. 
+
+It is not necessary at this time, but depending on what you are going to do, 
+you may wish to set up other configuration options first:
+ 
+* [Security](../ops/brooklyn_properties.html)
+* [Persistence](../ops/persistence/)
+* [Cloud credentials](../ops/locations/)

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png
deleted file mode 100644
index c2b48ba..0000000
Binary files a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com-w400.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png b/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png
deleted file mode 100644
index 78eb5c8..0000000
Binary files a/docs/guide/yaml/brooklyn-flow-websequencediagrams.com.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/yaml/catalog-maintenance.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/catalog-maintenance.md b/docs/guide/yaml/catalog-maintenance.md
deleted file mode 100644
index d8eb877..0000000
--- a/docs/guide/yaml/catalog-maintenance.md
+++ /dev/null
@@ -1,115 +0,0 @@
----
-title: Catalog Maintenance
-layout: guide-normal
-toc: ../guide_toc.json
-categories: [use, guide, catalog-maintenance]
----
-
-In addition to deploying [YAML blueprints](creating-yaml.html) directly through the web console, it is possible
-to add YAML blueprints to the catalog via Brooklyn's REST API.
-
-The catalog is a collection of versioned blueprints, which can be deployed directly or referenced 
-by other blueprints.  Blueprints in the catalog can be deployed via the Brooklyn REST API, or from 
-the web-console's 'Catalog' section of the 'Create Application' dialog box.
-
-All YAML blueprints added to the catalog must also contain a `brooklyn.catalog` section. 
-
-For a blueprint to be accessible via the 'Create Application' dialog, it must be an Application 
-(i.e. the entity at the root of the blueprint must implement `brooklyn.entity.Application`).
-If just deploying via the REST API, then this is not necessary.
-
-<!--
-TODO: Add section that explains how to add plain entities to the catalog and use them either from the App Wizard,
-(and entity UI) or embed the catalog id + version in another YAML
--->
-
-Let's take the following YAML as a starting point.
-
-{% highlight yaml %}
-location: localhost
-
-name: MySQL Database
-services:
-- type: brooklyn.entity.database.mysql.MySqlNode
-  brooklyn.config:
-    datastore.creation.script.url: classpath://visitors-creation-script.sql
-{% endhighlight %}
-
-We will convert it for adding to the catalog, such that it will usable through the 
-'Create Application' dialog.
-
-The steps are therefore:
-
-* Add a brooklyn.catalog section to give metadata about the version etc. This is also used 
-  when displaying the blueprint in the 'Add Application' dialog.
-* Remove the explicit location (as the user will typically select the location in the GUI).
-* Add a root element that extends `brooklyn.entity.Application`. As we don't require any
-  custom application-specific logic, we can use the `brooklyn.entity.basic.BasicApplication` 
-  class. We can then add our MySqlNode as a child of the BasicApplication. 
-  (When deploying via YAML at the REST API, this is not necessary as Brooklyn will do this 
-  automatically).
-
-{% highlight yaml %}
-brooklyn.catalog:
-  id: MySQL
-  version: 1.0
-  iconUrl: classpath://mysql.png
-  description: MySql is an open source relational database management system (RDBMS)
-
-name: MySQL Database
-services:
-- type: brooklyn.entity.basic.BasicApplication
-  brooklyn.children:
-  - type: brooklyn.entity.database.mysql.MySqlNode
-    brooklyn.config:
-      datastore.creation.script.url: classpath://visitors-creation-script.sql
-{% endhighlight %}
-
-<!--
-TODO: Add documentation to explain that the brooklyn.catalog section can contain a libraries array, each item pointing to 
-an OSGi bundle where the code for the blueprint is hosted. Every type from the blueprint will be searched for in the 
-libraries first and then on the standard Brooklyn classpath.*
--->
-
-To explain the `brooklyn.catalog` section:
-
-- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item. This ID is also passed to 
-`UsageManager.UsageListener.onApplicationEvent` for metering purposes.
-- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
-being installed (in this case MySQL).
-- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide a graphic to be 
-displayed in the 'Add Application' dialog alongside the blueprint name. These image files should be placed in the 
-`conf` folder to make them available at runtime.
-- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the 
-'Add Application' dialog.
-
-To add the blueprint to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
-follows (substituting your own usename:password, URL and file path):
-
-{% highlight bash %}
-curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
-{% endhighlight %}
-
-This will add the blueprint to the catalog as shown here:
-[![MySQL in Brooklyn Catalog](mysql-in-catalog-w700.png "MySQL in Brooklyn Catalog")](mysql-in-catalog.png) 
-
-If you attempt to run the curl command a second time, you will receive an error stating `Updating existing catalog entries is forbidden`.
-To update the blueprint, you will need to change the version number in your yaml file before running the curl command 
-again. This will create a second blueprint. You can then delete the old version via the REST API, using its ID and version
-as follows:
-
-{% highlight bash %}
-curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
-{% endhighlight %}
-
-**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
-rebinding the catalog item is used to reconstruct the entity.
-
-<!--
-TODO: Add documentation about adding policies to the catalog, and explaining how to add items to 
-the UI using the plus icon on the catalog tab*
-
-TODO: describe entity addition (this just covers app addition)
-
-TODO: describe how to use the web-console GUI
--->

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/yaml/chef/about-chef.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/about-chef.md b/docs/guide/yaml/chef/about-chef.md
index 0c7dcd6..db3ec3c 100644
--- a/docs/guide/yaml/chef/about-chef.md
+++ b/docs/guide/yaml/chef/about-chef.md
@@ -1,7 +1,7 @@
 ---
 title: About Chef
 title_in_menu: About Chef
-layout: guide-normal
+layout: website-normal
 ---
 
 ## What you need to know about Chef

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ac204e2e/docs/guide/yaml/chef/advanced-chef-integration.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/chef/advanced-chef-integration.md b/docs/guide/yaml/chef/advanced-chef-integration.md
index 9a7cc67..0d65286 100644
--- a/docs/guide/yaml/chef/advanced-chef-integration.md
+++ b/docs/guide/yaml/chef/advanced-chef-integration.md
@@ -1,7 +1,7 @@
 ---
 title: Advanced Chef Integration
 title_in_menu: Advanced Chef Integration
-layout: guide-normal
+layout: website-normal
 ---
 
 ### Adding Sensors and Effectors
@@ -30,7 +30,7 @@ indicated earlier.  If you'd like to work with us to implement these, please let
 
 A general schema for the supported YAML is below: 
 
-```
+{% highlight yaml %}
 - type: chef:cookbook_name
   cookbook_urls:
     cookbook_name: url://for/cookbook.tgz
@@ -39,7 +39,7 @@ A general schema for the supported YAML is below:
   launch_attributes: # map of arguments to set in the chef node
   service_name: cookbook_service
   pid_file: /var/run/cookbook.pid
-```
+{% endhighlight %}
 
 If you are interested in exploring the Java code for creating blueprints,
 start with the `TypedToyMySqlEntiyChef` class, which essentially does what this tutorial has shown;


Mime
View raw message