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 2016/02/01 18:45:21 UTC
[13/51] [abbrv] [partial] brooklyn-docs git commit: move subdir from
incubator up a level as it is promoted to its own repo (first non-incubator
commit!)
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/migrate-to-0.8.0.md
----------------------------------------------------------------------
diff --git a/guide/misc/migrate-to-0.8.0.md b/guide/misc/migrate-to-0.8.0.md
new file mode 100644
index 0000000..f2b9770
--- /dev/null
+++ b/guide/misc/migrate-to-0.8.0.md
@@ -0,0 +1,32 @@
+---
+layout: website-normal
+title: Migrating to 0.8.0
+---
+
+As noted in the [release notes](release-notes.html),
+this version introduces major package renames.
+
+However migrating your code should not be hard:
+
+* For small Java projects, simply "Optimizing Imports" in your IDE should fix code issues.
+
+* For YAML blueprints and larger projects,
+a set of regexes has been prepared [here](migrate-to-0.8.0-regexes.sed)
+detailing all class renames.
+
+To download and apply this to an entire directory, you can use the following snippet.
+If running this on a Java project, you should enter the `src` directory
+or `rm -rf target` first. For other use cases it should be easy to adapt,
+noting the use of `sed` and the arguments (shown for OS X / BSD here).
+Do make a `git commit` or other backup before applying,
+to make it easy to inspect the changes.
+It may add a new line to any file which does not terminate with one,
+so do not run on binary files.
+
+{% highlight bash %}
+$ curl {{ site.url_root }}{{ site.path.guide }}/misc/migrate-to-0.8.0-regexes.sed -o /tmp/migrate.sed
+$ for x in `find . -type file` ; do sed -E -i .bak -f /tmp/migrate.sed $x ; done
+$ find . -name "*.bak" -delete
+{% endhighlight %}
+
+If you encounter any issues, please [contact us](/community/).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/misc/release-notes.md
----------------------------------------------------------------------
diff --git a/guide/misc/release-notes.md b/guide/misc/release-notes.md
new file mode 100644
index 0000000..ef79155
--- /dev/null
+++ b/guide/misc/release-notes.md
@@ -0,0 +1,72 @@
+---
+layout: website-normal
+title: Release Notes
+---
+
+## Version {{ site.brooklyn-version }}
+
+{% if SNAPSHOT %}
+**You are viewing a SNAPSHOT release (master branch), so this list is in progress!**
+{% endif %}
+
+* Introduction
+* New Features
+* Backwards Compatibility
+
+
+### Introduction
+
+Version 0.9.0 is [TODO add description]
+
+Thanks go to our community for their improvements, feedback and guidance, and
+to Brooklyn's commercial users for funding much of this development.
+
+
+### New Features
+
+1. Parameters (config keys) can now be defined in YAML, using `brooklyn.parameters`.
+This allows YAML entities to advertise how they should be parameterized,
+for use in the UI and in documentation tools, and do coercion on these values.
+For a good demonstration, see the "Custom Entities" section of the YAML chapter of the user guide.
+
+[ TODO -
+restructuring and graduation;
+the `br` client CLI tool;
+test framework;
+`$brooklyn:external(...)` extension for taking values from other sources is supported in more places;
+better YAML editor in the UI;
+OSGi-native mode using Karaf, to simplify packaging of blueprints;
+a new pure-java WinRM client (winrm4j), hugely reducing the number of dependencies and distro size;
+several version bumps (jclouds) and performance and reliability improvements
+]
+
+
+### Backwards Compatibility
+
+Changes since 0.8.0-incubating:
+
+1. **Major:** The classes HttpTool and HttpToolResponse in brooklyn-core (package org.apache.brooklyn.util.core.http)
+have been moved to brooklyn-utils-common, in package org.apache.brooklyn.util.
+Classes such as HttpFeed that previously returned org.apache.brooklyn.util.core.http.HttpToolResponse in some methods now
+return org.apache.brooklyn.util.HttpToolResponse.
+
+2. **Major:** Locations set in YAML or on a spec are no longer passed to `child.start(...)` by `AbstractApplication`;
+this has no effect in most cases as `SoftwareProcess.start` looks at local and inherited locations, but in ambiguous cases
+it means that locally defined locations are now preferred. Other classes of entities may need to do similar behaviour,
+and it means that calls to `Entity.getLocations()` in some cases will not show parent locations,
+unless discovered and set locally e.g. `start()`. The new method `Entities.getAllInheritedLocations(Entity)`
+can be used to traverse the hierarchy. It also means that when a type in the registry (catalog) includes a location,
+and a caller references it, that location will now take priority over a location defined in a parent.
+Additionally, any locations specified in YAML extending the registered type will now *replace* locations on the referenced type;
+this means in many cases an explicit `locations: []` when extending a type will cause locations to be taken from the
+parent or application root in YAML. Related to this, tags from referencing specs now preceed tags in the referenced types,
+and the referencing catalog item ID also takes priority; this has no effect in most cases, but if you have a chain of
+referenced types blueprint plan source code and the catalog item ID are now set correctly.
+
+3. Task cancellation is now propagated to dependent submitted tasks, including backgrounded tasks if they are transient.
+Previously when a task was cancelled the API did not guarantee semantics but the behaviour was to cancel sub-tasks only
+in very limited cases. Now the semantics are more precise and controllable, and more sub-tasks are cancelled.
+This can prevent some leaked waits on `attributeWhenReady`.
+
+For changes in prior versions, please refer to the release notes for
+[0.8.0](/v/0.8.0-incubating/misc/release-notes.html).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/brooklyn_properties.md
----------------------------------------------------------------------
diff --git a/guide/ops/brooklyn_properties.md b/guide/ops/brooklyn_properties.md
new file mode 100644
index 0000000..e8335f1
--- /dev/null
+++ b/guide/ops/brooklyn_properties.md
@@ -0,0 +1,236 @@
+---
+title: brooklyn.properties
+layout: website-normal
+children:
+- { section: Quick Setup }
+- { section: Locations }
+- { section: Java }
+- { section: Authentication }
+- { section: Entitlements }
+- { section: HTTPS Configuration }
+---
+
+{% include fields.md %}
+
+The file `~/.brooklyn/brooklyn.properties` is read when Brooklyn starts
+to load server configuration values.
+A different properties file can be specified either additionally or instead
+through [CLI options](launch.html#configuration-files).
+
+A template [brooklyn.properties]({{brooklyn_properties_url_path}}) file is available,
+with abundant comments.
+
+
+## Quick Setup
+
+The most common properties set in this file are for access control.
+Without this, Brooklyn will bind only to localhost or will create a random
+password written to the log for use on other networks.
+The simplest way to specify users and passwords is:
+
+{% highlight properties %}
+brooklyn.webconsole.security.users=admin,bob
+brooklyn.webconsole.security.user.admin.password=AdminPassw0rd
+brooklyn.webconsole.security.user.bob.password=BobPassw0rd
+{% endhighlight %}
+
+The properties file *must* have permissions 600
+(i.e. readable and writable only by the file's owner),
+for some security.
+
+In many cases, it is preferable instead to use an external credentials store such as LDAP
+or at least to have passwords in this file.
+Information on configuring these is [below](#authentication).
+
+If coming over a network it is highly recommended additionally to use `https`.
+This can be configured with:
+
+{% highlight properties %}
+brooklyn.webconsole.security.https.required=true
+{% endhighlight %}
+
+More information, including setting up a certificate, is described [further below](#https-configuration).
+
+
+## Camp YAML Expressions
+
+Values in `brooklyn.properties` can use the Camp YAML syntax. Any value starting `$brooklyn:` is
+parsed as a Camp YAML expression.
+
+This allows [externalized configuration](externalized-configuration.html) to be used from
+brooklyn.properties. For example:
+
+{% highlight properties %}
+brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("vault", "aws-identity")
+brooklyn.location.jclouds.aws-ec2.credential=$brooklyn:external("vault", "aws-credential")
+{% endhighlight %}
+
+If for some reason one requires a literal value that really does start with `$brooklyn:` (i.e.
+for the value to not be parsed), then this can be achieved by using the syntax below. This
+example returns the property value `$brooklyn:myexample`:
+
+{% highlight properties %}
+example.property=$brooklyn:literal("$brooklyn:myexample")
+{% endhighlight %}
+
+
+## Locations
+
+Information on defining locations in the `brooklyn.properties` file is available [here](locations/).
+
+
+## Java
+
+Arbitrary data can be set in the `brooklyn.properties`.
+This can be accessed in java using `ManagementContext.getConfig(KEY)`.
+
+
+## Authentication
+
+**Security Providers** are the mechanism by which different authentication authorities are plugged in to Brooklyn.
+These 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 %}
+
+Alternatively, in dev/test environments where a lower level of security is required,
+the syntax `brooklyn.webconsole.security.user.<username>=<password>` can be used for
+each `<username>` specified in the `brooklyn.webconsole.security.users` list.
+
+Other security providers available include:
+
+### No one
+
+`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.BlackholeSecurityProvider`
+will block all logins (e.g. if not using the web console)
+
+### No security
+
+`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.AnyoneSecurityProvider`
+will allow logins with no credentials (e.g. in secure dev/test environments)
+
+### LDAP
+
+`brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider`
+will cause Brooklyn to call to an LDAP server to authenticate users;
+The other things you need to set in `brooklyn.properties` are:
+
+* `brooklyn.webconsole.security.ldap.url` - ldap connection url
+* `brooklyn.webconsole.security.ldap.realm` - ldap dc parameter (domain)
+* `brooklyn.webconsole.security.ldap.ou` *optional, by default it set to Users* - ldap ou parameter
+
+**brooklyn.properties example configuration:**
+
+```
+brooklyn.webconsole.security.provider=org.apache.brooklyn.rest.security.provider.LdapSecurityProvider
+brooklyn.webconsole.security.ldap.url=ldap://localhost:10389/????X-BIND-USER=uid=admin%2cou=system,X-BIND-PASSWORD=secret,X-COUNT-LIMIT=1000
+brooklyn.webconsole.security.ldap.realm=example.com
+```
+
+After you setup the brooklyn connection to your LDAP server, you can authenticate in brooklyn using your cn (e.g. John Smith) and your password.
+`org.apache.brooklyn.rest.security.provider.LdapSecurityProvider` searches in the LDAP tree in LDAP://cn=John Smith,ou=Users,dc=example,dc=com
+
+If you want to customize the ldap path or something else which is particular to your LDAP setup you can extend `LdapSecurityProvider` class or implement from scratch the `SecurityProvider` interface.
+
+## Entitlements
+
+In addition to login access, fine-grained permissions -- including
+seeing entities, creating applications, seeing sensors, and invoking effectors --
+can be defined on a per-user *and* per-target (e.g. which entity/effector) basis
+using a plug-in **Entitlement Manager**.
+
+This can be set globally with the property:
+
+{% highlight properties %}
+brooklyn.entitlements.global=<class>
+{% endhighlight %}
+
+The default entitlement manager is one which responds to per-user entitlement rules,
+and understands:
+
+* `root`: full access, including to the Groovy console
+* `readonly`: read-only access to almost all information
+* `minimal`: access only to server stats, for use by monitoring systems
+
+These keywords are also understood at the `global` level, so to grant full access to `admin`
+but limited access to other authenticated users and `readonly,
+you can write:
+
+{% highlight properties %}
+brooklyn.entitlements.global=readonly
+brooklyn.entitlements.perUser.admin=root
+brooklyn.entitlements.perUser.support=readonly
+brooklyn.entitlements.perUser.metrics=minimal
+{% endhighlight %}
+
+Under the covers this invokes the `PerUserEntitlementManager`,
+with a `default` set (and if not specified `default` defaults to `minimal`);
+so the above can equivalently be written:
+
+{% highlight properties %}
+brooklyn.entitlements.global=org.apache.brooklyn.core.mgmt.entitlement.PerUserEntitlementManager
+brooklyn.entitlements.perUser.default=readonly
+brooklyn.entitlements.perUser.admin=root
+brooklyn.entitlements.perUser.support=readonly
+brooklyn.entitlements.perUser.metrics=minimal
+{% endhighlight %}
+
+For more information, see
+[Java: Entitlements]({{ site.path.guide }}/java/entitlements.html).
+or
+{% include java_link.html class_name="EntitlementManager" package_path="org/apache/brooklyn/api/mgmt/entitlement" project_subpath="api" %}.
+
+
+
+## HTTPS Configuration
+
+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:
+
+{% highlight bash %}
+% keytool -genkey -keyalg RSA -alias brooklyn -keystore <path-to-keystore-directory>/server.key -storepass mypassword -validity 360 -keysize 2048
+{% endhighlight %}
+
+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:
+
+{% highlight properties %}
+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
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/catalog/images/add-to-catalog.png
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/images/add-to-catalog.png b/guide/ops/catalog/images/add-to-catalog.png
new file mode 100644
index 0000000..0565e7e
Binary files /dev/null and b/guide/ops/catalog/images/add-to-catalog.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/catalog/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/index.md b/guide/ops/catalog/index.md
new file mode 100644
index 0000000..700b24f
--- /dev/null
+++ b/guide/ops/catalog/index.md
@@ -0,0 +1,325 @@
+---
+title: Catalog
+layout: website-normal
+children:
+- { section: General YAML Schema }
+- { section: Catalog Metadata }
+- { section: Catalog YAML Examples }
+- { section: Templates and the Add-Application Wizard, title: Templates }
+- { section: Adding to the Catalog, title: Adding and Deleting }
+- { section: Versioning }
+- { section: CLI Options }
+
+---
+
+Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints and other resources.
+Blueprints in the catalog can be deployed directly, via the Brooklyn REST API or the web console,
+or referenced in other blueprints using their `id`.
+
+
+### Catalog Items YAML Syntax
+
+An item or items to be added to the catalog is defined by a YAML file,
+specifying the catalog metadata for the items and the actual blueprint or resource definition.
+
+
+#### General YAML Schema
+
+A single catalog item can be defined following this general structure:
+
+~~~ yaml
+brooklyn.catalog:
+ <catalog-metadata>
+ item:
+ <blueprint-or-resource-definition>
+~~~
+
+
+To define multiple catalog items in a single YAML,
+where they may share some metadata,
+use the following structure:
+
+~~~ yaml
+brooklyn.catalog:
+ <catalog-metadata>
+ items:
+ - <additional-catalog-metadata>
+ item:
+ <blueprint-or-resource-definition>
+ - <additional-catalog-metadata>
+ item:
+ <blueprint-or-resource-definition>
+~~~
+
+
+#### Catalog Metadata
+
+Catalog metadata fields supply the additional information required In order to register an item in the catalog.
+These fields can be supplied as `key: value` entries
+where either the `<catalog-metadata>` or `<additional-catalog-metadata>` placeholders are,
+with the latter overriding the former unless otherwise specfied below.
+
+The following metadata is *required* for all items:
+
+- `id`: a human-friendly unique identifier for how this catalog item will be referenced from blueprints
+- `version`: multiple versions of a blueprint can be installed and used simultaneously;
+ this field disambiguates between blueprints of the same `id`.
+ Note that this is typically *not* the version of the software being installed,
+ but rather the version of the blueprint. For more information on versioning, see below.
+ (Also note YAML treats numbers differently to Strings. Explicit quotes may sometimes be required.)
+
+To reference a catalog item in another blueprint, simply reference its ID and optionally its version number.
+For instance, if we've added an item with metadata `{ id: datastore, version: "1.0" }` (such as the example below),
+we could refer to it in another blueprint with:
+
+~~~ yaml
+services:
+- type: datastore:1.0
+~~~
+
+In addition to the above fields, exactly **one** of the following is also required:
+
+- `item`: the YAML for a service or policy or location specification
+ (a map containing `type` and optional `brooklyn.config`)
+ or a full application blueprint (in the usual YAML format) for a template; **or*
+- `items`: a list of catalog items, where each entry in the map follows the same schema as
+ the `brooklyn.catalog` value, and the keys in these map override any metadata specified as
+ a sibling of this `items` key (or, in the case of `brooklyn.libraries` they add to the list);
+ if there are references between items, then order is important,
+ `items` are processed in order, depth-first, and forward references are not supported.
+
+The following optional catalog metadata is supported:
+
+- `itemType`: the type of the item being defined.
+ When adding a template (see below) this must be set.
+ In most other cases this can be omitted and type type will be inferred.
+ The supported item types are:
+ - `entity`
+ - `template`
+ - `policy`
+ - `location`
+- `name`: a nicely formatted display name for the item, used when presenting it in a GUI
+- `description`: supplies an extended textual description for the item
+- `iconUrl`: points to an icon for the item, used when presenting it in a GUI.
+ The URL prefix `classpath` is supported but these URLs may *not* refer items in any OSGi bundle in the `brooklyn.libraries` section
+ (to prevent requiring all OSGi bundles to be loaded at launch).
+ Icons are instead typically installed either at the server from which the OSGi bundles or catalog items are supplied
+ or in the `conf` folder of the Brooklyn distro.
+- `scanJavaAnnotations` [experimental]: if provided (as `true`), this will scan any locally provided
+ library URLs for types annotated `@Catalog` and extract metadata to include them as catalog items.
+ If no libraries are specified this will scan the default classpath.
+ This feature is experimental and may change or be removed.
+ Also note that external OSGi dependencies are not supported
+ and other metadata (such as versions, etc) may not be applied.
+- `brooklyn.libraries`: a list of pointers to OSGi bundles required for the catalog item.
+ This can be omitted if blueprints are pure YAML and everything required is included in the classpath and catalog.
+ Where custom Java code or bundled resources is needed, however, OSGi JARs supply
+ a convenient packaging format and a very powerful versioning format.
+ Libraries should be supplied in the form
+ `brooklyn.libraries: [ "http://...", "http://..." ]`,
+ or as
+ `brooklyn.libraries: [ { name: symbolic-name, version: 1.0, url: http://... }, ... ]` if `symbolic-name:1.0`
+ might already be installed from a different URL and you want to skip the download.
+ Note that these URLs should point at immutable OSGi bundles;
+ if the contents at any of these URLs changes, the behaviour of the blueprint may change
+ whenever a bundle is reloaded in a Brooklyn server,
+ and if entities have been deployed against that version, their behavior may change in subtle or potentially incompatible ways.
+ To avoid this situation, it is highly recommended to use OSGi version stamps as part of the URL.
+
+
+#### Catalog YAML Examples
+
+##### A Simple Example
+
+The following example installs the `RiakNode` entity, making it also available as an application template,
+with a nice display name, description, and icon.
+It can be referred in other blueprints to as `datastore:1.0`,
+and its implementation will be the Java class `org.apache.brooklyn.entity.nosql.riak.RiakNode` included with Brooklyn.
+
+~~~ yaml
+brooklyn.catalog:
+ id: datastore
+ version: 1.0
+ itemType: template
+ iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
+ name: Datastore (Riak)
+ description: Riak is an open-source NoSQL key-value data store.
+ item:
+ type: org.apache.brooklyn.entity.nosql.riak.RiakNode
+ name: Riak Node
+~~~
+
+
+##### Multiple Items
+
+This YAML will install three items:
+
+~~~ yaml
+brooklyn.catalog:
+ version: 1.1
+ iconUrl: classpath://org/apache/brooklyn/entity/nosql/riak/riak.png
+ description: Riak is an open-source NoSQL key-value data store.
+ items:
+ - id: riak-node
+ item:
+ type: org.apache.brooklyn.entity.nosql.riak.RiakNode
+ name: Riak Node
+ - id: riak-cluster
+ item:
+ type: org.apache.brooklyn.entity.nosql.riak.RiakCluster
+ name: Riak Cluster
+ - id: datastore
+ name: Datastore (Riak Cluster)
+ itemType: template
+ item:
+ services:
+ - type: riak-cluster
+ location:
+ jclouds:softlayer:
+ region: sjc01
+ # identity and credential must be set unless they are specified in your brooklyn.properties
+ # identity: XXX
+ # credential: XXX
+ brooklyn.config:
+ # the default size is 3 but this can be changed to suit your requirements
+ initial.size: 3
+ provisioning.properties:
+ # you can also define machine specs
+ minRam: 8gb
+~~~
+
+The items this will install are:
+
+- `riak-node`, as before, but with a different name
+- `riak-cluster` as a convenience short name for the `org.apache.brooklyn.entity.nosql.riak.RiakCluster` class
+- `datastore`, now pointing at the `riak-cluster` blueprint, in SoftLayer and with the given size and machine spec,
+ as the default implementation for anyone
+ requesting a `datastore` (and if installed atop the previous example, new references to `datastore`
+ will access this version because it is a higher number);
+ because it is a template, users will have the opportunity to edit the YAML (see below).
+ (This must be supplied after `riak-cluster`, because it refers to `riak-cluster`.)
+
+
+#### Legacy Syntax
+
+The following legacy and experimental syntax is also supported:
+
+~~~ yaml
+<blueprint-definition>
+brooklyn.catalog:
+ <catalog-metadata>
+~~~
+
+In this format, the `brooklyn.catalog` block is optional;
+and an `id` in the `<blueprint-definition>` will be used to determine the catalog ID.
+This is primarily supplied for OASIS CAMP 1.1 compatibility,
+where the same YAML blueprint can be POSTed to the catalog endpoint to add to a catalog
+or POSTed to the applications endpoint to deploy an instance.
+(This syntax is discouraged as the latter usage,
+POSTing to the applications endpoint,
+will ignored the `brooklyn.catalog` information;
+this means references to any `item` blocks in the `<catalog-metadata>` will not be resolved,
+and any OSGi `brooklyn.libraries` defined there will not be loaded.)
+
+
+
+### Templates and the Add-Application Wizard
+
+When a `template` is added to the catalog, the blueprint will appear in the 'Create Application' dialog
+as shown here:
+
+[](mysql-in-catalog.png)
+
+
+
+### Catalog Management
+
+The Catalog tab in the web console will show all versions of catalog items,
+and allow you to add new items.
+
+
+#### Adding to the Catalog
+
+On the UI the "add" button <img src="images/add-to-catalog.png" width="24" alt="add-to-catalog" /> at the top of the menu panel allows the
+addition of new Applications to the catalog, via YAML, and of new Locations.
+
+In addition to the GUI, items can be added to the catalog via the REST API
+with a `POST` of the YAML file to `/v1/catalog` endpoint.
+To do this using `curl`:
+
+~~~ bash
+curl http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/riak.catalog.bom
+~~~
+
+
+
+#### Deleting from the Catalog
+
+On the UI, if an item is selected, a 'Delete' button in the detail panel can be used to delete it from the catalog.
+
+Using the REST API, you can delete a versioned item from the catalog using the corresponding endpoint.
+For example, to delete the item with id `datastore` and version `1.0` with `curl`:
+
+~~~ bash
+curl -X DELETE http://127.0.0.1:8081/v1/catalog/applications/datastore/1.0
+~~~
+
+**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.
+
+If you have running apps which were created using the item you wish to delete, you should instead deprecate the catalog item.
+Deprecated catalog items will not appear in the add application wizard, or in the catalog list but will still
+be available to Brooklyn for rebinding. The option to display deprecated catalog items in the catalog list will be added
+in a future release.
+
+Deprecation applies to a specific version of a catalog item, so the full
+id including the version number is passed to the REST API as follows:
+
+~~~ bash
+curl -X POST http://127.0.0.1:8081/v1/catalog/entities/MySQL:1.0/deprecated/true
+~~~
+
+
+### Versioning
+
+Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
+For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+
+The combination of `id:version` strings must be unique across the catalog.
+It is an error to deploy the same version of an existing item:
+to update a blueprint, it is recommended to increase its version number;
+alternatively in some cases it is permitted to delete an `id:version` instance
+and then re-deploy.
+If no version is specified, re-deploying will automatically
+increment an internal version number for the catalog item.
+
+When referencing a blueprint, if a version number is not specified
+the latest non-snapshot version will be loaded when an entity is instantiated.
+
+
+### CLI Options
+
+The `brooklyn` CLI includes several commands for working with the catalog.
+
+* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file
+* `--catalogReset` will reset the catalog to the initial state
+ (based on `brooklyn/default.catalog.bom` on the classpath, by default in a dist in the `conf/` directory)
+* `--catalogInitial <file.bom>` will set the catalog items to use on first run,
+ on a catalog reset, or if persistence is off
+
+If `--catalogInitial` is not specified, the default initial catalog at `brooklyn/default.catalog.bom` will be used.
+As `scanJavaAnnotations: true` is set in `default.catalog.bom`, Brooklyn will scan the classpath for catalog items,
+which will be added to the catalog.
+To launch Brooklyn without initializing the catalog, use `--catalogInitial classpath://brooklyn/empty.catalog.bom`
+
+If [persistence](../persistence/) is enabled, catalog additions will remain between runs. If items that were
+previously added based on items in `brooklyn/default.catalog.bom` or `--catalogInitial` are
+deleted, they will not be re-added on subsequent restarts of brooklyn. I.e. `--catalogInitial` is ignored
+if persistence is enabled and persistent state has already been created.
+
+For more information on these commands, run `brooklyn help launch`.
+
+
+<!--
+TODO: make test cases from the code snippets here, and when building the docs assert that they match test cases
+-->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/catalog/mysql-in-catalog-w700.png
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/mysql-in-catalog-w700.png b/guide/ops/catalog/mysql-in-catalog-w700.png
new file mode 100644
index 0000000..f370249
Binary files /dev/null and b/guide/ops/catalog/mysql-in-catalog-w700.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/catalog/mysql-in-catalog.png
----------------------------------------------------------------------
diff --git a/guide/ops/catalog/mysql-in-catalog.png b/guide/ops/catalog/mysql-in-catalog.png
new file mode 100644
index 0000000..685455d
Binary files /dev/null and b/guide/ops/catalog/mysql-in-catalog.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/cli/cli-ref-guide.md
----------------------------------------------------------------------
diff --git a/guide/ops/cli/cli-ref-guide.md b/guide/ops/cli/cli-ref-guide.md
new file mode 100644
index 0000000..9a7ebfd
--- /dev/null
+++ b/guide/ops/cli/cli-ref-guide.md
@@ -0,0 +1,313 @@
+---
+title: CLI Reference Guide
+layout: website-normal
+menu_parent: index.md
+children:
+- { section: List of Commands }
+- { section: Scopes }
+- { section: Abbreviations}
+- { section: Command Reference }
+- { section: Login}
+- { section: Applications}
+- { section: Entities}
+- { section: Sensors}
+- { section: Effectors}
+- { section: Policies}
+- { section: Activities}
+- { section: Miscellaneous}
+---
+
+## Usage
+{% highlight text %}
+NAME:
+ br - A Brooklyn command line client application
+
+USAGE:
+ br [global options] command [command options] [arguments...]
+{% endhighlight %}
+
+## List of Commands
+Commands whose description begins with a `*` character are particularly experimental
+and likely to change in upcoming releases.
+
+{% highlight text %}
+COMMANDS:
+
+ access Show access control
+ activity Show the activity for an application / entity
+ add-catalog * Add a new catalog item from the supplied YAML
+ add-children * Add a child or children to this entity from the supplied YAML
+ application Show the status and location of running applications
+ catalog * List the available catalog applications
+ config Show the config for an application or entity
+ delete * Delete (expunge) a brooklyn application
+ deploy Deploy a new application from the given YAML (read from file or stdin)
+ destroy-policy Destroy a policy
+ effector Show the effectors for an application or entity
+ entity Show the entities of an application or entity
+ env Show the ENV stream for a given activity
+ invoke Invoke an effector of an application and entity
+ locations * List the available locations
+ login Login to brooklyn
+ policy Show the policies for an application or entity
+ rename Rename an application or entity
+ restart Invoke restart effector on an application and entity
+ sensor Show values of all sensors or named sensor for an application or entity
+ set Set config for an entity
+ spec Get the YAML spec used to create the entity, if available
+ start Invoke start effector on an application and entity
+ start-policy Start or resume a policy
+ stderr Show the STDERR stream for a given activity
+ stdin Show the STDIN stream for a given activity
+ stdout Show the STDOUT stream for a given activity
+ stop Invoke stop effector on an application and entity
+ stop-policy Suspends a policy
+ tree * Show the tree of all applications
+ version Display the version of the connected Brooklyn
+ help
+
+GLOBAL OPTIONS:
+ --help, -h show help
+ --version, -v print the version
+{% endhighlight %}
+
+
+## Scopes
+Many commands require a "scope" expression to indicate the target on which they operate.
+Where this
+is required the usage statements below will use the shorthand nomenclature of `<X-scope>`.
+The various scopes should be replaced on the command line as:
+
+- `<app-scope>`
+ `application <Name|AppID>`
+
+- `<entity-scope>`
+ `application <Name|AppID> entity <Name|EntityID>`
+
+- `<effector-scope>`
+ `application <Name|AppID> effector <Name>`
+ `application <Name|AppID> entity <Name|EntityID> effector <Name>`
+
+- `<config-scope>`
+ `application <Name|AppID> entity <Name|EntityID> config <ConfigID>`
+
+- `<activity-scope>`
+ `activity <ActivityID>`
+ `application <Name|AppID> entity <Name|EntityID> activity <ActivityID>`
+
+## Abbreviations
+Many of the commands and scopes have shortened aliases:
+
+{% highlight text %}
+activity act
+application app
+entity ent
+policy pol
+{% endhighlight %}
+
+## Command Reference
+
+### Login
+
+- `br login <URL> [username [password]]`
+ Login to Brooklyn. The CLI will prompt for a password if it is not provided. If the Brooklyn server is running on localhost with no security enabled, the username and password may be omitted.
+ On successful login, the version of the connected Brooklyn server is shown.
+
+- `br version`
+ Show the version of the connected Brooklyn server.
+
+### Applications
+
+- `br deploy ( <FILE> | - )`
+ Deploy an application based on the supplied YAML file or read from STDIN when `-` is given instead of a file name.
+
+- `br application`
+ List the running applications.
+
+- `br application <Name|AppID>`
+ Show the detail for an application.
+
+- `br <app-scope> config`
+ Show the configuration details for an application.
+
+- `br <app-scope> config <ConfigID>`
+ Show the value for a configuration item.
+
+- `br <app-scope> spec`
+ Show the YAML specification used to create the application.
+
+- `br <app-scope> rename <Name>`
+ Rename the application to <Name>.
+
+- `br <app-scope> stop`
+ Stop an application. See below for further information on the `stop` effector.
+
+- `br <app-scope> start`
+ Start an application. See below for further information on the `start` effector.
+
+- `br <app-scope> restart`
+ Restart an application. See below for further information on the `restart` effector.
+
+- `br <app-scope> delete`
+ Delete an application from Brooklyn.
+ **NOTE:** Use this command with care. Even if the application / entities are still running, Brooklyn will drop all knowledge of them and they will be left running in an 'orphaned' state.
+
+### Entities
+
+- `br <app-scope> entity`
+ List the child entities for an application.
+
+- `br <entity-scope> entity`
+ List the child entities for an entity.
+
+- `br <app-scope> entity <Name|EntityID>`
+ Show the detail of an entity.
+
+- `br <app-scope> entity -c <Name|EntityID>`
+ List the child entities for an entity.
+
+- `br <entity-scope> config`
+ Show the configuration details for an entity.
+
+- `br <entity-scope> config <ConfigID>`
+ Show the value for a configuration item.
+
+- `br <config-scope> set <ConfigValue>`
+ Set the value of a configuration item.
+
+- `br <entity-scope> spec`
+ Show the YAML specification used to create the entity.
+
+- `br <entity-scope> rename <Name>`
+ Rename the entity to <Name>.
+
+- `br <entity-scope> stop`
+ Stop an entity. See below for further information on the `stop` effector.
+
+- `br <entity-scope> start`
+ Start an entity. See below for further information on the `start` effector.
+
+- `br <entity-scope> restart`
+ Restart an entity. See below for further information on the `restart` effector.
+
+### Sensors
+
+- `br <app-scope> sensor`
+ List the sensors and values for an application.
+
+- `br <app-scope> sensor <SensorID>`
+ Show the value for a sensor.
+
+- `br <entity-scope> sensor`
+ List the sensors and values for an entity.
+
+- `br <entity-scope> sensor <SensorID>`
+ Show the value for a sensor.
+
+### Effectors
+
+- `br <app-scope> effector`
+ List the effectors for an application.
+
+- `br <app-scope> effector <EffectorID>`
+ Show the detail for an application effector.
+
+- `br <app-scope> effector <EffectorID> invoke`
+ Invoke the effector without any parameters.
+
+- `br <app-scope> effector <EffectorID> invoke [<param>=<value> ...]`
+ Invoke the effector with one of more parameters.
+
+- `br <entity-scope> effector`
+ List the effectors for an entity.
+
+- `br <entity-scope> effector <EffectorID>`
+ Show the detail for an entity effector.
+
+- `br <entity-scope> effector <EffectorID> invoke`
+ Invoke the effector without any parameters.
+
+- `br <entity-scope> effector <EffectorID> invoke [<param>=<value> ...]`
+ Invoke the effector with one of more parameters.
+ If the parameter value is
+ complex or multi-lined it may be provided in a file and referenced as:
+ `<param>=@<FILE>`
+
+**NOTE** Shortcut commands have been provided for the standard start, restart and stop effectors. For example:
+
+- `br <app-scope> stop`
+- `br <entity-scope> restart restartChildren=true`
+
+### Policies
+
+- `br <entity-scope> policy`
+ List the policies for an entity.
+
+- `br <entity-scope> policy <PolicyID>`
+ Show the detail for an entity policy.
+
+- `br <entity-scope> start-policy <PolicyID>`
+ Start an entity policy.
+
+- `br <entity-scope> stop-policy <PolicyID>`
+ Stop an entity policy.
+
+- `br <entity-scope> destroy-policy <PolicyID>`
+ Destroy an entity policy.
+
+### Activities
+
+- `br <app-scope> activity`
+ List the activities for an application.
+
+- `br <entity-scope> activity`
+ List the activities for an entity.
+
+- `br <activity-scope> activity`
+ List the activities for an activity (ie its children).
+
+- `br activity <ActivityID>`
+ Show the detail for an activity.
+
+- `br activity -c <ActivityID>`
+ List the child activities of an activity.
+
+- `br <activity-scope> stdin`
+ Show the `<STDIN>` stream for an activity.
+
+- `br <activity-scope> stdout`
+ Show the `<STDOUT>` stream for an activity.
+
+- `br <activity-scope> stderr`
+ Show the `<STDERR>` stream for an activity.
+
+- `br <activity-scope> env`
+ Show the Environment for an activity.
+
+### Miscellaneous
+
+These commands are likely to change significantly or be removed in later versions of the Brooklyn CLI.
+
+#### Applications
+
+- `br tree`
+ List all of the applications and entities in a tree representation.
+
+#### Entities
+
+- `br <entity-scope> add-children <FILE>`
+ Add a child or children to the entity from a YAML file.
+
+#### Catalog
+
+- `br catalog`
+ List the application catalog.
+
+- `br add-catalog <FILE>`
+ Add a catalog entry from a YAML file.
+
+- `br locations`
+ List the location catalog.
+
+- `br access`
+ Show if you have access to provision locations.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/cli/cli-usage-guide.md
----------------------------------------------------------------------
diff --git a/guide/ops/cli/cli-usage-guide.md b/guide/ops/cli/cli-usage-guide.md
new file mode 100644
index 0000000..c8edf0d
--- /dev/null
+++ b/guide/ops/cli/cli-usage-guide.md
@@ -0,0 +1,483 @@
+---
+title: CLI Usage Guide
+layout: website-normal
+menu_parent: index.md
+children:
+- { section: Login }
+- { section: Applications }
+- { section: Entities }
+- { section: Sensors }
+- { section: Effectors }
+- { section: Policies }
+- { section: Activities }
+- { section: YAML Blueprint }
+---
+
+This document provides a brief overview of using the most common Brooklyn CLI commands,
+by using the CLI to deploy an application then examine various aspects of it.
+
+The YAML blueprint for the application that will be deployed is shown at the end of this document.
+
+**NOTE:** In the sample output, some additional line-wrapping has been used to aid readabilty.
+
+## Login
+First, login to the running Brooklyn server. This example assumes that the Brooklyn server
+is running on `localhost`; change the URL and credentials as necessary.
+
+{% highlight text %}
+$ br login http://localhost:8081 admin
+Enter Password: *
+Connected to Brooklyn version 0.9.0-SNAPSHOT at http://localhost:8081
+{% endhighlight %}
+
+The version of the connected Brooklyn server may be viewed with the `version` command:
+
+{% highlight text %}
+$ br version
+0.9.0-SNAPSHOT
+{% endhighlight %}
+
+## Applications
+Deploy the application; on success the Id of the new application is displayed:
+
+{% highlight text %}
+$ br deploy webapp-policy.yaml
+Id: lmOcZbsT
+Name: WebCluster
+Status: In progress
+{% endhighlight %}
+
+The `application` command can be used to list a summary of all the running applications.
+After all of the entities have been started, the application status changes to `RUNNING`:
+
+{% highlight text %}
+$ br application
+Id Name Status Location
+YeEQHwgW AppCluster RUNNING CNTBOtjI
+lmOcZbsT WebCluster RUNNING CNTBOtjI
+{% endhighlight %}
+
+Further details of an application can be seen by using the ApplicationID or Name as a
+parameter for the `application` command:
+
+{% highlight text %}
+$ br application WebCluster
+Id: lmOcZbsT
+Name: WebCluster
+Status: RUNNING
+ServiceUp: true
+Type: org.apache.brooklyn.entity.stock.BasicApplication
+CatalogItemId: null
+LocationId: CNTBOtjI
+LocationName: FixedListMachineProvisioningLocation:CNTB
+LocationSpec: byon
+LocationType: org.apache.brooklyn.location.byon.FixedListMachineProvisioningLocation
+{% endhighlight %}
+
+The configuration details of an application can be seen with the `config` command:
+
+{% highlight text %}
+$ br application WebCluster config
+Key Value
+camp.template.id TYWVroRz
+brooklyn.wrapper_app true
+{% endhighlight %}
+
+
+## Entities
+The entities of an application can be viewed with the `entity` command:
+
+{% highlight text %}
+$ br app WebCluster entity
+Id Name Type
+xOcMooka WebApp org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+thHnLFkP WebDB org.apache.brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+It is common for an entity to have child entities; these can be listed by providing an
+entity-scope for the `entity` command:
+
+{% highlight text %}
+$ br app WebCluster entity WebApp entity
+Id Name Type
+e5pWAiHf Cluster of TomcatServer org.apache.brooklyn.entity.webapp.DynamicWebAppCluster
+CZ8QUVgX NginxController:CZ8Q org.apache.brooklyn.entity.proxy.nginx.NginxController
+{% endhighlight %}
+
+or by using `-c` (or `--children`) flag with the `entity` command:
+
+{% highlight text %}
+$ br app WebCluster entity -c e5pWAiHf
+Id Name Type
+x0P2LRxZ quarantine org.apache.brooklyn.entity.group.QuarantineGroup
+QK6QjmrW TomcatServer:QK6Q org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
+
+As for applications, the configuration details of an entity can be seen with the `config`
+command:
+
+{% highlight text %}
+$ br app WebCluster entity thHnLFkP config
+Key Value
+install.unique_label MySqlNode_5.6.26
+brooklyn.wrapper_app true
+datastore.creation.script.url https://bit.ly/brooklyn-visitors-creation-script
+camp.template.id dnw3GqN0
+camp.plan.id db
+onbox.base.dir /home/vagrant/brooklyn-managed-processes
+onbox.base.dir.resolved true
+
+{% endhighlight %}
+
+The value of a single configuration item can be displayed by using the configuration key
+as a parameter for the `config` command:
+
+{% highlight text %}
+$ br app WebCluster entity thHnLFkP config datastore.creation.script.url
+https://bit.ly/brooklyn-visitors-creation-script
+{% endhighlight %}
+
+The value of a configuration item can be changed by using the `set` command:
+
+{% highlight text %}
+$ br app WebCluster entity thHnLFkP config datastore.creation.script.url set \"https://bit.ly/new-script\"
+{% endhighlight %}
+
+## Sensors
+The sensors associated with an application or entity can be listed with the `sensor` command:
+
+{% highlight text %}
+$ br app WebCluster entity CZ8QUVgX sensor
+Name Value
+download.addon.urls: {"stickymodule":"https://bitbucket.org/nginx-goodies/n
+ ginx-sticky-module-ng/get/${addonversion}.tar.gz","pcr
+ e":"ftp://ftp.csx.cam.ac.uk/pub/software/programming/p
+ cre/pcre-${addonversion}.tar.gz"}
+download.url: http://nginx.org/download/nginx-${version}.tar.gz
+expandedinstall.dir: /home/vagrant/brooklyn-managed-processes/installs/Ngi
+ nxController_1.8.0/nginx-1.8.0
+host.address: 192.168.52.102
+host.name: 192.168.52.102
+host.sshAddress: vagrant@192.168.52.102:22
+host.subnet.address: 192.168.52.102
+host.subnet.hostname: 192.168.52.102
+http.port: 8000
+install.dir: /home/vagrant/brooklyn-managed-processes/installs/Ngin
+ xController_1.8.0
+log.location: /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2
+ /entities/NginxController_CZ8QUVgX/console
+main.uri: http://192.168.52.102:8000/
+member.sensor.hostandport:
+member.sensor.hostname: {"typeToken":null,"type":"java.lang.String","name":"ho
+ st.subnet.hostname","description":"Host name as known
+ internally in the subnet where it is running (if diffe
+ rent to host.name)","persistence":"REQUIRED"}
+member.sensor.portNumber: {"typeToken":null,"type":"java.lang.Integer","name":"h
+ ttp.port","description":"HTTP port","persistence":"RE
+ QUIRED","configKey":{"name":"http.port","typeToken":nu
+ ll,"type":"org.apache.brooklyn.api.location.PortRange"
+ ,"description":"HTTP port","defaultValue":{"ranges":[{
+ "port":8080},{"start":18080,"end":65535,"delta":1}]},"
+ reconfigurable":false,"inheritance":null,"constraint":
+ "ALWAYS_TRUE"}}
+nginx.log.access: /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2
+ /entities/NginxController_CZ8QUVgX/logs/access.log
+nginx.log.error: /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2
+ /entities/NginxController_CZ8QUVgX/logs/error.log
+nginx.pid.file: /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2
+ /entities/NginxController_CZ8QUVgX/pid.txt
+nginx.url.answers.nicely: true
+proxy.domainName:
+proxy.http.port: 8000
+proxy.https.port: 8443
+proxy.protocol: http
+proxy.serverpool.targets: {"TomcatServerImpl{id=QK6QjmrW}":"192.168.52.103:8080"}
+run.dir: /home/vagrant/brooklyn-managed-processes/apps/FoEXXwJ2
+ /entities/NginxController_CZ8QUVgX
+service.isUp: true
+service.notUp.diagnostics: {}
+service.notUp.indicators: {}
+service.problems: {}
+service.process.isRunning: true
+service.state: RUNNING
+service.state.expected: running @ 1449314377781 / Sat Dec 05 11:19:37 GMT 2015
+softwareprocess.pid.file:
+softwareservice.provisioningLocation: {"type":"org.apache.brooklyn.api.location.Location","i
+ d":"zhYBc6xt"}
+webapp.url: http://192.168.52.102:8000/
+{% endhighlight %}
+
+Details for an individual sensor can be shown by providing the Sensor Name as a
+parameter to the `sensor` command:
+
+{% highlight text %}
+$ br app WebCluster entity CZ8QUVgX sensor service.state.expected
+"running @ 1449314377781 / Sat Dec 05 11:19:37 GMT 2015"
+{% endhighlight %}
+
+## Effectors
+The effectors for an application or entity can be listed with the `effector` command:
+
+{% highlight text %}
+$ br app WebCluster effector
+Name Description Parameters
+restart Restart the process/service represented by an entity
+start Start the process/service represented by an entity locations
+stop Stop the process/service represented by an entity
+{% endhighlight %}
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q effector
+Name Description Parameters
+deploy Deploys an archive ...
+getCurrentConfiguration Gets the current ...
+populateServiceNotUpDiagnostics Populates the attribute ...
+reload Forces reload of ...
+restart Restart the process/service ... restartChildren,restartMachine
+start Start the process/service ... locations
+stop Stop the process/service ... stopProcessMode,stopMachineMode
+update Updates the entities ...
+{% endhighlight %}
+
+Details of an individual effector can be viewed by using the name as a parameter for
+the `effector` command:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q effector update
+Name: update
+Description: Updates the entities configuration, and then forces reload of that configuration
+Parameters:
+{% endhighlight %}
+
+An effector can be invoked by using the `invoke` command with an effector-scope:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q effector update invoke
+{% endhighlight %}
+
+Parameters can also be passed to the effector:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q effector restart invoke restartChildren=true
+{% endhighlight %}
+
+If a parameter value is complex or spans multiple lines, it may be provided in a file and used like this:
+
+{% highlight text %}
+$ br app WebCluster effector start invoke locations=@data.txt
+{% endhighlight %}
+
+Shortcut commands are available for the 3 standard effectors of `start`, `restart` and `stop`.
+These commands can be used directly with an app-scope or entity-scope:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q restart
+$ br app WebCluster stop
+{% endhighlight %}
+
+## Policies
+The policies associated with an application or entity can be listed with the `policy` command:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q policy
+Id Name State
+VcZ0cfeO Controller targets tracker RUNNING
+{% endhighlight %}
+
+Details of an individual policy may be viewed by using the PolicyID as a parameter to
+the `policy` command:
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q policy VcZ0cfeO
+Name Value Description
+group DynamicWebAppClusterImpl{id=TpbkaK4D} group
+notifyOnDuplicates false Whether to notify listeners when
+ a sensor is published with the
+ same value as last time
+sensorsToTrack [Sensor: host.subnet.hostname Sensors of members to be monitored
+ (java.lang.String), Sensor: http.port (implicitly adds service-up
+ (java.lang.Integer)] to this list, but that
+ behaviour may be deleted in a
+ subsequent release!)
+{% endhighlight %}
+
+## Activities
+The activities for an application or entity may be listed with the `activity` command:
+
+{% highlight text %}
+$ br app WebCluster activity
+Id Task Submitted Status Streams
+Wb6GV5rt start Sat Dec 19 11:08:01 GMT 2015 Completed
+q2MbyyTo invoking start[locations] on 2 nodes Sat Dec 19 11:08:01 GMT 2015 Completed
+{% endhighlight %}
+
+{% highlight text %}
+$ br app WebCluster entity NginxController:CZ8Q activity
+Id Task Submitted Status Streams
+GVh0pyKG start Sun Dec 20 19:18:06 GMT 2015 Completed
+WJm908rA provisioning (FixedListMachineProvisi... Sun Dec 20 19:18:06 GMT 2015 Completed
+L0cKFBrW pre-start Sun Dec 20 19:18:06 GMT 2015 Completed
+D0Ab2esP ssh: initializing on-box base dir ./b... Sun Dec 20 19:18:06 GMT 2015 Completed env,stderr,stdin,stdout
+tumLAdo4 start (processes) Sun Dec 20 19:18:06 GMT 2015 Completed
+YbF2czKM copy-pre-install-resources Sun Dec 20 19:18:06 GMT 2015 Completed
+o3YdqxsQ pre-install Sun Dec 20 19:18:06 GMT 2015 Completed
+TtGw4qMZ pre-install-command Sun Dec 20 19:18:06 GMT 2015 Completed
+duPvOSDB setup Sun Dec 20 19:18:06 GMT 2015 Completed
+WLtkbhgW copy-install-resources Sun Dec 20 19:18:06 GMT 2015 Completed
+ZQtrImnl install Sun Dec 20 19:18:06 GMT 2015 Completed
+hzi49YD6 ssh: setting up sudo Sun Dec 20 19:18:06 GMT 2015 Completed env,stderr,stdin,stdout
+eEUHcpfi ssh: Getting machine details for: Ssh... Sun Dec 20 19:18:07 GMT 2015 Completed env,stderr,stdin,stdout
+juTe2qLG ssh: installing NginxControllerImpl{i... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+hXqwEZJl post-install-command Sun Dec 20 19:18:08 GMT 2015 Completed
+vZliYwBI customize Sun Dec 20 19:18:08 GMT 2015 Completed
+O4Wwb0bP ssh: customizing NginxControllerImpl{... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+sDwMSkE2 copy-runtime-resources Sun Dec 20 19:18:08 GMT 2015 Completed
+yDYkdkS8 ssh: create run directory Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+W7dI8r1c pre-launch-command Sun Dec 20 19:18:08 GMT 2015 Completed
+OeZKwM5z launch Sun Dec 20 19:18:08 GMT 2015 Completed
+y50Gne5E scheduled:nginx.url.answers.nicely @ ... Sun Dec 20 19:18:08 GMT 2015 Scheduler,
+ARTninGE scheduled:service.process.isRunning @... Sun Dec 20 19:18:08 GMT 2015 Scheduler,
+tvZoNUTN ssh: launching NginxControllerImpl{id... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+YASrjA4w post-launch-command Sun Dec 20 19:18:09 GMT 2015 Completed
+jgLYv8pE post-launch Sun Dec 20 19:18:09 GMT 2015 Completed
+UN9OcWLS post-start Sun Dec 20 19:18:09 GMT 2015 Completed
+nmiv97He reload Sun Dec 20 19:18:09 GMT 2015 Completed
+FJfPbNtp ssh: restarting NginxControllerImpl{i... Sun Dec 20 19:18:10 GMT 2015 Completed env,stderr,stdin,stdout
+Xm1tjvKf update Sun Dec 20 19:18:40 GMT 2015 Completed
+Row67vfa reload Sun Dec 20 19:18:40 GMT 2015 Completed
+r8QZXlxJ ssh: restarting NginxControllerImpl{i... Sun Dec 20 19:18:40 GMT 2015 Completed env,stderr,stdin,stdout
+{% endhighlight %}
+
+The detail for an individual activity can be viewed by providing the ActivityID as a
+parameter to the `activity` command (an app-scope or entity-scope is not not needed for viewing
+the details of an activity):
+
+{% highlight text %}
+$ br activity tvZoNUTN
+Id: tvZoNUTN
+DisplayName: ssh: launching NginxControllerImpl{id=OxPUBk1p}
+Description:
+EntityId: OxPUBk1p
+EntityDisplayName: NginxController:OxPU
+Submitted: Sun Dec 20 19:18:08 GMT 2015
+Started: Sun Dec 20 19:18:08 GMT 2015
+Ended: Sun Dec 20 19:18:09 GMT 2015
+CurrentStatus: Completed
+IsError: false
+IsCancelled: false
+SubmittedByTask: OeZKwM5z
+Streams: stdin: 1133, stdout: 162, stderr: 0, env 0
+DetailedStatus: "Completed after 1.05s
+
+Result: 0"
+{% endhighlight %}
+
+The activity command output shows whether any streams were associated with it. The streams
+and environment for an activity can be viewed with the commands `stdin`, `stdout`,
+`stderr` and `env`:
+
+{% highlight text %}
+$ br activity tvZoNUTN stdin
+export RUN_DIR="/home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p"
+mkdir -p $RUN_DIR
+cd $RUN_DIR
+cd /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p
+{ which "./sbin/nginx" || { EXIT_CODE=$? && ( echo "The required executable \"./sbin/nginx\" does not exist" | tee /dev/stderr ) && exit $EXIT_CODE ; } ; }
+nohup ./sbin/nginx -p /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/ -c conf/server.conf > /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/console 2>&1 &
+for i in {1..10}
+do
+ test -f /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/logs/nginx.pid && ps -p `cat /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/logs/nginx.pid` && exit
+ sleep 1
+done
+echo "No explicit error launching nginx but couldn't find process by pid; continuing but may subsequently fail"
+cat /home/vagrant/brooklyn-managed-processes/apps/V5GQCpIT/entities/NginxController_OxPUBk1p/console | tee /dev/stderr
+{% endhighlight %}
+
+{% highlight text %}
+$ br activity tvZoNUTN stdout
+./sbin/nginx
+ PID TTY TIME CMD
+ 6178 ? 00:00:00 nginx
+Executed /tmp/brooklyn-20151220-191808796-CaiI-launching_NginxControllerImpl_.sh, result 0
+{% endhighlight %}
+
+The child activities of an activity may be listed by providing an activity-scope for the
+`activity` command:
+
+{% highlight text %}
+$ br activity OeZKwM5z
+Id: OeZKwM5z
+DisplayName: launch
+Description:
+EntityId: OxPUBk1p
+EntityDisplayName: NginxController:OxPU
+Submitted: Sun Dec 20 19:18:08 GMT 2015
+Started: Sun Dec 20 19:18:08 GMT 2015
+Ended: Sun Dec 20 19:18:09 GMT 2015
+CurrentStatus: Completed
+IsError: false
+IsCancelled: false
+SubmittedByTask: tumLAdo4
+Streams:
+DetailedStatus: "Completed after 1.06s
+
+No return value (null)"
+
+$ br activity OeZKwM5z activity
+Id Task Submitted Status Streams
+tvZoNUTN ssh: launching NginxControllerImpl{id... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+{% endhighlight %}
+
+or by using the `-c` (or `--children`) flag with the `activity` command:
+
+{% highlight text %}
+$ br activity -c OeZKwM5z
+Id Task Submitted Status Streams
+tvZoNUTN ssh: launching NginxControllerImpl{id... Sun Dec 20 19:18:08 GMT 2015 Completed env,stderr,stdin,stdout
+{% endhighlight %}
+
+## YAML Blueprint
+This the YAML blueprint used for this document.
+
+{% highlight text %}
+name: WebCluster
+
+location:
+ byon:
+ user: vagrant
+ password: vagrant
+ hosts:
+ - 192.168.52.101
+ - 192.168.52.102
+ - 192.168.52.103
+ - 192.168.52.104
+ - 192.168.52.105
+
+services:
+
+- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ name: WebApp
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ java.sysprops:
+ brooklyn.example.db.url: >
+ $brooklyn:formatString("jdbc:%s%s?user=%s&password=%s",
+ component("db").attributeWhenReady("datastore.url"),
+ "visitors", "brooklyn", "br00k11n")
+ brooklyn.policies:
+ - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: webapp.reqs.perSec.windowed.perNode
+ metricLowerBound: 2
+ metricUpperBound: 10
+ minPoolSize: 1
+ maxPoolSize: 2
+ resizeUpStabilizationDelay: 1m
+ resizeDownStabilizationDelay: 5m
+
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: WebDB
+ brooklyn.config:
+ creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/cli/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/cli/index.md b/guide/ops/cli/index.md
new file mode 100644
index 0000000..d01cc47
--- /dev/null
+++ b/guide/ops/cli/index.md
@@ -0,0 +1,12 @@
+---
+layout: website-normal
+title: Client CLI Reference
+children:
+- cli-ref-guide.md
+- cli-usage-guide.md
+---
+
+{% include list-children.html %}
+
+**NOTE:** These documents are for using the Brooklyn Client CLI to access a running Brooklyn Server. For
+information on starting on a Brooklyn Server, refer to [Server CLI Reference](../server-cli-reference.html).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/externalized-configuration.md
----------------------------------------------------------------------
diff --git a/guide/ops/externalized-configuration.md b/guide/ops/externalized-configuration.md
new file mode 100644
index 0000000..24fd4eb
--- /dev/null
+++ b/guide/ops/externalized-configuration.md
@@ -0,0 +1,253 @@
+---
+title: Externalized Configuration
+layout: website-normal
+---
+
+Sometimes it is useful that configuration in a blueprint, or in Brooklyn itself, is not given explicitly, but is instead
+replaced with a reference to some other storage system. For example, it is undesirable for a blueprint to contain a
+plain-text password for a production system, especially if (as we often recommend) the blueprints are kept in the
+developer's source code control system.
+
+To handle this problem, Apache Brooklyn supports externalized configuration. This allows a blueprint to refer to
+a piece of information that is stored elsewhere. `brooklyn.properties` defines the external suppliers of configuration
+information. At runtime, when Brooklyn finds a reference to externalized configuration in a blueprint, it consults
+`brooklyn.properties` for information about the supplier, and then requests that the supplier return the information
+required by the blueprint.
+
+Take, as a simple example, a web app which connects to a database. In development, the developer is running a local
+instance of PostgreSQL with a simple username and password. But in production, an enterprise-grade cluster of PostgreSQL
+is used, and a dedicated service is used to provide passwords. The same blueprint can be used to service both groups
+of users, with `brooklyn.properties` changing the behaviour depending on the deployment environment.
+
+Here is the blueprint:
+
+{% highlight yaml %}
+name: MyApplication
+services:
+- type: brooklyn.entity.webapp.jboss.JBoss7Server
+ name: AppServer HelloWorld
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ http.port: 8080+
+ java.sysprops:
+ brooklyn.example.db.url: $brooklyn:formatString("jdbc:postgresql://%s/myappdb?user=%s\\&password=%s",
+ external("servers", "postgresql"), external("credentials", "postgresql-user"), external("credentials", "postgresql-password"))
+{% endhighlight %}
+
+You can see that when we are building up the JDBC URL, we are using the `external` function. This takes two parameters:
+the first is the name of the configuration supplier, the second is the name of a key that is stored by the configuration
+supplier. In this case we are using two different suppliers: `servers` to store the location of the server, and
+`credentials` which is a security-optimized supplier of secrets.
+
+Developers would add lines like this to the `brooklyn.properties` file on their workstation:
+
+{% highlight properties %}
+brooklyn.external.servers=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier
+brooklyn.external.servers.postgresql=127.0.0.1
+brooklyn.external.credentials=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier
+brooklyn.external.credentials.postgresql-user=admin
+brooklyn.external.credentials.postgresql-password=admin
+{% endhighlight %}
+
+In this case, all of the required information is included in-line in the local `brooklyn.properties`.
+
+Whereas in production, `brooklyn.properties` might look like this:
+
+{% highlight properties %}
+brooklyn.external.servers=org.apache.brooklyn.core.config.external.PropertiesFileExternalConfigSupplier
+brooklyn.external.servers.propertiesUrl=https://ops.example.com/servers.properties
+brooklyn.external.credentials=org.apache.brooklyn.core.config.external.vault.VaultAppIdExternalConfigSupplier
+brooklyn.external.credentials.endpoint=https://vault.example.com
+brooklyn.external.credentials.path=secret/enterprise-postgres
+brooklyn.external.credentials.appId=MyApp
+{% endhighlight %}
+
+In this case, the list of servers is stored in a properties file located on an Operations Department web server, and the
+credentials are stored in an instance of [Vault](https://www.vaultproject.io/).
+
+## Defining Suppliers
+
+External configuration suppliers are defined in `brooklyn.properties`. The minimal definition is of the form:
+
+brooklyn.external.*supplierName* = *className*
+
+This defines a supplier named *supplierName*. Brooklyn will attempt to instantiate *className*; it is this class which
+will provide the behaviour of how to retrieve data from the supplier. Brooklyn includes a number of supplier
+implementations; see below for more details.
+
+Suppliers may require additional configuration options. These are given as additional properties in
+`brooklyn.properties`:
+
+{% highlight properties %}
+brooklyn.external.supplierName = className
+brooklyn.external.supplierName.firstConfig = value
+brooklyn.external.supplierName.secondConfig = value
+{% endhighlight %}
+
+## Referring to External Configuration in Blueprints
+
+Externalized configuration adds a new function to the Brooklyn blueprint language DSL, `$brooklyn:external`. This
+function takes two parameters:
+
+1. supplier
+2. key
+
+When resolving the external reference, Brooklyn will first identify the *supplier* of the information, then it will
+give the supplier the *key*. The returned value will be substituted into the blueprint.
+
+You can use `$brooklyn:external` directly:
+
+{% highlight yaml %}
+name: MyApplication
+brooklyn.config:
+ example: $brooklyn:external("supplier", "key")
+{% endhighlight %}
+
+or embed the `external` function inside another `$brooklyn` DSL function, such as `$brooklyn:formatString`:
+
+{% highlight yaml %}
+name: MyApplication
+brooklyn.config:
+ example: $brooklyn:formatString("%s", external("supplier", "key"))
+{% endhighlight %}
+
+
+## Referring to External Configuration in brooklyn.properties
+
+The same blueprint language DSL can be used from `brooklyn.properties`. For example:
+
+{% highlight properties %}
+brooklyn.location.jclouds.aws-ec2.identity=$brooklyn:external("mysupplier", "aws-identity")
+brooklyn.location.jclouds.aws-ec2.credential=$brooklyn:external("mysupplier", "aws-credential")
+{% endhighlight %}
+
+
+## Referring to External Configuration in Catalog Items
+
+The same blueprint language DSL can be used within YAML catalog items. For example:
+
+ brooklyn.catalog:
+ id: com.example.myblueprint
+ version: 1.2.3
+ brooklyn.libraries:
+ - >
+ $brooklyn:formatString("https://%s:%s@repo.example.com/libs/myblueprint-1.2.3.jar",
+ external("mysuppier", "username"), external("mysupplier", "password"))
+ item:
+ type: com.example.MyBlueprint
+
+Note the `>` in the example above is used to split across multiple lines.
+
+
+## Suppliers available with Brooklyn
+
+Brooklyn ships with a number of external configuration suppliers ready to use.
+
+### In-place
+
+**InPlaceExternalConfigSupplier** embeds the configuration keys and values as properties inside `brooklyn.properties`.
+For example:
+
+{% highlight properties %}
+brooklyn.external.servers=org.apache.brooklyn.core.config.external.InPlaceExternalConfigSupplier
+brooklyn.external.servers.postgresql=127.0.0.1
+{% endhighlight %}
+
+Then, a blueprint which referred to `$brooklyn:external("servers", "postgresql")` would receive the value `127.0.0.1`.
+
+### Properties file
+
+**PropertiesFileExternalConfigSupplier** loads a properties file from a URL, and uses the keys and values in this
+file to respond to configuration lookups.
+
+Given this configuration:
+
+{% highlight properties %}
+brooklyn.external.servers=org.apache.brooklyn.core.config.external.PropertiesFileExternalConfigSupplier
+brooklyn.external.servers.propertiesUrl=https://ops.example.com/servers.properties
+{% endhighlight %}
+
+This would cause the supplier to download the given URL. Assuming that the file contained this entry:
+
+{% highlight properties %}
+postgresql=127.0.0.1
+{% endhighlight %}
+
+Then, a blueprint which referred to `$brooklyn:external("servers", "postgresql")` would receive the value `127.0.0.1`.
+
+### Vault
+
+[Vault](https://www.vaultproject.io) is a server-based tool for managing secrets. Brooklyn provides suppliers that are
+able to query the Vault REST API for configuration values. The different suppliers implement alternative authentication
+options that Vault provides.
+
+For *all* of the authentication methods, you must always set these properties in `brooklyn.properties`:
+
+{% highlight properties %}
+brooklyn.external.supplierName.endpoint=<Vault HTTP/HTTPs endpoint>
+brooklyn.external.supplierName.path=<path to a Vault object>
+{% endhighlight %}
+
+For example, if the path is set to `secret/brooklyn`, then attempting to retrieve the key `foo` would cause Brooklyn
+to retrieve the value of the `foo` key on the `secret/brooklyn` object. This value can be set using the Vault CLI
+like this:
+
+{% highlight bash %}
+vault write secret/brooklyn foo=bar
+{% endhighlight %}
+
+#### Authentication by username and password
+
+The `userpass` plugin for Vault allows authentication with username and password.
+
+{% highlight properties %}
+brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultUserPassExternalConfigSupplier
+brooklyn.external.supplierName.username=fred
+brooklyn.external.supplierName.password=s3kr1t
+{% endhighlight %}
+
+#### Authentication using App ID
+
+The `app_id` plugin for Vault allows you to specify an "app ID", and then designate particular "user IDs" to be part
+of the app. Typically the app ID would be known and shared, but user ID would be autogenerated on the client in some
+way. Brooklyn implements this by determining the MAC address of the server running Brooklyn (expressed as 12 lower
+case hexadecimal digits without separators) and passing this as the user ID.
+
+{% highlight properties %}
+brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultAppIdExternalConfigSupplier
+brooklyn.external.supplierName.appId=MyApp
+{% endhighlight %}
+
+If you do not wish to use the MAC address as the user ID, you can override it with your own choice of user ID:
+
+{% highlight properties %}
+brooklyn.external.supplierName.userId=server3.cluster2.europe
+{% endhighlight %}
+
+#### Authentication by fixed token
+
+If you have a fixed token string, then you can use the *VaultTokenExternalConfigSupplier* class and provide the token
+in `brooklyn.properties`:
+
+{% highlight properties %}
+brooklyn.external.supplierName=org.apache.brooklyn.core.config.external.vault.VaultTokenExternalConfigSupplier
+brooklyn.external.supplierName.token=1091fc84-70c1-b266-b99f-781684dd0d2b
+{% endhighlight %}
+
+This supplier is suitable for "smoke testing" the Vault supplier using the Initial Root Token or similar. However it
+is not suitable for production use as it is inherently insecure - should the token be compromised, an attacker could
+have complete access to your Vault, and the cleanup operation would be difficult. Instead you should use one of the
+other suppliers.
+
+## Writing Custom External Configuration Suppliers
+
+Supplier implementations must conform to the brooklyn.config.external.ExternalConfigSupplier interface, which is very
+simple:
+
+{% highlight java %}
+String getName();
+String get(String key);
+{% endhighlight %}
+
+Classes implementing this interface can be placed in the `lib/dropins` folder of Brooklyn, and then the supplier
+defined in `brooklyn.properties` as normal.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/_my-web-cluster.yaml
----------------------------------------------------------------------
diff --git a/guide/ops/gui/_my-web-cluster.yaml b/guide/ops/gui/_my-web-cluster.yaml
new file mode 100644
index 0000000..a3295b9
--- /dev/null
+++ b/guide/ops/gui/_my-web-cluster.yaml
@@ -0,0 +1,23 @@
+name: My Web Cluster
+
+location:
+ jclouds:aws-ec2:
+ identity: ABCDEFGHIJKLMNOPQRST
+ credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+
+services:
+- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+ name: My Web
+ id: webappcluster
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.6.0/brooklyn-example-hello-world-sql-webapp-0.6.0.war
+ java.sysprops:
+ brooklyn.example.db.url: >
+ $brooklyn:formatString("jdbc:%s%s?user=%s&password=%s",
+ component("db").attributeWhenReady("datastore.url"),
+ "visitors", "brooklyn", "br00k11n")
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+ name: My DB
+ id: 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/brooklyn-docs/blob/6e86cb02/guide/ops/gui/_my-web-cluster2.yaml
----------------------------------------------------------------------
diff --git a/guide/ops/gui/_my-web-cluster2.yaml b/guide/ops/gui/_my-web-cluster2.yaml
new file mode 100644
index 0000000..33723ab
--- /dev/null
+++ b/guide/ops/gui/_my-web-cluster2.yaml
@@ -0,0 +1,31 @@
+name: My Web Cluster
+
+location: localhost
+
+services:
+
+- type: org.apache.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/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")
+ brooklyn.policies:
+ - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+ brooklyn.config:
+ metric: webapp.reqs.perSec.windowed.perNode
+ metricLowerBound: 0.1
+ metricUpperBound: 10
+ minPoolSize: 1
+ maxPoolSize: 4
+ resizeUpStabilizationDelay: 10s
+ resizeDownStabilizationDelay: 1m
+
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+ id: db
+ name: My DB
+ brooklyn.config:
+ creationScriptUrl: https://bit.ly/brooklyn-visitors-creation-script
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/blueprints.md
----------------------------------------------------------------------
diff --git a/guide/ops/gui/blueprints.md b/guide/ops/gui/blueprints.md
new file mode 100644
index 0000000..8c67f9b
--- /dev/null
+++ b/guide/ops/gui/blueprints.md
@@ -0,0 +1,68 @@
+---
+title: Deploying Blueprints
+layout: website-normal
+menu_parent: index.md
+children:
+- { section: Launching from a Blueprint, title: Launching from a Blueprint }
+- { section: Launching from the Catalog, title: Launching from the Catalog }
+---
+
+{% include fields.md %}
+
+
+## Launching from a Blueprint
+
+When you first access the web console on [http://127.0.0.1:8081](http://127.0.0.1:8081) you will be requested to create your first application.
+
+We'll start by deploying an application via a YAML blueprint consisting of the following layers.
+
+- MySQL DB
+- Dynamic web application cluster
+ - Nginx load balancer
+ - Tomcat app server cluster
+
+[](images/add-application-modal-yaml-large.png)
+
+Switch to the YAML tab and copy the blueprint below into the large text box.
+
+But *before* you submit it, modify the YAML to specify the location where the application will be deployed.
+
+{% highlight yaml %}
+{% readj _my-web-cluster.yaml %}
+{% endhighlight %}
+
+Replace the `location:` element with values for your chosen target environment, for example to use SoftLayer rather than AWS (updating with your own credentials):
+
+{% highlight yaml %}
+location:
+ jclouds:softlayer:
+ identity: ABCDEFGHIJKLMNOPQRST
+ credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
+{% endhighlight %}
+
+**NOTE**: See __[Locations](../locations)__ in the Operations section of the User Guide for instructions on setting up alternate cloud providers, bring-your-own-nodes, or localhost targets, and storing credentials/locations in a file on disk rather than in the blueprint.
+
+With the modified YAML in the dialog, click "Finish". The dialog will close and Brooklyn will begin deploying your
+application. Your application will be shown as "Starting" on the web console's front page.
+
+[](images/home-app-starting-large.png)
+
+Depending on your choice of location it may take some time for the application nodes to start, the next page describes how you can monitor the progress of the application deployment and verify its successful deployment.
+
+## Launching from the Catalog
+
+Instead of pasting the YAML blueprint each time, it can be added to the Brooklyn Catalog where it will be accessible from the Catalog tab of the Create Application dialog.
+
+[](images/add-application-catalog-web-cluster-with-db-large.png)
+
+<!-- TODO: more detail for adding to catalog? but wait for persistence to be the default,
+ rather than extensively document default.catalog.bom.
+ also need to include instructions on stopping (currently in help, including stopping apps) -->
+
+See __[Catalog](../catalog/)__ in the Operations section of the User Guide for instructions on creating a new Catalog entry from your Blueprint YAML.
+
+
+## Next
+
+So far we have touched on Brooklyn's ability to *deploy* an application blueprint to a cloud provider.
+The next section will show how to **[Monitor and Manage Applications](managing.html)**.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-large.png b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-large.png
new file mode 100644
index 0000000..1e1cf4e
Binary files /dev/null and b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location-large.png b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location-large.png
new file mode 100644
index 0000000..05e9b0c
Binary files /dev/null and b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location.png b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location.png
new file mode 100644
index 0000000..c13fdd8
Binary files /dev/null and b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db-location.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-catalog-web-cluster-with-db.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-catalog-web-cluster-with-db.png b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db.png
new file mode 100644
index 0000000..0a7d985
Binary files /dev/null and b/guide/ops/gui/images/add-application-catalog-web-cluster-with-db.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-modal-yaml-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-modal-yaml-large.png b/guide/ops/gui/images/add-application-modal-yaml-large.png
new file mode 100644
index 0000000..57c9e5c
Binary files /dev/null and b/guide/ops/gui/images/add-application-modal-yaml-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/add-application-modal-yaml.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/add-application-modal-yaml.png b/guide/ops/gui/images/add-application-modal-yaml.png
new file mode 100644
index 0000000..a9b2c35
Binary files /dev/null and b/guide/ops/gui/images/add-application-modal-yaml.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/home-app-starting-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/home-app-starting-large.png b/guide/ops/gui/images/home-app-starting-large.png
new file mode 100644
index 0000000..5b92e31
Binary files /dev/null and b/guide/ops/gui/images/home-app-starting-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/home-app-starting.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/home-app-starting.png b/guide/ops/gui/images/home-app-starting.png
new file mode 100644
index 0000000..5394498
Binary files /dev/null and b/guide/ops/gui/images/home-app-starting.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/my-db-activities-step1-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/my-db-activities-step1-large.png b/guide/ops/gui/images/my-db-activities-step1-large.png
new file mode 100644
index 0000000..c715ba3
Binary files /dev/null and b/guide/ops/gui/images/my-db-activities-step1-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/my-db-activities-step1.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/my-db-activities-step1.png b/guide/ops/gui/images/my-db-activities-step1.png
new file mode 100644
index 0000000..382a198
Binary files /dev/null and b/guide/ops/gui/images/my-db-activities-step1.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/my-db-activities-step2-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/my-db-activities-step2-large.png b/guide/ops/gui/images/my-db-activities-step2-large.png
new file mode 100644
index 0000000..3a6d1e3
Binary files /dev/null and b/guide/ops/gui/images/my-db-activities-step2-large.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/my-db-activities-step2.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/my-db-activities-step2.png b/guide/ops/gui/images/my-db-activities-step2.png
new file mode 100644
index 0000000..e771a06
Binary files /dev/null and b/guide/ops/gui/images/my-db-activities-step2.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/ops/gui/images/my-db-activities-step3-large.png
----------------------------------------------------------------------
diff --git a/guide/ops/gui/images/my-db-activities-step3-large.png b/guide/ops/gui/images/my-db-activities-step3-large.png
new file mode 100644
index 0000000..7f484a2
Binary files /dev/null and b/guide/ops/gui/images/my-db-activities-step3-large.png differ