brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [50/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!)
Date Mon, 01 Feb 2016 17:45:58 GMT
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-guide-root.yml
----------------------------------------------------------------------
diff --git a/_build/config-guide-root.yml b/_build/config-guide-root.yml
new file mode 100644
index 0000000..f45a593
--- /dev/null
+++ b/_build/config-guide-root.yml
@@ -0,0 +1,2 @@
+path:
+  guide: ""

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-guide-version.yml
----------------------------------------------------------------------
diff --git a/_build/config-guide-version.yml b/_build/config-guide-version.yml
new file mode 100644
index 0000000..9b910a9
--- /dev/null
+++ b/_build/config-guide-version.yml
@@ -0,0 +1,6 @@
+path:
+  # BROOKLYN_VERSION_BELOW
+  guide: /v/0.9.0-SNAPSHOT
+  # BROOKLYN_VERSION_BELOW
+  style: /v/0.9.0-SNAPSHOT/style
+  website: ""

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-production.yml
----------------------------------------------------------------------
diff --git a/_build/config-production.yml b/_build/config-production.yml
new file mode 100644
index 0000000..445b7a1
--- /dev/null
+++ b/_build/config-production.yml
@@ -0,0 +1,6 @@
+# in production we always set the URL and dependencies should come from the remote source
+
+url: https://brooklyn.apache.org
+url_root: https://brooklyn.apache.org
+
+dependency_mode: remote

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-pygments.yml
----------------------------------------------------------------------
diff --git a/_build/config-pygments.yml b/_build/config-pygments.yml
new file mode 100644
index 0000000..29f85d5
--- /dev/null
+++ b/_build/config-pygments.yml
@@ -0,0 +1,28 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# this uses python pygments engine to render code;
+# with recent jekyll (dec 2014) i can't see any difference,
+# and the formatting appears to be following pygments rules
+# without it, so perhaps the jekyll ruby highlighter is very
+# good (identical? i see a pygments gem, even if the docs
+# say it is using something called "rouge");
+# included here so it is documented at least.
+# NB: you may need `python easy_install pygments`
+highlighter: pygments

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-rdiscount.yml
----------------------------------------------------------------------
diff --git a/_build/config-rdiscount.yml b/_build/config-rdiscount.yml
new file mode 100644
index 0000000..aa82ee3
--- /dev/null
+++ b/_build/config-rdiscount.yml
@@ -0,0 +1,28 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# add this file as a config to use "rdiscount" markdown processor
+# instead of the default ruby/jekyll one.
+# rdiscount is the original, and C-based, so a bit faster
+# (but not much, 7s vs 8.5s on my system -alex)
+# and slightly more forgiving, e.g. for <a href="chapter"> tags
+# on a line directly about a section header
+# (ruby markdown seems to want a blank line between the two).
+# NB: this requires adding "rdiscount" to your Gemfile, then `cd ~ ; cd -`
+markdown: rdiscount

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-style-latest.yml
----------------------------------------------------------------------
diff --git a/_build/config-style-latest.yml b/_build/config-style-latest.yml
new file mode 100644
index 0000000..d03b87d
--- /dev/null
+++ b/_build/config-style-latest.yml
@@ -0,0 +1,2 @@
+path:
+  style: /v/latest/style

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-subpath-brooklyn.yml
----------------------------------------------------------------------
diff --git a/_build/config-subpath-brooklyn.yml b/_build/config-subpath-brooklyn.yml
new file mode 100644
index 0000000..ade7e19
--- /dev/null
+++ b/_build/config-subpath-brooklyn.yml
@@ -0,0 +1,9 @@
+# to test for absolute reference problems, prefix each of the paths and set the baseurl
+
+path:
+  style: /brooklyn/style
+  guide: /brooklyn/v/latest
+  website: /brooklyn
+  v: /brooklyn/v
+
+baseurl: /brooklyn

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-website-root.yml
----------------------------------------------------------------------
diff --git a/_build/config-website-root.yml b/_build/config-website-root.yml
new file mode 100644
index 0000000..e5e4b07
--- /dev/null
+++ b/_build/config-website-root.yml
@@ -0,0 +1,3 @@
+path:
+  website: ""
+  guide: "/v/latest"

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/help.txt
----------------------------------------------------------------------
diff --git a/_build/help.txt b/_build/help.txt
new file mode 100644
index 0000000..e855c10
--- /dev/null
+++ b/_build/help.txt
@@ -0,0 +1,22 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+See the README.md in the parent directory,
+or run:
+
+    _build/build.sh help

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/htmlproof-brooklyn.sh
----------------------------------------------------------------------
diff --git a/_build/htmlproof-brooklyn.sh b/_build/htmlproof-brooklyn.sh
new file mode 100755
index 0000000..5fa6b1b
--- /dev/null
+++ b/_build/htmlproof-brooklyn.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby_executable_hooks
+
+# supports --disable_external, --ignore-v-refs, --v-only
+
+require 'html/proofer'
+
+HTML::Proofer.new("./_site", {
+  :href_ignore => [
+      /https?:\/\/127.*/,
+      /https?:\/\/github.com\/apache\/incubator-brooklyn\/edit.*/,
+      ((ARGV.include? "--ignore-v-refs") ? /.*\/v\/.*/ : /ignore/),
+      ((ARGV.include? "--v-only") ? /\/(|[^v].*|.[^\/].*)/ : /ignore/)
+      ],
+  :alt_ignore => [/.*/], 
+  # don't scan javadoc files (too many errors) 
+  # or autogen catalog items (their style files are wrong in some modes; reinstate when cleaner)
+  :disable_external => (ARGV.include? "--disable_external"),
+  :file_ignore => [ /.*\/(javadoc|apidoc|learnmore\/catalog)\/.*/ ] 
+  # bug - must do above - see https://github.com/gjtorikian/html-proofer/issues/145 
+#  :file_ignore => [ /.*\/javadoc\/.*/, /.*\/learnmore\/catalog\/.*/ ]
+  }).run

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/javadoc-overview.html
----------------------------------------------------------------------
diff --git a/_build/javadoc-overview.html b/_build/javadoc-overview.html
new file mode 100644
index 0000000..ef4819a
--- /dev/null
+++ b/_build/javadoc-overview.html
@@ -0,0 +1,22 @@
+<html><body>
+
+<!-- BROOKLYN_VERSION_BELOW -->
+Javadoc for <a href="http://brooklyn.io"> Apache Brooklyn</a> 0.9.0-SNAPSHOT
+
+<p>
+                Apache Brooklyn is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the 
+                Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the
+                infrastructure, communications, and decision making process have stabilized in a manner consistent with other
+                successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of
+                the code, it does indicate that the project has yet to be fully endorsed by the ASF.
+</p>
+<p>
+                Apache Brooklyn is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License v2.0</a>.
+</p>
+
+<p>
+<!-- BROOKLYN_VERSION_BELOW -->
+This is the Javadoc for v 0.9.0-SNAPSHOT (git SHA1 hash ${SHA1STAMP}) auto-generated on ${DATESTAMP}.
+</p> 
+
+</body><html>

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/list-objects-logback.xml
----------------------------------------------------------------------
diff --git a/_build/list-objects-logback.xml b/_build/list-objects-logback.xml
new file mode 100644
index 0000000..4ce07ae
--- /dev/null
+++ b/_build/list-objects-logback.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+-->
+<configuration>
+  <property name="logging.basename" scope="context" value="brooklyn" />
+  <property name="logging.dir" scope="context" value="./" />
+
+  <!-- this file defines the default logging configuration for brooklyn projects,
+       in a way which is intended to be friendly to downstream projects.
+
+       downstream projects may be routed to this file in two situations:
+
+       * running tests (via brooklyn-test-support)
+       * dependency on `brooklyn-logback-xml` and running in IDE
+
+       this file may be overridden in downstream projects, as may any of the files incldued here.
+
+       for an _assembly_ (i.e. a redistributable binary) a project must supply
+       a logback.xml.  it can route to this file if they wish, or use some of
+       the files referenced herein, or ignore it altogether.  (the reason for
+       this is that assemblies usually want to declare their own logging anyway.)
+  -->
+
+  <!-- set default root logger threshhold to info; some categories may get debug -->
+  <root level="INFO"/>
+</configuration>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/make-javadoc.sh
----------------------------------------------------------------------
diff --git a/_build/make-javadoc.sh b/_build/make-javadoc.sh
new file mode 100755
index 0000000..c7d9a5a
--- /dev/null
+++ b/_build/make-javadoc.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+JAVADOC_TARGET1_SUBPATH=javadoc
+JAVADOC_TARGET2_SUBPATH=misc/javadoc
+
+if [ ! -x make-javadoc.sh ]; then
+  echo This command must be run from the _build directory, not its parent.
+  exit 1
+fi
+
+if [ -z "$BROOKLYN_JAVADOC_SOURCE_PATHS" ]; then
+  echo detecting source paths for javadoc
+  export SOURCE_PATHS=`find ../.. -name java | grep "src/main/java$" | grep -v "^../../sandbox" | tr "\\n" ":"`
+else
+  echo using pre-defined source paths $BROOKLYN_JAVADOC_SOURCE_PATHS
+  export SOURCE_PATHS=$BROOKLYN_JAVADOC_SOURCE_PATHS
+fi
+
+mkdir -p target
+rm -rf target/$JAVADOC_TARGET1_SUBPATH/
+
+export YEARSTAMP=`date "+%Y"`
+export DATESTAMP=`date "+%Y-%m-%d"`
+export SHA1STAMP=`git rev-parse HEAD`
+
+# BROOKLYN_VERSION_BELOW
+export BROOKLYN_JAVADOC_CLASSPATH=$( mvn -f ../../pom.xml --projects :brooklyn-all dependency:build-classpath | grep -E -v '^\[[A-Z]+\]' )
+
+echo "building javadoc at $DATESTAMP from:
+$SOURCE_PATHS"
+
+javadoc -sourcepath $SOURCE_PATHS \
+  -public \
+  -d target/$JAVADOC_TARGET1_SUBPATH/ \
+  -subpackages "org.apache.brooklyn:io.brooklyn:brooklyn" \
+  -classpath "${BROOKLYN_JAVADOC_CLASSPATH}" \
+  -doctitle "Apache Brooklyn" \
+  -windowtitle "Apache Brooklyn" \
+  -notimestamp \
+  -overview javadoc-overview.html \
+  -header '<a href="/" class="brooklyn-header">Apache Brooklyn <div class="img"></div></a>' \
+  -footer '<b>Apache Brooklyn - Multi-Cloud Application Management</b> <br/> <a href="http://brooklyn.io/" target="_top">brooklyn.io</a>. Apache License. &copy; '$YEARSTAMP'.' \
+2>&1 1>/dev/null | tee target/javadoc.log
+
+if ((${PIPESTATUS[0]})) ; then echo ; echo ; echo "wARNING: javadoc process exited non-zero" ; echo ; echo ; fi
+echo ; echo
+
+if [ ! -f target/$JAVADOC_TARGET1_SUBPATH/org/apache/brooklyn/api/entity/Entity.html ]; then echo "ERROR: missing expected content. Are the paths right?" ; exit 1 ; fi
+
+if [ ! -z "`grep warnings target/javadoc.log`" ] ; then echo "WARNINGs occurred during javadoc build. See target/javadoc.log for more information." ; fi
+
+sed -i.bak s/'${DATESTAMP}'/"${DATESTAMP}"/ target/$JAVADOC_TARGET1_SUBPATH/overview-summary.html
+sed -i.bak s/'${SHA1STAMP}'/"${SHA1STAMP}"/ target/$JAVADOC_TARGET1_SUBPATH/overview-summary.html
+rm target/$JAVADOC_TARGET1_SUBPATH/*.bak
+
+if [ -d ../_site/guide/$JAVADOC_TARGET2_SUBPATH/ ] ; then
+  echo "API directory detected in test structure _site, copying docs there so they can be served with serve-site.sh"
+  cp -r target/$JAVADOC_TARGET1_SUBPATH/* ../_site/guide/$JAVADOC_TARGET2_SUBPATH/
+fi
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/quick-make-few-javadoc.sh
----------------------------------------------------------------------
diff --git a/_build/quick-make-few-javadoc.sh b/_build/quick-make-few-javadoc.sh
new file mode 100755
index 0000000..e78d79b
--- /dev/null
+++ b/_build/quick-make-few-javadoc.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+export BROOKLYN_JAVADOC_SOURCE_PATHS="../../api/src/main/java"
+echo LIMITING build to $BROOKLYN_JAVADOC_SOURCE_PATHS for speed
+./make-javadoc.sh
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/serve-public-site.sh
----------------------------------------------------------------------
diff --git a/_build/serve-public-site.sh b/_build/serve-public-site.sh
new file mode 100755
index 0000000..70c6470
--- /dev/null
+++ b/_build/serve-public-site.sh
@@ -0,0 +1 @@
+ruby -run -e httpd ${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public} -p 4000

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/serve-site.sh
----------------------------------------------------------------------
diff --git a/_build/serve-site.sh b/_build/serve-site.sh
new file mode 100755
index 0000000..69cf70d
--- /dev/null
+++ b/_build/serve-site.sh
@@ -0,0 +1 @@
+ruby -run -e httpd _site/ -p 4000

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball.md
----------------------------------------------------------------------
diff --git a/_build/tests/jsonball/test_jsonball.md b/_build/tests/jsonball/test_jsonball.md
new file mode 100644
index 0000000..1dcc572
--- /dev/null
+++ b/_build/tests/jsonball/test_jsonball.md
@@ -0,0 +1,18 @@
+---
+layout: website-normal
+title: Test Jsonball
+---
+
+{% jsonball j from data { "a": "data" } %}
+from data: j.a is {{ j.a }} (should be data)
+
+{% assign v = '{ "a": "var" }' %}
+{% jsonball j from var v %}
+from var: j.a is {{ j.a }} (should be var)
+
+{% jsonball j from file test_jsonball_file.json %}
+from file: j.a is {{ j.a }} (should be file)
+
+{% jsonball j from page test_jsonball_page.json %}
+from page: j.a is {{ j.a }} (should be page)
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball_file.json
----------------------------------------------------------------------
diff --git a/_build/tests/jsonball/test_jsonball_file.json b/_build/tests/jsonball/test_jsonball_file.json
new file mode 100644
index 0000000..e566a20
--- /dev/null
+++ b/_build/tests/jsonball/test_jsonball_file.json
@@ -0,0 +1 @@
+{ "a": "file" }

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball_page.json
----------------------------------------------------------------------
diff --git a/_build/tests/jsonball/test_jsonball_page.json b/_build/tests/jsonball/test_jsonball_page.json
new file mode 100644
index 0000000..bb08f70
--- /dev/null
+++ b/_build/tests/jsonball/test_jsonball_page.json
@@ -0,0 +1,2 @@
+{% assign x = "page" %}
+{ "a": "{{ x }}" }

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/toc.json
----------------------------------------------------------------------
diff --git a/_build/tests/jsonball/toc.json b/_build/tests/jsonball/toc.json
new file mode 100644
index 0000000..cd01e1a
--- /dev/null
+++ b/_build/tests/jsonball/toc.json
@@ -0,0 +1,6 @@
+[
+{ "title": "Test Jsonball",
+  "file":  "test_jsonball.html" },
+{ "title": "Home",
+  "file":  "{{ site.path.guide }}/index.html" }
+]

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_config.yml
----------------------------------------------------------------------
diff --git a/_config.yml b/_config.yml
new file mode 100644
index 0000000..7b634b2
--- /dev/null
+++ b/_config.yml
@@ -0,0 +1,54 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#  http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+encoding: utf-8
+markdown: kramdown
+
+# where this will publish
+url_root: http://0.0.0.0:4000
+
+# absolute base directories where things will land on the server
+path:
+  style: /style
+  guide: /guide
+  website: /website
+  v: /v
+
+# Use local copies of dependencies in dev build (switched to remote using URLs for prod build)
+dependency_mode: local
+dependency_urls:
+  bootstrap.css: https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css
+  bootstrap.js: https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js
+  jquery.js: https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js
+
+root_menu_page: /website/index.md
+
+# These files should not be included in the final build (in addition to _* contents)
+exclude: ['/Gemfile*','/README.md']
+
+sass:
+    sass_dir: style/css
+
+brooklyn-stable-version: 0.8.0-incubating
+
+brooklyn-version: 0.9.0-SNAPSHOT # BROOKLYN_VERSION
+brooklyn-snapshot-git-branch: master   # if line above is SNAPSHOT this should point to corresponding git branch (e.g. master, 0.4)
+
+# This is auto-detected, but you can override it if needed.
+# git-branch: master

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/before-begin.include.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/before-begin.include.md b/_extra/big_examples/before-begin.include.md
new file mode 100644
index 0000000..5170c64
--- /dev/null
+++ b/_extra/big_examples/before-begin.include.md
@@ -0,0 +1,56 @@
+{% include fields.md %}
+
+## Before You Begin
+
+To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven`` (v3) installed.
+
+### Installing Brooklyn
+
+(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.)
+
+{% if SNAPSHOT %}
+
+First, grab a copy of the Brooklyn snapshot distribution you wish to use from 
+[the maven repository]({{ this_dist_url_list }})
+(or build it yourself following instructions [here]({{ site.path.guide }}/dev/build/)),
+unpack it to your favourite location (e.g. `$(pwd)`), 
+and export `BROOKLYN_HOME`:
+
+{% highlight bash %}
+% curl -L -o brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz "{{ this_dist_url_tgz }}"
+% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
+% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
+{% endhighlight %}
+
+{% else %}
+
+Grab a copy of the Brooklyn distribution and set up `BROOKLYN_HOME`:
+
+{% highlight bash %}
+% curl -LO "{{ this_dist_url_tgz }}"
+% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz
+% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/
+{% endhighlight %}
+
+{% endif %}
+
+### Installing the Examples 
+
+Grab a copy of the brooklyn-examples source code and build it with Maven:
+
+{% highlight bash %}
+% git clone https://github.com/apache/incubator-brooklyn.git
+% cd incubator-brooklyn/examples
+% mvn clean install
+{% endhighlight %}
+
+{% if SNAPSHOT %}
+Please note, these instructions are for a SNAPSHOT release of Brooklyn,
+so proceed with caution. 
+For the latest stable version, go [here](/meta/versions.html). 
+{% endif %}
+
+For more information on ways to download Brooklyn please
+see the [download page]({{site.path.guide}}/start/download.html).
+For more information on the Brooklyn CLI and launching apps,
+please visit [this section of the user guide]({{site.path.guide}}/use/guide/management/index.html#cli).

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png b/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png
new file mode 100644
index 0000000..c34217f
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-geoscaling-details.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/console-geoscaling-details.png b/_extra/big_examples/global-web-fabric/console-geoscaling-details.png
new file mode 100644
index 0000000..f47226a
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-geoscaling-details.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-map-w700.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/console-map-w700.png b/_extra/big_examples/global-web-fabric/console-map-w700.png
new file mode 100644
index 0000000..af353a9
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-map-w700.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-map.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/console-map.png b/_extra/big_examples/global-web-fabric/console-map.png
new file mode 100644
index 0000000..cd0f811
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-map.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png b/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png
new file mode 100644
index 0000000..33c811d
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png b/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png
new file mode 100644
index 0000000..4e743e3
Binary files /dev/null and b/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png differ

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/index.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/global-web-fabric/index.md b/_extra/big_examples/global-web-fabric/index.md
new file mode 100644
index 0000000..a8c373a
--- /dev/null
+++ b/_extra/big_examples/global-web-fabric/index.md
@@ -0,0 +1,378 @@
+---
+layout: website-normal
+title: Global Web Fabric
+toc: /guide/toc.json
+---
+
+This example shows how to build a multi-site web application *fabric*
+with DNS configured on the front-end to combine the sites,
+routing users to the location closest to them.
+
+It can combine with the [Simple Web Cluster](../webcluster) example
+or the [Portable Cloud Foundry](https://github.com/cloudsoft/brooklyn-cloudfoundry) example,
+but does not assume knowledge of either of these.
+
+{% readj ../before-begin.include.md %}
+
+Now, go to this particular example's directory:
+
+{% highlight bash %}
+% cd global-web-fabric
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``global-web-fabric`` contains the code used
+in this example under ``src/main/java``.
+
+
+### Setting Up Geographic DNS
+
+This example uses [geoscaling.com](http://www.geoscaling.com) to provide **free** geographic-dependent DNS services.
+This will forward a domain name of your choice to various IPs depending on a script,
+e.g. computing the nearest IP based on latitude and longitude of the requester and the targets.
+Brooklyn will automatically generate and update this script, but you do need to 
+create and configure a Geoscaling account:
+
+ 1. Create the free account [here](https://www.geoscaling.com/dns2/?module=register).
+ 1. Click the link in the email you receive.
+ 1. Enter the domain name you wish to use into geoscaling (see below).
+
+The simplest domain name to choose is something unique under `geopaas.org`, e.g. `yourname.geopaas.org`,
+which we have already configured for Geoscaling to manage.
+If you are using your own domain name, 
+set its nameservers as advised by geoscaling (e.g. `ns{1,2,3,4}.geoscaling.com`).
+
+Next we need to supply this information to Brooklyn at runtime.
+The simplest way is to create or add the following fields to `~/.brooklyn/brooklyn.properties`:
+
+{% highlight bash %}
+brooklyn.geoscaling.username=yourname
+brooklyn.geoscaling.password=s3cr3t
+brooklyn.geoscaling.primaryDomain=yourname.geopaas.org
+{% endhighlight %}
+
+Replace the values of these fields as appropriate, of course!
+You can, if you prefer, supply (or override) these values in your Brooklyn application.
+
+
+### Setting Up the Locations Database
+
+In order to generate the "closest-IP" script,
+Brooklyn needs a way to find out the latitude and longitude of the
+servers you are using.
+The simplest way to do this is do download the free GeoCityLite binary flatfile 
+from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/#Downloads),
+unpack it, and copy it to `~/.brooklyn/GeoLite2-City.mmdb`.
+
+This will be picked up automatically if it is installed.
+You can instead specify to use an online lookup service, such as 
+[utrace.de](http://www.utrace.de) by specifying
+`-Dorg.apache.brooklyn.core.location.geo.HostGeoLookup=UtraceHostGeoLookup`;
+but note this has a cap of 100 per day.
+
+This information is also used to display locations on the map
+in the Brooklyn dashboard.
+Note however that these free services are not 100% accurate;
+they are handy for dev/test but in a production system
+you may wish to specify the geographical information manually in your application,
+or purchase a commercial locations-database subscription.
+
+
+## The Code
+
+Now let's start writing our application.
+The heavy lifting will be done by off-the-shelf Brooklyn classes:
+
+ * `DynamicFabric` will create the entity specified by `factory` in each location it is given
+ * `GeoscalingDnsService` monitors children of a specified entity (the `DynamicFabric`) 
+   and adds them as DNS targets for the region they are in  
+
+First, however, let's create the Java class -- call it `GlobalWebFabricExample`.
+This will extend the Brooklyn `AbstractApplication`:
+
+{% highlight java %}
+package brooklyn.demo;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import org.apache.brooklyn.core.entity.AbstractApplication;
+
+public class GlobalWebFabricExample extends AbstractApplication {
+    @Override
+    public void init() {
+         // TODO create our app!
+    }
+}
+{% endhighlight %}
+
+### The Fabric
+
+The `DynamicFabric` by default has no knowledge of what it will build,
+other than the `factory` it is given to create an entity in each region.
+We'll use the class `ElasticJavaWebAppService.Factory` which creates
+an elastic Java Web App service,
+such as the `ControlledDynamicWebAppCluster` used in the
+[Simple Web Cluster](../webcluster) example, if deploying to VMs,
+or perhaps a `CloudFoundryJavaWebAppCluster` if deploying to a Cloud Foundry location
+(see [brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry)).
+
+{% highlight java %}
+        DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+                .displayName("Web Fabric")
+                .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+                .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH));
+{% endhighlight %}
+
+Here we have specified the WAR to use with `configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)`.
+The war configuration used in the previous example is only available on web-aware entities;
+configuration specified with a ConfigKey can be done on any entity,
+and is inherited at runtime, so this provides a useful way to specify the WAR to use
+even though the web-aware entities are only constructed at runtime.
+
+
+### Stitching the Fabric together with DNS
+
+To stitch these together seamlessly, another entity will run a policy
+which collects the public-facing IP address of each cluster created by the fabric,
+as it comes online, by watching for `SERVICE_UP` sensors.
+First, however, let's make sure any load-balancer proxies (e.g. nginx) in these clusters
+are listening on port 80:
+
+{% highlight java %}
+        DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+                .displayName("Web Fabric")
+                .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+                .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)
+                .configure(AbstractController.PROXY_HTTP_PORT, PortRanges.fromInteger(80)));
+{% endhighlight %}
+
+Let's now define the Geoscaling entity which does the stitching.
+We need to supply the username, password, and primaryDomainName for Geoscaling;
+we'll take this from the `brooklyn.properties` file mentioned above.
+We'll also specify a `smartSubdomainName`, to use Geoscaling's facility for
+lightweight sub-domains to prevent DNS caching and multiple instances of our application
+from confusing us -- e.g. `brooklyn-1234.yourname.geopaas.org`.
+
+{% highlight java %}
+        StringConfigMap config = getManagementContext().getConfig();
+        
+        GeoscalingDnsService geoDns = addChild(EntitySpec.create(GeoscalingDnsService.class)
+                .displayName("GeoScaling DNS")
+                .configure("username", checkNotNull(config.getFirst("brooklyn.geoscaling.username"), "username"))
+                .configure("password", checkNotNull(config.getFirst("brooklyn.geoscaling.password"), "password"))
+                .configure("primaryDomainName", checkNotNull(config.getFirst("brooklyn.geoscaling.primaryDomain"), "primaryDomain")) 
+                .configure("smartSubdomainName", "brooklyn"));
+{% endhighlight %}
+
+Lastly we need to tell this instance what entity it should monitor
+for children to include as targets:
+
+{% highlight java %}
+        geoDns.setTargetEntityProvider(webFabric);
+{% endhighlight %}
+
+
+
+### Cloud Foundry and other PaaS Targets
+
+At this point our core application is ready, and can be deployed to AWS or another VM cloud.
+This may take between 15 and 30 minutes to run,
+mainly spent downloading software
+(unless of course you specify a pre-configured `imageId` which contains the software).
+
+A quicker alternative is to deploy to a Java Web App platform-as-a-service
+such as Cloud Foundry.  A major advantage here is that they can provision very quickly,
+in a matter of seconds.  Code for this can be found in the 
+[brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry), 
+along with an example global-web-fabric app.
+
+
+### Imports
+
+Your imports should look as follows:
+
+{% highlight java %}
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import org.apache.brooklyn.api.entity.EntitySpec;
+import org.apache.brooklyn.config.StringConfigMap;
+import org.apache.brooklyn.core.entity.AbstractApplication;
+import org.apache.brooklyn.core.entity.Attributes;
+import org.apache.brooklyn.entity.dns.geoscaling.GeoscalingDnsService;
+import org.apache.brooklyn.entity.group.DynamicFabric;
+import org.apache.brooklyn.entity.proxy.AbstractController;
+import org.apache.brooklyn.entity.webapp.ElasticJavaWebAppService;
+import PortRanges;
+{% endhighlight %}
+
+
+### Use of main method (optional)
+
+In this example, we will use the brooklyn CLI launcher. However, it is possible to write your own main method.
+
+The following static constants are assumed (most of these as in the [Simple Web Cluster](../webcluster) example and others): 
+
+ * `WAR_PATH`, pointing to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+ * `DEFAULT_LOCATIONS`, containing a string spec of the locations to deploy to if none are supplied on the command-line;
+   for this example `localhost` will frequently not work unless Geoscaling can see it 
+   (i.e. it has a public IP and appropriate firewall settings)
+
+The code (which can safely be omitted) is as follows:
+
+{% highlight java %}
+import org.apache.brooklyn.launcher.BrooklynLauncher;
+import org.apache.brooklyn.util.CommandLineUtil;
+
+import com.google.common.base.Joiner;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+
+// class definition, and rest of class goes here...
+
+    public static final Logger log = LoggerFactory.getLogger(GlobalWebFabricExample.class);
+    
+    // points to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+    public static final String WAR_PATH = "classpath://hello-world-webapp.war";
+    
+    // locations to deploy to if none are supplied on the command-line; for this example `localhost` will 
+    // frequently not work unless Geoscaling can see it (i.e. it has a public IP and appropriate firewall settings)
+    static final List<String> DEFAULT_LOCATIONS = ImmutableList.of(
+            "aws-ec2:eu-west-1",
+            "aws-ec2:ap-southeast-1",
+            "aws-ec2:us-west-1" );
+        
+    public static void main(String[] argv) {
+        List<String> args = Lists.newArrayList(argv);
+        String port =  CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
+        String locations = CommandLineUtil.getCommandLineOption(args, "--locations", Joiner.on(",").join(DEFAULT_LOCATIONS));
+
+        BrooklynLauncher launcher = BrooklynLauncher.newInstance()
+                .application(EntitySpec.create(StartableApplication.class, GlobalWebFabricExample.class).displayName("Brooklyn Global Web Fabric Example"))
+                .webconsolePort(port)
+                .locations(Arrays.asList(locations))
+                .start();
+        
+        Entities.dumpInfo(app);
+    }
+{% endhighlight %}
+
+
+
+## Running the Example
+
+Now let's run this example.
+
+{% highlight bash %}
+${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.GlobalWebFabricExample \
+--location jclouds:aws-ec2:eu-west-1,jclouds:aws-ec2:ap-southeast-1,jclouds:aws-ec2:us-west-1 
+{% endhighlight %}
+
+The management web console will start,
+followed by the web-app services in the locations specified
+creating the VM's as needed.
+Let's look at the management web console, on port 8081:
+
+[![Web Console Map](console-map-w700.png "Web Console Map")](console-map.png) 
+
+This shows the targets (e.g. Ireland (AWS eu-west-1),  Singapore (AWS ap-southeast-1),  and California (AWS us-west-1)).
+This also shows the current status of the application.
+
+Navigating to the "applications" tab, we can view sensors, invoke effectors, control policies,
+and track activity, 
+for instance if a cluster is slow to start and you want to find out what is going on
+(you'll find additional information in the `brooklyn.log` file).
+Let's drill down on the Geoscaling DNS entity's sensors:
+
+[![Web Console Geoscaling Details](console-geoscaling-details-w700.png "Web Console Geoscaling Details")](console-geoscaling-details.png)
+
+Here we see it has chosen `brooklyn-vOZ7b4BL.martincloudsoft.geopaas.org` as the geo-load-balanced domain name.
+(Yours will be under `yourname.geopaas.org`, unless you chose a different domain earlier.)
+We can also see the hosts it is forwarding to, one for each cluster, corresponding to the
+children of the Web Fabric (propagated from the nginx hostnames, in the case of the ControlledDynamicWebAppCluster instances).
+
+
+### Checking the Web App
+
+Once Geoscaling reports at least one target, you should be able to access it on the geo-load-balanced domain name:
+
+[![Our Deployed Application](geopaas-deployed-app-w700.png "Our Deployed Application")](geopaas-deployed-app.png)
+
+Under the covers you are being routed to one of the clusters that has been deployed --
+whichever one is closest to you.
+(Due to DNS caching, at your machine or your ISP, clusters which come online after your first lookup
+will not be picked up until TTL expires, typically 10m, although often more if DNS services don't respect TTL.)
+
+
+### Checking DNS Information
+
+Let's find out exactly where we were routed:
+
+{% highlight bash %}
+% dig brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> brooklyn-csgFCzTm.geopaas.org
+
+;; QUESTION SECTION:
+;brooklyn-csgFCzTm.geopaas.org. IN      A
+
+;; ANSWER SECTION:
+brooklyn-csgFCzTm.geopaas.org. 120 IN   CNAME   ec2-46-137-138-4.eu-west-1.compute.amazonaws.com.
+ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. 215 IN A 46.137.138.4
+{% endhighlight %}
+
+This was run from Scotland so it seems a sensible choice.
+(Some portions of the output from `dig` have been removed for readability.)
+
+We can get more information by looking at the TXT records: 
+
+{% highlight bash %}
+% dig +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+...
+
+geopaas.org.            86400   IN      NS      ns1.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns2.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns3.geoscaling.com.
+geopaas.org.            86400   IN      NS      ns4.geoscaling.com.
+;; Received 133 bytes from 199.249.112.1#53(a2.org.afilias-nst.info) in 45 ms
+
+brooklyn-csgFCzTm.geopaas.org. 300 IN   TXT     "Request from [54,-2]-(GB) directed to Ireland (IE)"
+brooklyn-csgFCzTm.geopaas.org. 300 IN   TXT     "GeoScaling config auto-updated by Brooklyn 2012-04-26 12:27:25 UTC"
+;; Received 189 bytes from 80.87.128.195#53(ns3.geoscaling.com) in 60 ms
+{% endhighlight %}
+
+
+## Next Steps
+
+This example has shown how to create a multi-region fabric, using the abstractions from
+[jclouds](http://jclouds.org) under the covers to make it easy to access different hosting providers
+simultaneously, and using higher-level abstractions in Brooklyn to mix PaaS systems with
+bare-VM (or even bare-metal, if you specify fixed IPs).
+
+This is meant as just the beginning however.  
+Here are some questions to think about and code challenges to give you a steer for what to explore next.
+
+
+ 1. The routines used at Geoscaling optimize for latency between the user and the location of the web-cluster.
+    What other strategies might be used?  Cost?  Compliance?  How would you code these?
+    
+ 2. This example ignores data, but you clearly can't do that in the real world.
+    When big-data is involved, does this introduce other considerations for optimizing geo-location?
+    
+ 3. Add a data tier to this system, such as MySQL or Mongo, or even Hadoop.
+    You might start with a single instance or cluster,
+    but the real fun starts with a fabric, and defining the synchronization/replication strategies
+    between the different clusters.
+    This isn't for the faint-hearted, but whatever you create will certainly be of interest
+    to people in the Brooklyn community.
+    Please [let us know]({{ site.path.guide }}/meta/contact.html) what you've built!

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/index.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/index.md b/_extra/big_examples/index.md
new file mode 100644
index 0000000..b5789a3
--- /dev/null
+++ b/_extra/big_examples/index.md
@@ -0,0 +1,18 @@
+---
+layout: website-normal
+title: Examples
+toc: /guide/toc.json
+---
+
+We currently have the following examples on the site:
+
+{% capture ltocs %}{% readj toc.json %}{% endcapture %}
+{% jsonball ltoc from var ltocs %}
+
+{% for x in ltoc %}
+* <a href="{{ x.file }}">{{ x.title }}</a>
+{% endfor %} 
+
+There are examples in the code also, just check out the examples/ project.
+
+**Have one of your own?**  [Add it here!]({{site.path.guide}}/dev/tips/update-docs.html)

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/messaging/index.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/messaging/index.md b/_extra/big_examples/messaging/index.md
new file mode 100644
index 0000000..f33cecc
--- /dev/null
+++ b/_extra/big_examples/messaging/index.md
@@ -0,0 +1,181 @@
+---
+layout: website-normal
+title: Publish-Subscribe Messagiung
+toc: /guide/toc.json
+---
+
+This example shows how a simple messaging application can be build
+in brooklyn, starting with configuring and launching a broker. For
+these examples we will use the Apache [Qpid](http://qpid.apache.org/)
+Java AMQP message broker and clients using the
+[JMS](http://docs.oracle.com/javaee/6/tutorial/doc/bnceh.html) API.
+
+{% readj ../before-begin.include.md %}
+
+Now, go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-messaging-pubsub
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-messaging-pubsub`` includes a deployment
+descriptor for our example messaging application and simple _Publish_
+and _Subscribe_ JMS test client scripts.
+
+## Single Broker
+
+The first example will include a Qpid broker, which we will customize
+to use the Oracle [BDB](http://www.oracle.com/technetwork/products/berkeleydb/overview/index.html)
+message store as an example of a typical production setup. We will
+also create a queue for use by a pair of test clients.
+
+The ``QpidBroker`` entity is created like this, which uses the
+default configuration, specifying only the AMQP port and creates
+no queues or topics:
+
+{% highlight java %}
+public class StandaloneQpidBrokerExample extends AbstractApplication {
+    @Override
+    public void init() {
+        // Configure the Qpid broker entity
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672));
+    }
+}
+{% endhighlight %}
+
+To install the custom configuration files and extra libraries for
+BDB, we specify some files to copy to the broker installation, using
+the ``runtimeFiles`` property. These files should be available in
+the classpath of the application when it is running, usually by
+copying them to the ``src/main/resources`` directory. For example,
+here we copy a custom XML configuration file and a new password
+file:
+
+{% highlight java %}
+        final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml";
+        final String PASSWD_PATH = "classpath://passwd";
+
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672)
+    	        .configure("amqpVersion", AmqpServer.AMQP_0_10)
+    	        .configure("runtimeFiles", ImmutableMap.builder()
+    	                .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH)
+    	                .put(QpidBroker.PASSWD, PASSWD_PATH)
+    	                .build()));
+{% endhighlight %}
+
+Finally, we come to the complete configuration of our ``QpidBroker``
+entity using the BDB store. The additional properties here specify
+the AMQP version and that a queue named _testQueue_ should be created
+on startup.
+
+{% highlight java %}
+        final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml";
+        final String PASSWD_PATH = "classpath://passwd";
+        final String QPID_BDBSTORE_JAR_PATH = "classpath://qpid-bdbstore-0.14.jar";
+        final String BDBSTORE_JAR_PATH = "classpath://je-5.0.34.jar";
+
+    	QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class)
+    	        .configure("amqpPort", 5672)
+    	        .configure("amqpVersion", AmqpServer.AMQP_0_10)
+    	        .configure("runtimeFiles", ImmutableMap.builder()
+    	                .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH)
+    	                .put(QpidBroker.PASSWD, PASSWD_PATH)
+    	                .put("lib/opt/qpid-bdbstore-0.14.jar", QPID_BDBSTORE_JAR_PATH)
+    	                .put("lib/opt/je-5.0.34.jar", BDBSTORE_JAR_PATH)
+    	                .build())
+    	        .configure("queue", "testQueue"));
+{% endhighlight %}
+
+
+### Running the Example
+
+You can run the example as follows:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn -v launch --app brooklyn.demo.StandaloneQpidBrokerExample --location localhost
+{% endhighlight %}
+
+Now, visit the Brooklyn web console on port 8081 (for pre 0.6 releases,
+use the credentials admin/password). This allows you to view the Brooklyn 
+entities and their current state for debugging.
+
+Note that the installation may take some time, because the default
+deployment downloads the software from the official repos.  You can
+monitor start-up activity for each entity in the ``Activity`` pane
+in the management console, and see more detail by tailing the log
+file (``tail -f brooklyn.log``).
+
+After starting up, the demo script should display a summary of all
+the Brooklyn managed entities and their attributes. This will show
+both the Qpid broker and its child entity, the queue _testQueue_
+which was created at startup. The queue entity has sensors that
+monitor the depth of unread messages, which you can check while
+running the test client scripts later.
+
+If the ``-v`` flag is passed to the startup command, all configured
+entity and sensor details will be output. This includes the broker URL,
+which is used to configure JMS clients to connect to this broker.
+This URL can also be viewed as a sensor attribute in the web console,
+named _broker.url_.
+
+This sensor is common to _all_ messaging brokers that Brooklyn
+provides, and is usually accessed by applications to allow them to
+provide it as a parameter to other entities, as shown in the code
+fragment below.
+
+{% highlight java %}
+String url = broker.getAttribute(MessageBroker.BROKER_URL)
+{% endhighlight %}
+
+Using the URL the demo script printed, you can run the test ``Subscribe``
+and then ``Publish`` classes, to send messages using the broker. Simply
+run the commands in another window, with the provided URL as the
+only argument. Note that the URLs may be different to those printed
+below, and that any unquoted ``&`` characters *must* be escaped,
+if present.
+
+{% highlight bash %}
+% URL="amqp://guest:guest@/localhost?brokerlist='tcp://localhost:5672'"
+% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Subscribe ${URL}
+% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Publish ${URL}
+{% endhighlight %}
+
+In the _Publish_ window you should see a log message every time a
+message is sent, like this:
+
+{% highlight bash %}
+2012-05-02 14:04:38,521 INFO  Sent message 65
+2012-05-02 14:04:39,522 INFO  Sent message 66
+{% endhighlight %}
+
+Similarly, the _Subscribe_ windows should log on reciept of these
+messages, as follows:
+
+{% highlight bash %}
+2012-05-02 14:04:32,522 INFO  got message 41 test message 41
+2012-05-02 14:04:33,523 INFO  got message 42 test message 42
+{% endhighlight %}
+
+### Cloud Deployment
+
+With appropriate setup (as described
+[here]({{ site.path.guide }}/use/guide/management/index.html#startup-config))
+this can also be deployed to your favourite cloud, let's pretend
+it's Amazon Ireland, as follows:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.StandaloneQpidBrokerExample --location aws-ec2:eu-west-1
+{% endhighlight %}
+
+If you encounter any difficulties, please
+[tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best
+to help.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/nosql-cassandra/cassandra.include.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/nosql-cassandra/cassandra.include.md b/_extra/big_examples/nosql-cassandra/cassandra.include.md
new file mode 100644
index 0000000..a4d1643
--- /dev/null
+++ b/_extra/big_examples/nosql-cassandra/cassandra.include.md
@@ -0,0 +1,282 @@
+      
+{% readj ../before-begin.include.md %}
+
+## Simple Cassandra Cluster
+
+Go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-nosql-cluster
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-nosql-cluster`` includes several deployment descriptors
+for deploying and managing Cassandra, under ``src/main/java``.
+
+The simplest of these, ``SimpleCassandraCluster``, will start a Cassandra cluster. The code is:
+
+{% highlight java %}
+public class SimpleCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraCluster.class)
+        .configure(CassandraCluster.INITIAL_SIZE, 1)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn"));
+  }
+}
+{% endhighlight %}
+
+To run that example on localhost (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase):
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \
+  --location localhost
+{% endhighlight %}
+
+Then visit the Brooklyn console on ``localhost:8081``.
+Note that the installation may take some time, because the default deployment downloads the software from
+the official repos.  You can monitor start-up activity for each entity in the ``Activity`` pane in the management console,
+and see more detail by tailing the log file (``tail -f brooklyn.log``).
+
+This example runs successfully on a local machine because ``INITIAL_SIZE`` is configured to just one node
+(a limitation of Cassandra is that every node must be on a different machine/VM).
+If you want to run with more than one node in the cluster, you'll need to use a location 
+that either points to multiple existing machines or to a cloud provider where you can 
+provision new machines.
+
+With appropriate setup of credentials (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) 
+this example can also be deployed to your favourite cloud. Let's pretend it's Amazon US East, as follows: 
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \
+  --location aws-ec2:us-east-1
+{% endhighlight %}
+
+If you want more nodes in your cluster, you can either modify the deployment descriptor (i.e. change the ``INITIAL_SIZE`` value),
+or dynamically add more nodes by calling the ``resize`` effector through the web-console. 
+To do the latter, select cluster entity in the tree on the left, then click on the "effectors" tab, and invoke ``resize`` 
+with the desired number of nodes.
+
+
+### Testing your Cluster
+
+An easy way to test your cluster is to use the ``cassandra-stress`` command line tool.
+For example, run:
+
+{% highlight bash %}
+# Substitute the id below for your VM
+NODE_IDS=ec2-54-221-69-95.compute-1.amazonaws.com
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+	--nodes ${NODE_IDS} \
+    --replication-factor 1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation INSERT
+{% endhighlight %}
+
+This command will fire 10000 inserts at the cluster, via the nodes specified in the comma-separated node list. 
+If you change ``INSERT`` to ``READ``, it will read each of those 10000 values.
+
+
+## High Availability Cassandra Cluster
+
+Ready for something more interesting?  Try this:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.HighAvailabilityCassandraCluster \
+  --location aws-ec2:us-east-1
+{% endhighlight %}
+
+This launches the class ``HighAvailabilityCassandraCluster``,
+which launches a Cassandra cluster configured to replicate across availability zones.
+
+To give some background for that statement, in 
+[AWS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
+(and various other clouds), a region is a 
+separate geographic area, consisting of multiple isolated locations known as availability zones.
+To ensure high availability, the Cassandra cluster and thus the data should be spread across the 
+availability zones. Cassandra should be configured to ensure there is at least one replica in
+each availability zone. In 
+[Cassandra terminology](http://www.datastax.com/docs/1.1/cluster_architecture/replication)
+a region is normally mapped to a "datacenter" and an availability zone to a "rack".
+
+To be properly highly available, we need some automated policies to restart failed servers 
+and to replace unhealthy nodes. Brooklyn has these policies available out-of-the-box.
+To wire them up, the essential code fragment looks like this:
+
+{% highlight java %}
+public class HighAvailabilityCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraCluster.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 1)
+        .configure(CassandraCluster.ENABLE_AVAILABILITY_ZONES, true)
+        .configure(CassandraCluster.NUM_AVAILABILITY_ZONES, 3)
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "GossipingPropertyFileSnitch")
+        .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class)
+            .policy(PolicySpec.create(ServiceFailureDetector.class))
+            .policy(PolicySpec.create(ServiceRestarter.class)
+                .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED)))
+        .policy(PolicySpec.create(ServiceReplacer.class)
+            .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED)));
+  }
+}
+{% endhighlight %}
+
+This code is doing a lot and deserves some more detailed explanation:
+
+* The ``MEMBER_SPEC`` describes the configuration of the Cassandra nodes to be created in the cluster.
+  Assuming you're happy to use all the default thrift port etc, then the only configuration to add is
+  a couple of policies.
+* The ``ServiceFailureDetector`` policy watches the node's sensors, and generates
+  an ``ENTITY_FAILED`` event if the node goes down.
+* The ``ServiceRestarter`` policy responds to this failure-event
+  by restarting the node. Its default configuration is that: if a node does not come back up, or if it 
+  fails again within three minutes, then it will emit an ``ENTITY_RESTART_FAILED`` event.
+* Finally, the ``SERVICE_REPLACER`` policy on the cluster responds to this event by replacing the
+  entire VM. It sets up a new VM in the same location, and then tears down the faulty node.
+
+> *Troubleshooting:*
+
+> *In AWS, some availability zones can be constrained for particular instance sizes (see
+  [this bug report](https://github.com/brooklyncentral/brooklyn/issues/973)
+  If you get this error, the workaround is to specify explicitly the availability zones to use. 
+  This requires an additional line of code such as:*
+
+{% highlight java %}
+  .configure(AVAILABILITY_ZONE_NAMES, ImmutableList.of("us-east-1b", "us-east-1c", "us-east-1e"))
+{% endhighlight %}
+
+> *However, this prevents the blueprint from being truly portable. We're looking at fixing this issue.*
+
+
+## Wide Area Cassandra Cluster
+
+For critical enterprise use-cases, you'll want to run your Cassandra cluster across multiple regions, 
+or better yet across multiple cloud providers. This gives the highest level of availability for 
+the service.
+
+Try running:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \
+  --location "aws-ec2:us-east-1,aws-ec2:us-west-2"
+{% endhighlight %}
+
+This launches the class ``WideAreaCassandraCluster`` across two AWS regions.
+
+Cassandra provides some great support for this with the 
+[EC2MultiRegionSnitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication)
+The 
+[snitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication#snitches)
+maps IPs to racks and data centers; it defines how the nodes are grouped together within the overall 
+network topology. For wide-area deployments, it must also deal with when to use the private IPs 
+(within a region) and the public IPs (between regions).
+You'll need a more generic snitch if you're going to span different cloud providers.
+Brooklyn has a custom MultiCloudSnitch that we're looking to contribute back to Cassandra.
+
+The important piece of code in ``WideAreaCassandraCluster`` is:
+
+{% highlight java %}
+public class WideAreaCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraFabric.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 2) // per location
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch")
+        .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://org/apache/brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar"));
+  }
+}
+{% endhighlight %}
+
+The code below shows the wide-area example with the high-availability policies from the previous section also configured:
+
+{% highlight java %}
+public class WideAreaCassandraCluster extends AbstractApplication {
+  public void init() {
+    addChild(EntitySpec.create(CassandraFabric.class)
+        .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")
+        .configure(CassandraCluster.INITIAL_SIZE, 2) // per location
+        .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch")
+        .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://org/apache/brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar")
+        .configure(CassandraFabric.MEMBER_SPEC, EntitySpec.create(CassandraCluster.class)
+            .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class)
+                .policy(PolicySpec.create(ServiceFailureDetector.class))
+                .policy(PolicySpec.create(ServiceRestarter.class)
+                    .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED)))
+            .policy(PolicySpec.create(ServiceReplacer.class)
+                 .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED))));
+  }
+}
+{% endhighlight %}
+
+To run Cassandra across multiple clouds, try running:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \
+  --location "aws-ec2:us-east-1,google-compute-engine,rackspace-cloudservers-uk"
+{% endhighlight %}
+
+
+### Testing your Wide-Area Cluster
+
+You can again use the ``cassandra-stress`` command line tool to test the wide-area cluster.
+
+Note that the replication strategy (such as 
+[NetworkTopologyStrategy](http://www.datastax.com/docs/1.0/cluster_architecture/replication#networktopologystrategy)
+is specified when creating a 
+[keyspace](http://www.datastax.com/documentation/cassandra/1.2/webhelp/index.html#cassandra/configuration/configStorage_r.html).
+The example below specifies a minimum of 1 replica in each datacenter.
+
+To do updates against a node in a given availability zone:
+
+{% highlight bash %}
+NODE_IDS=<your node hostname>
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+    --nodes ${NODE_IDS} \
+    --replication-strategy NetworkTopologyStrategy \
+    --strategy-properties=us-east-1:1,us-west-2:1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation INSERT
+{% endhighlight %}
+
+To check that the same data is available from a different region, target the reads
+against an appropriate node:
+
+{% highlight bash %}
+NODE_IDS=<your node hostname>
+/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \
+    --nodes ${NODE_IDS} \
+    --replication-strategy NetworkTopologyStrategy \
+    --strategy-properties=us-east-1:1,us-west-2:1 \
+    --progress-interval 1 \
+    --num-keys 10000 \
+    --operation READ
+{% endhighlight %}
+
+To really test this, you may want to simulate the failure of a region first.
+You can kill the VMs or ``kill -9`` the processes. But remember that if Brooklyn policies are configured
+they will by default restart the processes automatically! You can disable the Brooklyn policies through 
+the brooklyn web-console (select the entity, go the policies tab, select the policy, and click "disable").
+
+
+## Putting it all together: CumulusRDF
+
+If you want to try this with a real example application using the Cassandra cluster, take a look at
+[CumulusRDF](https://code.google.com/p/cumulusrdf). There is an example Brooklyn application at:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.CumulusRDFApplication \
+  --location "aws-ec2:us-east-1"
+{% endhighlight %}
+
+
+## Contact us!
+
+If you encounter any difficulties or have any comments, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/nosql-cassandra/index.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/nosql-cassandra/index.md b/_extra/big_examples/nosql-cassandra/index.md
new file mode 100644
index 0000000..7e7948e
--- /dev/null
+++ b/_extra/big_examples/nosql-cassandra/index.md
@@ -0,0 +1,7 @@
+---
+layout: website-normal
+title: Cassandra Clusters
+toc: /guide/toc.json
+---
+
+{% readj cassandra.include.md %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/simple-web-cluster.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/simple-web-cluster.md b/_extra/big_examples/simple-web-cluster.md
new file mode 100644
index 0000000..2b08a37
--- /dev/null
+++ b/_extra/big_examples/simple-web-cluster.md
@@ -0,0 +1,9 @@
+---
+layout: website-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+<!-- file kept to preserve old links; remove when link not used -->
+
+{% readj webcluster/webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/toc.json
----------------------------------------------------------------------
diff --git a/_extra/big_examples/toc.json b/_extra/big_examples/toc.json
new file mode 100644
index 0000000..4bca3a1
--- /dev/null
+++ b/_extra/big_examples/toc.json
@@ -0,0 +1,13 @@
+[
+{ "title": "Elastic Web Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/webcluster/index.html" },
+{ "title": "Global Web Fabric",
+  "file":  "{{ site.path.guide }}/use/examples/global-web-fabric/index.html" },
+{ "title": "Whirr Hadoop Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/whirrhadoop/index.html" },
+{ "title": "Publish-Subscribe Messaging",
+  "file":  "{{ site.path.guide }}/use/examples/messaging/index.html" },
+{ "title": "Cassandra Cluster",
+  "file":  "{{ site.path.guide }}/use/examples/nosql-cassandra/index.html" }
+
+]

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/webcluster.md b/_extra/big_examples/webcluster.md
new file mode 100644
index 0000000..2b08a37
--- /dev/null
+++ b/_extra/big_examples/webcluster.md
@@ -0,0 +1,9 @@
+---
+layout: website-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+<!-- file kept to preserve old links; remove when link not used -->
+
+{% readj webcluster/webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster/index.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/webcluster/index.md b/_extra/big_examples/webcluster/index.md
new file mode 100644
index 0000000..99c6b36
--- /dev/null
+++ b/_extra/big_examples/webcluster/index.md
@@ -0,0 +1,7 @@
+---
+layout: website-normal
+title: Elastic Web Cluster
+toc: /guide/toc.json
+---
+
+{% readj webcluster.include.md %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster/webcluster.include.md
----------------------------------------------------------------------
diff --git a/_extra/big_examples/webcluster/webcluster.include.md b/_extra/big_examples/webcluster/webcluster.include.md
new file mode 100644
index 0000000..e135998
--- /dev/null
+++ b/_extra/big_examples/webcluster/webcluster.include.md
@@ -0,0 +1,124 @@
+      
+{% readj ../before-begin.include.md %}
+
+## Simple Web Server
+
+Go to this particular example's directory:
+
+{% highlight bash %}
+% cd simple-web-cluster
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``simple-web-cluster`` includes several deployment descriptors
+for rolling out a web application, under ``src/main/java``.
+
+
+
+The simplest of these, ``SingleWebServerExample``, starts JBoss on a single machine with a "Hello World" war deployed,
+with a single line:
+
+{% highlight java %}
+public class SingleWebServerExample extends AbstractApplication {
+    private static final String WAR_PATH = "classpath://hello-world-webapp.war";
+
+    @Override
+    public void init() {
+        addChild(EntitySpec.create(JBoss7Server.class)
+                .configure("war", WAR_PATH)
+                .configure("httpPort", 8080));
+    }
+}
+{% endhighlight %}
+
+You can run this as follows (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase):
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \
+  --location localhost
+{% endhighlight %}
+
+
+Then visit the webapp on port 8080, or the Brooklyn console on localhost:8081.
+Note that the installation may take some time, because the default deployment downloads the software from
+the official repos.  You can monitor start-up activity for each entity in the ``Activity`` pane in the management console,
+and see more detail by tailing the log file (``tail -f brooklyn.log``).
+
+With appropriate setup (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) 
+this can also be deployed to your favourite cloud, let's pretend it's Amazon Ireland, as follows: 
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \
+  --location aws-ec2:eu-west-1
+{% endhighlight %}
+
+
+## Elastic Three-Tier
+
+Ready for something more interesting?  Try this:
+
+{% highlight bash %}
+% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WebClusterDatabaseExample \
+  --location localhost
+{% endhighlight %}
+
+This launches the class ``WebClusterDatabaseExample`` (also described in the [walkthrough]({{ site.path.guide }}/start/walkthrough/index.html))
+which launches a pool of web-servers -- of size 1 initially,
+but manually configurable (if you stop the policy first, in the GUI, then use the ``resize`` effector) --
+with an Nginx load-balancer set up in front of them, and backed by a MySQL database.
+
+The essential code fragment looks like this:
+
+{% highlight java %}
+public class WebClusterDatabaseExample extends AbstractApplication {
+    public static final String WAR_PATH = "classpath://hello-world-sql-webapp.war";
+    
+    public static final String DB_SETUP_SQL_URL = "classpath://visitors-creation-script.sql";
+    
+    public static final String DB_TABLE = "visitors";
+    public static final String DB_USERNAME = "brooklyn";
+    public static final String DB_PASSWORD = "br00k11n";
+
+    @Override
+    public void init() {
+        MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
+                .configure("creationScriptUrl", DB_SETUP_SQL_URL));
+        
+        ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+                .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
+                        .configure("httpPort", "8080+")
+                        .configure("war", WAR_PATH)
+                        .configure(javaSysProp("brooklyn.example.db.url"), 
+                                formatString("jdbc:%s%s?user=%s\\&password=%s", 
+                                        attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
+        
+        web.getCluster().addPolicy(AutoScalerPolicy.builder().
+                        metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
+                        sizeRange(1, 5).
+                        metricRange(10, 100).
+                        build());
+    }
+}
+{% endhighlight %}
+
+You can, of course, try this with your favourite cloud, 
+tweak the database start script, or drop in your favourite WAR.
+
+
+## A Few Other Things
+
+The project includes variants of the examples shown here, 
+including alternative syntax (the `*Alt*` files), 
+and a web-only cluster (no database) in `WebClusterExample``.
+
+The webapp that is used is included under ``examples/hello-world-webapp``.
+
+You may wish to check out the [Global Web Fabric example]({{ site.path.guide }}/use/examples/global-web-fabric/) next.
+
+If you encounter any difficulties, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/brooklyn-gpg-public-key.asc
----------------------------------------------------------------------
diff --git a/_extra/brooklyn-gpg-public-key.asc b/_extra/brooklyn-gpg-public-key.asc
new file mode 100644
index 0000000..3b515a4
--- /dev/null
+++ b/_extra/brooklyn-gpg-public-key.asc
@@ -0,0 +1,21 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG/MacGPG2 v2.0.18 (Darwin)
+Comment: GPGTools - http://gpgtools.org
+
+mQENBFDsSLEBCAC2JxQHeXpL3oGN2IickcG9C49gkxIsws4hpasQModVipezrQi0
+9pLq4lkB01GgC2sfPH+XXE8rCpA9EL0e4wVA7JICz5AsLZAAJH91tKksL20tLMeU
+Yrbufaq1ga7ifk3JWhF4iwvkDMBKyCjrF173nI+2TwX2XfNTQpzoQGOL1bNvS4NZ
+AD9JeXGW2D996zHdSK+x3wVdY3cDECvVMuw61+5ytZrGNnyvaaWTl3lJUyydPXHQ
+5TXVtbQH5WgYCLPr4E95axJ0BoY8H+fEaG1Uax1a+xLumVWhiWNp7rMvmgcZXuJO
+fx+wXAIbRNlAHoJcdZ4NCReRxDIBQ+2HsU1zABEBAAG0bUJyb29rbHluIFByb2pl
+Y3QgKGJyb29rbHluLmlvKSAoS2V5IHVzZWQgdG8gYXV0aGVudGljYXRlIEJyb29r
+bHluIGFydGlmYWN0cykgPGJyb29rbHluLWRldkBncm91cHMuZ29vZ2xlLmNvbT6J
+AT8EEwECACkFAlDsSLECGy8FCQeGH4AHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIX
+gAAKCRANhinnSRLCsOdIB/4tUVShup2NHXJ9acCah8TuEN4GmN9dBiD9YsGW66SR
+/ptY0Gn9XExl2wbmQW+7TQg3QUGv8uffwYLtnMwnmCp/WwgE+uSnRmcENxa9GuTu
+PLlURKKGK0C9ljTAHwXtPcIYxPNN3BT4VB56ME1DTBRCgEvudaNSANs8/kT88kE2
+eMC7x0Uo3/P38Ob8XSOfR8c6G6nSz6jILcRBXZTPNNK4svyqF5XHIru65d3/0+mr
+bpfcDLcUQYms0MpPmO1RCHLZWwJLsPUIxNwGGnKJc8/RNEvQinK+Ap0cf+PGUQSX
+PhB6Z81ROFIVToEVZslgSiL+u4Tc7zXDfDQDY4HeLY2t
+=w/CG
+-----END PGP PUBLIC KEY BLOCK-----

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/deploying-yaml.md
----------------------------------------------------------------------
diff --git a/_extra/deploying-yaml.md b/_extra/deploying-yaml.md
new file mode 100644
index 0000000..73010dd
--- /dev/null
+++ b/_extra/deploying-yaml.md
@@ -0,0 +1,39 @@
+---
+title: Deploying YAML Blueprints
+layout: page
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Once you've [written a YAML blueprint](creating-yaml.md), there are several ways to deploy it.
+These insructions assume you have [installed]({{ site.url }}/use/guide/quickstart/) Brooklyn.
+You can then:
+
+- Supply the YAML blueprint file on the CLI when launching the server:
+
+{% highlight bash %}
+$ brooklyn launch --app ./blueprint.yaml
+{% endhighlight %}
+
+
+Or, assuming you've launched a server already 
+(usually on [http://127.0.0.1/](http://127.0.0.1/) unless you've 
+configured security in [`brooklyn.properties`](/use/guide/quickstart/brooklyn.properties)),
+you can:
+
+- Curl it to the Brooklyn REST API:
+
+{% highlight bash %}
+$ curl -T ./blueprint.yaml -X POST http://localhost:8081/v1/applications
+{% endhighlight %}
+
+You may also need a `-H "Content-Type: application/yaml"` depending on type configuration.
+(Not usually for this, but often for other calls.)
+
+- In the web-console, select the "YAML" tab in the "Add Application" wizard:
+
+[![Web Console](web-console-yaml-700.png "YAML via Web Console")](web-console-yaml.png)
+
+
+- The web-console also has an interactive "REST API" page,
+  where you can paste the YAML for uploading into the `POST` to `/v1/applications`.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/highlevel1.md
----------------------------------------------------------------------
diff --git a/_extra/highlevel1.md b/_extra/highlevel1.md
new file mode 100644
index 0000000..3dfafb4
--- /dev/null
+++ b/_extra/highlevel1.md
@@ -0,0 +1,50 @@
+## What is Brooklyn?
+
+**brooklyn** is a library that simplifies application deployment and management.
+
+For **deployment**, it is designed to tie in with other tools, 
+giving single-click deploy and adding the concepts of 
+manageable clusters and fabrics:
+
+* many common software entities available out-of-the-box
+* integrates with [Apache Whirr](http://whirr.apache.org) 
+  to deploy well-known services such as Hadoop and elasticsearch
+  (or use POBS, plain-old-bash-scripts)
+* use PaaS's such as OpenShift, alongside self-built clusters, for maximum flexibility
+
+Brooklyn makes roll-out an integral part of the DevOps chain,
+as code which can be version-controlled and programmatically tested,
+and portable across many clouds or fixed IP machines,
+using [jclouds](http://jclouds.org) -- 
+or just hitting ``localhost`` for quick dev/test.
+
+Brooklyn's main emphasis is post-deployment, **managing** an application once it is live:
+management policies are an integral part of the deployment descriptor,
+and at runtime policies have access to all aspects of the deployment.
+They are aware of the deployment topology (hierarchical) and
+locations (machines, PaaSes, and jurisdictions), 
+as well as scripts, instrumentation, and operational goals and constraints.
+This means they're all set, once the application is launched, 
+to keep the application running optimally,
+based on whatever *optimally* means in that context.
+
+These deployment patterns and management policies are expressed as Java (and Groovy) classes,
+open-sourced here and giving you full control over what you want to happen.
+More importantly, however, this code can be shared, improved, and extended.
+
+We're still near the beginning of figuring this out: 
+[join us to make it better]({{site.path.guide}}/meta/contact.html).
+
+
+## To Get Started
+
+* See the [developer's walkthrough]({{site.path.guide}}/start/walkthrough/index.html) for a quick tour
+* Check out the [examples]({{site.path.guide}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
+* Jump in to the [user guide]({{site.path.guide}}/use/guide/) describing the 
+  [concepts]({{site.path.guide}}/use/guide/defining-applications/basic-concepts.html)
+  and including a [tutorial]({{site.path.guide}}/use/guide/quickstart/)
+* Or dive straight in to the code, either [reading]({{site.path.guide}}/dev/code/) about it
+  or [gitting](http://github.com/apache/incubator-brooklyn/) it
+
+If you like it, or if you have ideas how it could be better,
+[join the discussion]({{site.path.guide}}/meta/contact.html).

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/list-of-blueprints.md
----------------------------------------------------------------------
diff --git a/_extra/list-of-blueprints.md b/_extra/list-of-blueprints.md
new file mode 100644
index 0000000..95a602c
--- /dev/null
+++ b/_extra/list-of-blueprints.md
@@ -0,0 +1,160 @@
+---
+title: Systems Available Out-of-the-Box
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide]
+---
+
+brooklyn comes bundled with support for a large number of systems and entities.
+
+*Some entities are in an early-access state, and documentation is incomplete. Please contact the Brooklyn Project for assistance and clarification.*
+<!---
+.. TODO fix
+.. TODO name entities
+.. TODO include the fully qualified name of the entity
+-->
+
+<a name="web"></a>
+Web
+---
+
+### Clusters and Interfaces
+
+The class ``ControlledDynamicWebAppCluster`` creates a load-balanced cluster of web servers.
+It defaults to Nginx and JBoss 7, but this is configurable with the ``controller`` or ``controllerSpec``, and 
+the ``memberSpec`` configuration options.
+
+Most web app server processes, and some clusters and PaaS implementations,
+support the interface ``WebAppService`` which defines many sensors including requests per second.
+This allows app server metrics to interoperable across implementations in many cases.
+
+
+### JBoss Application Server
+
+Brooklyn supports JBoss 7 in the calss ``JBoss7Server``, with a wide range of
+monitoring.
+
+JBoss 6 is also supported using the different class ``JBoss6Server``.
+(The different implementation is needed due to major differences between 6 and 7,
+including switching from JMX to HTTP/JSON as the preferred metrics mechanism.)
+
+
+### Apache Tomcat
+
+Apache Tomcat is supported in the class ``TomcatServer``.
+(Note that this currently uses a legacy Brooklyn class hierarchy,
+and could benefit from being ported to the ``JavaSoftwareProcessSshDriver`` implementation.)
+
+
+### Nginx Load Balancer
+
+Nginx provides clustering support for several web/app servers.
+
+The install process downloads the sources for both the service and the sticky session module, configures them using GNI
+autoconf and compiles them. This requires gcc and autoconf to be installed. The install script also uses the yum package manager (if available) to install openssl-devel which is required to build the service. This will only work on RHEL or CentOS Linux systems, but the install process should proceed on a vanilla system with development tools available.
+
+On debian/ubuntu to build nginx you can get the required libraries with: 
+``apt-get install zlib1g-dev libdigest-sha-perl libssl-dev``.
+(The entity install script will attempt to do this with sudo, 
+but that may fail if sudo access is not available.) 
+
+
+<a name="database"></a>
+Database
+--------
+
+### MySQL
+
+MySQL is one of the most popular relational databases.
+Brooklyn supports setting up individual MySQL nodes with arbitrary configuration,
+which may be used to create multiple nodes using back-up and synchronization processes as desired.
+(If certain patterns for configuring multiple nodes become popular, these could be
+added as Brooklyn entities.)  
+
+
+### Apache Derby
+
+*This entity is in the sandbox.* 
+
+Brooklyn supports Apache Derby, a pure-Java SQL database. For setting up an instance of a server see ``DerbySetup``.
+
+
+<a name="nosql"></a>
+NoSQL
+-----
+
+*The NoSQL entities may not be complete.* 
+
+### Redis
+
+Redis is a distributed key-value store, supporting master/slave replication of a store as a clustered cache. This gives
+a series of read-only slaves and a single read-write master, which propagates to the slaves with eventual consistency.
+
+
+### MongoDB
+
+
+### Cassandra
+
+
+### CouchBase
+
+
+<a name="messaging"></a>
+Messaging
+---------
+
+### Qpid
+
+
+Qpid support provides a JMS broker, running over AMQP. This exposes JMS queues and topics as entities as well.
+See ``QpidSetup`` for instantiating a broker.
+
+### ActiveMQ
+
+
+ActiveMQ support provides a JMS broker. This exposes JMS queues and topics as entities as well. See ``ActiveMQSetup`` for
+instantiating a broker.
+
+### RabbitMQ
+
+
+<a name="downstream-projects"></a>
+Downstream Projects
+-------------------
+
+Downstream projects include those below.
+
+### Apache Whirr
+
+https://github.com/brooklyncentral/brooklyn-whirr
+
+Whirr allows running a variety of services on cloud providers and on localhost. This is done by providing a ``recipe`` which describes what services to launch. You can find an example of how Brooklyn integrates with Whirr [here](/use/examples/whirrhadoop/index.html#custom-whirr-recipe).
+
+### OpenShift
+
+https://github.com/cloudsoft/brooklyn-openshift
+
+### CloudFoundry
+
+https://github.com/cloudsoft/brooklyn-cloudfoundry and https://github.com/cloudsoft/brooklyn-cloudfoundry
+
+### MPI
+
+https://github.com/cloudsoft/brooklyn-openmpi
+
+### Waratek
+
+https://github.com/cloudsoft/brooklyn-waratek
+
+### MapR
+
+https://github.com/cloudsoft/brooklyn-mapr
+
+### Cloudera CDH
+
+https://github.com/cloudsoft/brooklyn-cdh
+
+### Drupal and Wordpress
+
+https://github.com/cloudsoft/brooklyn-social-apps

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/_extra/local-artifact-repo.md b/_extra/local-artifact-repo.md
new file mode 100644
index 0000000..2fd777b
--- /dev/null
+++ b/_extra/local-artifact-repo.md
@@ -0,0 +1,32 @@
+---
+layout: website-normal
+title: Prepopulating a Local Artifact Repository
+toc: /guide/toc.json
+---
+
+On occasion it can be useful to have/control/prepopulate a local repository of entity installers <small>[1]</small>.
+
+The following command (run from `~/`) may be used to sync Cloudsoft's fallback repository to the local `~/.brooklyn/repository/` folder:
+
+	wget --directory-prefix=".brooklyn/repository/" --no-parent --relative --no-host-directories --reject="index.html*" --cut-dirs=2 --recursive -e robots=off --user-agent="Brooklyn Repository Sync" http://downloads.cloudsoftcorp.com/brooklyn/repository/
+
+Brooklyn's default search behaviour for installation artifacts is as follows:
+
+1.  The local `~/.brooklyn/repository/` folder.
+2.	The entity's installer's public download url (or an overridden url if one has been specified).
+3.	Cloudsoft's fallback repository.
+
+Cloudsoft's fallback repository <small>[2]</small> contains many of the installation artifacts used by current Brooklyn entities. 
+
+It is intended to prevent problems occurring when the public url for an installer changes (e.g. when several new versions of MySQL have been released). It is provided on an as-is and as-available basis.
+
+If you use this command to create a local repository, please respect the `--user-agent`. In future this will allow Cloudsoft to easily filter repository syncing behaviour from  fallback behaviour, allowing out-of-date entities to be more easily identified and updated. 
+
+<br />
+<small>
+<ol>
+<li>For example, when establishing a local cache or enterprise golden source, or when developing Brooklyn while offline, in planes, trains and automobiles, or other such situations of exemplary derring-do <small>[3]</small>.</li> 
+<li><a href="http://downloads.cloudsoftcorp.com/brooklyn/repository/">downloads.cloudsoftcorp.com/brooklyn/repository</a></li>
+<li>This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.</li>
+</ol>
+</small>

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/simple_java_examples/example_files/tomcat_multi-location.java
----------------------------------------------------------------------
diff --git a/_extra/simple_java_examples/example_files/tomcat_multi-location.java b/_extra/simple_java_examples/example_files/tomcat_multi-location.java
new file mode 100644
index 0000000..cb92766
--- /dev/null
+++ b/_extra/simple_java_examples/example_files/tomcat_multi-location.java
@@ -0,0 +1,15 @@
+// TODO Untested code; see brooklyn-example for better maintained examples!
+public class TomcatFabricApp extends AbstractApplication {
+    @Override
+    public void init() {
+        addChild(EntitySpec.create(DynamicFabric.class)
+                .configure("displayName", "WebFabric")
+                .configure("displayNamePrefix", "")
+                .configure("displayNameSuffix", " web cluster")
+                .configure("memberSpec", EntitySpec.create(ControlledDynamicWebAppCluster.class)
+                        .configure("initialSize", 2)
+                        .configure("memberSpec", : EntitySpec.create(TomcatServer.class)
+                                .configure("httpPort", "8080+")
+                                .configure("war", "/path/to/booking-mvc.war"))));
+    }
+}


Mime
View raw message