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 2014/12/17 18:23:43 UTC
[09/50] [abbrv] incubator-brooklyn git commit: move version-specific
things to "guide"
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/update-docs.md b/docs/guide/dev/tips/update-docs.md
new file mode 100644
index 0000000..5d72e47
--- /dev/null
+++ b/docs/guide/dev/tips/update-docs.md
@@ -0,0 +1,70 @@
+---
+layout: guide-normal
+title: Updating the Docs
+toc: /toc.json
+---
+
+The Brooklyn docs live in the **docs** project in the Brooklyn codebase.
+It's built using standard jekyll/markdown with a few extensions.
+
+
+## Jekyll
+
+Firstly, install Pygments (used for source code highlighting):
+
+ sudo easy_install Pygments
+
+Next, install Jekyll and the other Ruby Gems that we need:
+
+ bundle install
+
+Then, in the `docs/` directory, run:
+
+ ./_scripts/jekyll-debug.sh
+
+Visit [http://localhost:4000/](http://localhost:4000/) and you should see the documentation.
+
+
+## Extensions
+
+In addition to the standard pygments plugin for code-highlighting,
+we use some custom Jekyll plugins (in the `_plugins` dir) to:
+
+* include markdown files inside other files
+ (see, for example, the `*.include.md` files which contain text
+ which is used in multiple other files)
+* parse JSON which we can loop over in our markdown docs
+* trim whitespace of ends of variables
+
+Using JSON table-of-contents files (`toc.json`) is our lightweight solution
+to the problem of making the site structure navigable (the menus at left).
+If you add a page, simply add the file (with full path from project root)
+and a title to the toc.json in that directory, and it will get included
+in the menu. You can also configure a special toc to show on your page,
+if you wish, by setting the toc variable in the header.
+Most pages declare the "page" layout (`_layouts/page.html`) which builds
+a menu in the left side-bar (`_includes/sidebar.html`) using the JSON --
+and automatically detecting which page is active.
+
+
+## Publishing
+
+Because GitHub don't run plugins (they run with the `--safe` option),
+the site is built off-line and uploaded to github, where the documentation is hosted.
+
+This makes the process a little more tedious, but it does have the advantage
+that the documentation lives right in the Brooklyn project,
+easy to open alongside the code inside your IDE.
+
+The off-line build can be done using `/docs/_scripts/build.sh`,
+including both jekyll markdown documentation and Brooklyn javadoc,
+with the result of this copied to the `brooklyncentral/brooklyncentral.github.com`
+github project (as per the GitHub pages documentation).
+[brooklyn.io](http://brooklyn.io) is CNAMEd to [brooklyncentral.github.com](brooklyncentral.github.com)
+for convenience.
+
+The latest stable version typically lives in the root of the `brooklyncentral.github.com` project.
+Archived versions are kept under `/v/*` with logic in the markdown for
+[meta/versions]({{ site.url }}/meta/versions.html) to link to related versions.
+Additional instructions and scripts for automating the installs can be found in `/docs/_scripts/`.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/toc.json b/docs/guide/dev/toc.json
new file mode 100644
index 0000000..f22e840
--- /dev/null
+++ b/docs/guide/dev/toc.json
@@ -0,0 +1,26 @@
+[
+{ "title": "The Code",
+ "file": "{{ site.url }}/dev/code/index.html",
+ "exclude": true,
+ "children": {% readj ./code/toc.json %} },
+{ "title": "Build and Test",
+ "file": "{{ site.url }}/dev/build/index.html",
+ "exclude": true,
+ "children": {% readj ./build/toc.json %} },
+{ "title": "Tips and Tricks",
+ "file": "{{ site.url }}/dev/tips/index.html",
+ "exclude": true,
+ "children": {% readj ./tips/toc.json %} },
+{ "title": "Links",
+ "file": "{{ site.url }}/dev/links.html",
+ "children": [
+ { "title": "Github repo",
+ "file": "https://github.com/brooklyncentral/" },
+ { "title": "Github issues",
+ "file": "https://github.com/brooklyncentral/brooklyn/issues" },
+ { "title": "Maven snapshots",
+ "file": "http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/" }
+ ] },
+{ "title": "How to Contribute",
+ "file": "{{ site.url }}/dev/how-to-contrib.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/index.md b/docs/guide/index.md
new file mode 100644
index 0000000..8665cdf
--- /dev/null
+++ b/docs/guide/index.md
@@ -0,0 +1,8 @@
+---
+layout: guide-normal
+title: Overview
+toc: /toc.json
+categories: [start]
+---
+
+{% readj start/index.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/license/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/license/index.md b/docs/guide/license/index.md
new file mode 100644
index 0000000..aed028d
--- /dev/null
+++ b/docs/guide/license/index.md
@@ -0,0 +1,18 @@
+---
+layout: guide-normal
+title: Brooklyn Licenses
+toc: /toc.json
+---
+
+## License
+
+Apache Brooklyn is released to the public as open source under the
+terms of the [Apache License, v2.0](license.html).
+
+Apache Brooklyn is currently undergoing Incubation at the Apache Software Foundation.
+
+
+## Trademark
+
+The Brooklyn name and logo are trademarks owned by the Apache Software Foundation.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/license/license.md
----------------------------------------------------------------------
diff --git a/docs/guide/license/license.md b/docs/guide/license/license.md
new file mode 100644
index 0000000..75cceac
--- /dev/null
+++ b/docs/guide/license/license.md
@@ -0,0 +1,194 @@
+---
+layout: guide-normal
+title: License
+toc: /toc.json
+---
+
+Brooklyn is licensed to the public as open source under the
+terms of the [Apache License, v2.0](http://www.apache.org/licenses/LICENSE-2.0).
+You may not use this content except in compliance with the License.
+
+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.
+
+
+{% highlight text %}
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/license/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/license/toc.json b/docs/guide/license/toc.json
new file mode 100644
index 0000000..8194f80
--- /dev/null
+++ b/docs/guide/license/toc.json
@@ -0,0 +1,4 @@
+[
+{ "title": "Apache License v2.0",
+ "file": "{{ site.url }}/license/license.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/brooklyn-gpg-public-key.asc
----------------------------------------------------------------------
diff --git a/docs/guide/meta/brooklyn-gpg-public-key.asc b/docs/guide/meta/brooklyn-gpg-public-key.asc
new file mode 100644
index 0000000..3b515a4
--- /dev/null
+++ b/docs/guide/meta/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/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/contact.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/contact.include.md b/docs/guide/meta/contact.include.md
new file mode 100644
index 0000000..e0d1e4b
--- /dev/null
+++ b/docs/guide/meta/contact.include.md
@@ -0,0 +1,9 @@
+
+Contact us on the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/).
+
+Additionally look for us on:
+
+* **IRC**: #brooklyncentral ([IRC??](/meta/irc.html))
+* **Twitter**: @brooklyncentral #brooklyncentral
+
+We'd love to hear from you!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/contact.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/contact.md b/docs/guide/meta/contact.md
new file mode 100644
index 0000000..937e763
--- /dev/null
+++ b/docs/guide/meta/contact.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Contact
+toc: /toc.json
+---
+
+{% readj contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/irc.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/irc.md b/docs/guide/meta/irc.md
new file mode 100644
index 0000000..5827818
--- /dev/null
+++ b/docs/guide/meta/irc.md
@@ -0,0 +1,31 @@
+---
+layout: guide-normal
+title: IRC
+toc: /toc.json
+---
+
+IRC is a basic group chat system used by many open source projects to enable developers to
+collaborate and to help users communicate and support each other. Brooklyn has an IRC
+channel where users and developers hang out.
+
+## Getting Help On IRC
+
+When you connect to the Brooklyn IRC channel, say Hi and then ask your question. It may
+take a little while for someone to see and respond to your question. (Be
+patient if you don't get an instant answer - unless there's already a conversation
+happening folk will probably not have their eyes on the channel.)
+
+You may want to do other things while you wait, like reviewing the [brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
+lists to see if anyone has had the same issue before.
+
+## Brooklyn IRC Channel
+
+* **IRC Server:** irc.freenode.net
+* **Channel/Room:** #brooklyncentral
+* **Port:** 6667 (Default)
+
+If you are new to IRC, there is a web interface at [webchat.freenode.net](http://webchat.freenode.net/?channels=brooklyncentral)
+but you may prefer to checkout the [Wikipedia IRC article](http://en.wikipedia.org/wiki/IRC#Client_software)
+for an IRC application.
+
+You can find more information about using IRC at [irchelp.org](http://www.irchelp.org/).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/meta/toc.json b/docs/guide/meta/toc.json
new file mode 100644
index 0000000..694eaea
--- /dev/null
+++ b/docs/guide/meta/toc.json
@@ -0,0 +1,8 @@
+[
+{ "title": "Versions",
+ "file": "{{ site.url }}/meta/versions.html" },
+{ "title": "Verify",
+ "file": "{{ site.url }}/meta/verify.html" },
+{ "title": "Contact",
+ "file": "{{ site.url }}/meta/contact.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/verify.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/verify.md b/docs/guide/meta/verify.md
new file mode 100644
index 0000000..889e5bd
--- /dev/null
+++ b/docs/guide/meta/verify.md
@@ -0,0 +1,36 @@
+---
+layout: guide-normal
+title: Verify the Integrity of Downloads
+toc: /toc.json
+---
+{% include fields.md %}
+
+It is essential for security that you verify the integrity of the downloaded files using their PGP signatures or SHA-1 checksums.
+
+### Verifying PGP signatures using PGP or GPG
+
+Download the [brooklyn-gpg-public-key.asc](brooklyn-gpg-public-key.asc)
+file and the `.asc` PGP signature file for the relevant artefact.
+
+(Make sure you get these files from the main {% if SNAPSHOT %}[Maven Central]({{ mavencentral_repo_groupid_url }}){% else %}[Sonatype]({{ sonatype_repo_groupid_url }}){% endif %} repository rather than from a mirror.)
+
+Verify the signatures using one of the following commands:
+
+ pgpk -a brooklyn-gpg-public-key.asc
+ pgpv brooklyn-{{ site.brooklyn-version }}-dist.tar.gz.asc
+
+or
+
+ pgp -ka brooklyn-gpg-public-key.asc
+ pgp brooklyn-{{ site.brooklyn-version }}-dist.zip.asc
+
+or
+
+ gpg --import brooklyn-gpg-public-key.asc
+ gpg --verify brooklyn-{{ site.brooklyn-version }}-dist.tar.gz.asc
+
+You can also verify the SHA-1 checksum of the files.
+
+A program called `sha1` or `sha1sum` is included in most Linux distributions and OSx. For Windows users, `fsum` supports SHA-1.
+
+Ensure the generated checksum string matches the contents of the `.sha1` file for the relevant artefact (and again download from {% if SNAPSHOT %}[Maven Central]({{ mavencentral_repo_groupid_url }}){% else %}[Sonatype]({{ sonatype_repo_groupid_url }}){% endif %} repository, rather than from a mirror).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/meta/versions.md
----------------------------------------------------------------------
diff --git a/docs/guide/meta/versions.md b/docs/guide/meta/versions.md
new file mode 100644
index 0000000..53a6a0d
--- /dev/null
+++ b/docs/guide/meta/versions.md
@@ -0,0 +1,110 @@
+---
+layout: guide-normal
+title: Versions
+toc: /toc.json
+---
+
+<!--- display which version we are using, based on where it is written -->
+
+### Brooklyn v{{ site.brooklyn-version }}
+
+
+{% if site.server %}
+> **Server (debug) mode detected.**
+
+> *Links to other versions on this page and others will likely not work when running in server/debug mode.
+Files must be copied to the brooklyncentral.github.com repo for these links to resolve correctly.*
+
+> *Debug page generated {{ site.time }}*
+{% endif %}
+
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+<!--- snapshot version -->
+
+ {% if site.url == '' %}
+
+<!--- current version (served off root of site) is snapshot (unusual) -->
+
+This is the documentation for the current snapshot version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+
+ {% else %}
+
+<!--- archive docs -->
+
+This is the documentation for a snapshot version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+
+[View current documentation here.](/meta/versions.html)
+
+
+ {% endif %}
+
+NB: "Snapshot" means it is the code at a point in time,
+and that a reference to this version {{ site.brooklyn-version }}
+may resolve to different code at a different point in time.
+Where possible it is preferable to develop against a GA version
+rather than a shapshot.
+
+{% else %}
+<!--- not snapshot -->
+
+ {% if site.url == '' %}
+
+<!--- current version (served off root of site) -->
+
+This is the documentation for the latest stable version of Brooklyn,
+generated {{ site.time | date_to_string }}.
+Other versions with documentation available are listed below.
+
+ {% else %}
+
+<!--- archive version -->
+
+This is the archived documentation for Brooklyn {{ site.brooklyn-version }}
+(generated {{ site.time }}, archived under {{ site.url }}).
+
+[View current documentation here.](/meta/versions.html)
+
+ {% endif %}
+{% endif %}
+
+
+### Version History
+
+* **[0.7.0-SNAPSHOT (master)](/v/0.7.0-SNAPSHOT)**: since 0.6.0, lots of work on yaml, persistence, policies, and more supported systems
+
+* **[0.7.0](/v/0.7.0-M1/)**: most recent milestone release
+
+* **[0.6.0](/v/0.6.0/)**: use of spec objects, chef and windows support, more clouds (Nov 2013)
+
+* **[0.5.0](/v/0.5.0/)**: includes new JS GUI and REST API, rebind/persistence support, cleaner model and naming conventions, more entities (May 2013)
+
+* **[0.4.0](/v/0.4.0/)**: initial public GA release of Brooklyn to Maven Central, supporting wide range of entities and examples (Jan 2013)
+
+Note: To prevent accidentally referring to out-of-date information,
+a banner is displayed when accessing specific versions from the archive.
+You may
+<a href="#" onclick="set_user_versions_all();">disable all warnings</a> or
+<a href="#" onclick="clear_user_versions();">re-enable all warnings</a>.
+
+
+### Versioning
+
+Brooklyn uses the [semantic versioning](http://semver.org/) guidelines. Releases will be numbered with the following format:
+
+`Brooklyn <major>.<minor>.<patch>`
+
+Breaking backward compatibility increments the `<major>` version.
+New additions without breaking backward compatibility ups the `<minor>` version.
+Bug fixes and misc changes bumps the `<patch>` version.
+New major and minor releases zero the less significant counters.
+
+Additionally, Brooklyn's release process include Snapshots, Milestones and Release Candidates.
+
+A Snapshot (`-SNAPSHOT`) is the bleeding edge. This will not be stable.
+
+Milestone versions (`-Mn`) are frozen snapshots. Some code features may be stable, but the documentation and examples may not be complete.
+
+A Release Candidate (`-rc.n`) is a just-about-ready version. Release candidates are tested against our acceptance criteria, and qualifying builds are promoted as final.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/docs-summary.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/docs-summary.include.md b/docs/guide/start/docs-summary.include.md
new file mode 100644
index 0000000..c08c06f
--- /dev/null
+++ b/docs/guide/start/docs-summary.include.md
@@ -0,0 +1,7 @@
+To learn about Brooklyn, here are some recommended starting points:
+
+* [Developer's Walkthrough]({{site.url}}/start/walkthrough/index.html)
+* [Examples]({{site.url}}/use/examples/)
+* [User Guide]({{site.url}}/use/guide/)
+* [Code Overview]({{site.url}}/dev/code/)
+* [Code on Github](http://github.com/brooklyncentral/brooklyn/)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/docs-summary.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/docs-summary.md b/docs/guide/start/docs-summary.md
new file mode 100644
index 0000000..4e993fa
--- /dev/null
+++ b/docs/guide/start/docs-summary.md
@@ -0,0 +1,9 @@
+---
+layout: guide-normal
+title: Documentation
+toc: ../toc.json
+---
+
+{% readj docs-summary.include.md %}
+
+Beyond this, [just come chat to us]({{site.url}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/download.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/download.md b/docs/guide/start/download.md
new file mode 100644
index 0000000..0e82a84
--- /dev/null
+++ b/docs/guide/start/download.md
@@ -0,0 +1,185 @@
+---
+layout: guide-normal
+title: Downloads
+toc: ../toc.json
+---
+{% include fields.md %}
+
+First time user? The [getting started]({{ site.url }}/use/guide/quickstart/index.html) guide will walk you through downloading Brooklyn, setup of your `brooklyn.properties` and `catalog.xml` files, and then trying the [examples](#examples).
+
+## Download Version {{ site.brooklyn-version }}
+
+<table>
+<tr>
+ <th style='text-align:left'>Download</th>
+ <th style='text-align:left'>File/Format</th>
+ <th>checksums <small><a href="/meta/verify.html" title='Instructions on verifying the integrity of your downloads.'>(?)</a></small></th>
+</tr>
+<tr>
+ <td style='text-align:left;vertical-align:top' rowspan='2'>Distro</td>
+ <td style='text-align:left'><a href='{{ this_dist_url_zip }}' title='Download ZIP archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.zip</a></td>
+ <td><small><a href='{{ this_dist_url_zip }}.asc'>PGP</a>, <a href='{{ this_dist_url_zip }}.sha1'>SHA1</a></small></td>
+</tr>
+<tr>
+ <td style='text-align:left'><a href='{{ this_dist_url_tgz }}' title='Download TGZ archive'>brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz</a></td>
+ <td ><small><a href='{{ this_dist_url_tgz }}.asc'>PGP</a>, <a href='{{ this_dist_url_tgz }}.sha1'>SHA1</a></small></td>
+</tr>
+<tr>
+ <td style='text-align:left'>All Jar</td>
+ <td style='text-align:left'><a href='{{ this_alljar_url_jar }}' title='Download the ALL JAR'>brooklyn-all-{{ site.brooklyn-version }}-with-dependencies.jar</a></td>
+ <td ><small><a href='{{ this_alljar_url_jar }}.asc'>PGP</a>, <a href='{{ this_alljar_url_jar }}.sha1'>SHA1<a/></small></td>
+</tr>
+<tr>
+ <td style='text-align:left'>Release notes</td>
+ <td style='text-align:left'><a href='{{ site.url }}/start/release-notes.html'>{{ site.brooklyn-version }}</a></td>
+ <td> - </td>
+</tr>
+</table>
+{% if SNAPSHOT %}
+<span style='float:right'><small>Source: <a href='{{ this_anything_url_search }}'>Sonatype</a></small></span>
+{% else %}
+<span style='float:right'><small>Source: <a href='{{ this_anything_url_search }}'>Maven Central</a></small></span>
+{% endif %}
+
+<a name="distro"></a>
+## The Distro
+
+The distribution archive contains Brooklyn as a standalone executable package.
+
+* previous stable versions: [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-dist/)
+* previous snapshot versions: [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-dist/)
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+**Please note**: You are reading the documentation for a snapshot version of Brooklyn.
+You should always confirm that the source and date for snapshot artifacts.
+{% endif %}
+
+
+<a name="alljar"></a>
+## The All Jar
+
+This is a single JAR containing all of Brooklyn and its dependencies, for developing Brooklyn into your own applications. Just download your preferred flavour and add it to your classpath.
+
+{% if SNAPSHOT %}{% else %}
+* [Version {{ site.brooklyn-version }}](http://search.maven.org/#artifactdetails|io.brooklyn|brooklyn-all|{{ site.brooklyn-version }}|jar)
+{% endif %}
+* previous stable versions: [Maven Central]({{ mavencentral_repo_groupid_url }}brooklyn-all/)
+* previous snapshot versions: [Sonatype]({{ sonatype_repo_groupid_url }}brooklyn-all/)
+
+{% if site.brooklyn-version contains 'SNAPSHOT' %}
+**Again**, check the source and date for SNAPSHOT JARs.
+{% endif %}
+
+## Release Notes
+
+Release notes can be found [here]({{ site.url }}/start/release-notes.html).
+
+<a name="examples"></a>
+## Examples
+
+{% if SNAPSHOT %}
+As this is a snapshot version of Brooklyn, please find the examples in the main Brooklyn codebase (in the `/examples` directory).
+
+When this version is released, the [brooklyn-examples git repository](http://github.com/brooklyncentral/brooklyn-examples) will be updated and instructions for use will be included here.
+
+{% else %}
+
+You can checkout the examples from the [brooklyn-examples git repository](http://github.com/brooklyncentral/brooklyn-examples).
+
+Maven (v3) is required to build them, as described [here]({{ site.url }}/dev/build/).
+The examples for this version ({{ site.brooklyn-version }}) are in the branch
+`{% if SNAPSHOT %}{{ site.brooklyn-snapshot-git-branch }}{% else %}{{ site.brooklyn-version }}{% endif %}`, so if you have `git` and `mvn` already, you can simply:
+
+{% highlight bash %}
+% git clone https://github.com/brooklyncentral/brooklyn-examples.git
+% cd brooklyn-examples
+{% if brooklyn_examples_branch == 'master' %}{% else %}% git checkout {{ brooklyn_examples_branch }}
+{% endif %}% mvn clean install
+{% endhighlight %}
+
+
+If you don't use `git`, you can download the projects as a tarball instead
+from [this link](https://github.com/brooklyncentral/brooklyn-examples/tarball/{{ brooklyn_examples_branch }}).
+These commands should do the trick:
+
+{% highlight bash %}
+% curl -L -o brooklyn-examples-{{ brooklyn_examples_branch }}.tgz \
+ https://github.com/brooklyncentral/brooklyn-examples/tarball/{{ brooklyn_examples_branch }}
+% tar xvfz brooklyn-examples-{{ brooklyn_examples_branch }}.tgz
+% mv brooklyncentral-brooklyn-examples-* brooklyn-examples-{{ brooklyn_examples_branch }} \
+ # change the strange name which github assigns in the tarball
+% mvn clean install
+{% endhighlight %}
+
+
+A good example to start with is the [Elastic Web Cluster]({{site.url}}/use/examples/webcluster.html).
+
+{% endif %}
+
+
+<a name="maven"></a>
+## Maven
+
+If you use Maven, you can add Brooklyn with the following in your pom:
+
+{% highlight xml %}
+ <dependencies>
+ <dependency>
+ <groupId>io.brooklyn</groupId>
+ <artifactId>brooklyn-all</artifactId>
+ <version>{{ site.brooklyn-version }}</version>
+ </dependency>
+ </dependencies>
+{% endhighlight %}
+
+`brooklyn-all` (used above) brings in all dependencies, including jclouds.
+If you prefer a smaller repo you might want just ``brooklyn-core``, ``brooklyn-policies``,
+and some of ``brooklyn-software-webapp``, ``brooklyn-software-database``, ``brooklyn-software-messaging``, or others
+(browse the full list [here]({{ this_anything_url_search }})).
+
+If you wish to use the Apache and/or Cloudsoft repositories (particularly for snapshots),
+you can add some of the following sections:
+
+{% highlight xml %}
+ <repositories>
+ <repository>
+ <id>cloudsoft-cloudfront-releases-repo</id>
+ <url>http://developers.cloudsoftcorp.com/maven/releases/</url>
+ </repository>
+ <!-- optional for snapshot versions -->
+ <repository>
+ <id>apache-nexus-snapshots</id>
+ <name>Apache Nexus Snapshots</name>
+ <url>https://repository.apache.org/content/repositories/snapshots</url>
+ <releases> <enabled>false</enabled> </releases>
+ <snapshots> <enabled>true</enabled> </snapshots>
+ </repository>
+ <repository>
+ <id>cloudsoft-cloudfront-snapshots-repo</id>
+ <url>http://developers.cloudsoftcorp.com/maven/snapshots/</url>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ <checksumPolicy>fail</checksumPolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+{% endhighlight %}
+
+{% if SNAPSHOT %}
+**Please note**: to use a snapshot version of Brooklyn, you must either have Brooklyn built locally
+or one of the additional snapshot repositories above.
+{% endif %}
+
+
+<a name="source"></a>
+## Source Code
+
+Full source is at [github.com/brooklyncentral/brooklyn](http://github.com/brooklyncentral/brooklyn).
+Information on working with the source is [here]({{ site.url }}/dev/code).
+
+Alternatively you can download archives of the source directly:
+
+<a href="https://github.com/brooklyncentral/brooklyn/tarball/master"><img border="0" width="90" src="https://github.com/images/modules/download/tar.png"></a>
+<a href="https://github.com/brooklyncentral/brooklyn/zipball/master"><img border="0" width="90" src="https://github.com/images/modules/download/zip.png"></a>
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.include.md b/docs/guide/start/index.include.md
new file mode 100644
index 0000000..1406337
--- /dev/null
+++ b/docs/guide/start/index.include.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.url}}/meta/contact.html).
+
+
+## To Get Started
+
+* See the [developer's walkthrough]({{site.url}}/start/walkthrough/index.html) for a quick tour
+* Check out the [examples]({{site.url}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target
+* Jump in to the [user guide]({{site.url}}/use/guide/) describing the
+ [concepts]({{site.url}}/use/guide/defining-applications/basic-concepts.html)
+ and including a [tutorial]({{site.url}}/use/guide/quickstart/)
+* Or dive straight in to the code, either [reading]({{site.url}}/dev/code/) about it
+ or [gitting](http://github.com/brooklyncentral/brooklyn/) it
+
+If you like it, or if you have ideas how it could be better,
+[join the discussion]({{site.url}}/meta/contact.html).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/index.md b/docs/guide/start/index.md
new file mode 100644
index 0000000..b3e9983
--- /dev/null
+++ b/docs/guide/start/index.md
@@ -0,0 +1,8 @@
+---
+layout: guide-normal
+title: Overview
+toc: /toc.json
+categories: [start]
+---
+
+{% readj index.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/known-issues.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/known-issues.md b/docs/guide/start/known-issues.md
new file mode 100644
index 0000000..65c4986
--- /dev/null
+++ b/docs/guide/start/known-issues.md
@@ -0,0 +1,28 @@
+---
+layout: guide-normal
+title: Known Issues
+toc: ../toc.json
+---
+
+## Unable to Provision certain types of Debian VMs
+
+*Symptom*: Brooklyn fails to provision Debian VMs (e.g. in aws-ec2).
+
+*Cause*: `sudo` is not available on path, causing Brooklyn to fail to confirm that the VM is ssh'able.
+
+*Workaround*: Choose an image that does have sudo (see [wiki.debian.org/Cloud/AmazonEC2Image](http://wiki.debian.org/Cloud/AmazonEC2Image)).
+
+*Fix*: is [Pull #600](https://github.com/brooklyncentral/brooklyn/pull/600); you may also want to run with `brooklyn.location.jclouds.aws-ec2.user=root` if subsequent commands give permission errors.
+
+*Versions Affected*: 0.5.0-M2
+
+
+### Unable to Provision Ubuntu 8 VMs
+
+*Symptom: Brooklyn fails to provision Ubuntu 8 VMs (e.g. in aws-ec2) with the following error 'Cannot insert the iptables rule for port 22. Error: sudo: illegal option `-n''.
+
+*Cause: Ubuntu 8 is too old; the sudo command doesn't support the -n setting.
+
+*Workaround: Choose Ubuntu 10 or higher.
+
+*Versions Affected*: 0.5.0-M2
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/release-notes.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/release-notes.md b/docs/guide/start/release-notes.md
new file mode 100644
index 0000000..1f2fa4e
--- /dev/null
+++ b/docs/guide/start/release-notes.md
@@ -0,0 +1,56 @@
+---
+layout: guide-normal
+title: Release Notes
+toc: ../toc.json
+---
+
+## Brooklyn Version (Version)
+
+You are viewing a SNAPSHOT release (master branch), so this is a template for the release notes.
+
+* Introduction
+* New Features
+* Backwards Compatibility
+* Community Activity
+
+### Introduction
+
+This milestone release includes many big features, and brings us much closer to NEXT VERSION.
+
+It incorporates a lot of improvements and feedback from our community. Thank you!
+
+Thanks also go to Brooklyn's commercial users. Already Brooklyn has been adopted into some very exciting projects including
+
+For more information, please checkout [brooklyncentral.github.io](http://brooklyncentral.github.io), and our
+[mailing list at Apache](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/).
+
+### New Features
+
+The major changes between M1 and M2 are:
+
+1. Entry
+
+2. Entry
+ * With sublist
+ * list item
+ * list item
+3. [Links](#) formatting. (Example.)
+
+4. List of new providers
+
+5. List of new entities
+
+
+### Backwards Compatibility
+
+For upgrading from OLD to NEW version.
+
+1. Entry
+
+1. Lists can use 1. 1. 1. 1.
+
+1. (Jekyll counts for you.)
+
+### Community Activity
+
+Any activity related to Brooklyn, but not part of Brooklyn itself.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/start/toc.json b/docs/guide/start/toc.json
new file mode 100644
index 0000000..43d79d7
--- /dev/null
+++ b/docs/guide/start/toc.json
@@ -0,0 +1,10 @@
+[
+{ "title": "Overview",
+ "file": "{{ site.url }}/index.html" },
+{ "title": "Walkthrough",
+ "file": "{{ site.url }}/start/walkthrough/index.html" },
+{ "title": "Download",
+ "file": "{{ site.url }}/start/download.html" },
+{ "title": "Documentation",
+ "file": "{{ site.url }}/start/docs-summary.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/video.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/video.md b/docs/guide/start/video.md
new file mode 100644
index 0000000..c45dd4c
--- /dev/null
+++ b/docs/guide/start/video.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Video
+toc: ../toc.json
+---
+
+TODO
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/index.md b/docs/guide/start/walkthrough/index.md
new file mode 100644
index 0000000..de29f5c
--- /dev/null
+++ b/docs/guide/start/walkthrough/index.md
@@ -0,0 +1,240 @@
+---
+layout: guide-normal
+title: Walkthrough
+toc: /toc.json
+---
+{% include fields.md %}
+
+## Intro
+
+Brooklyn makes it easy to describe the structure and management of sophisticated distributed applications,
+and then it makes it easy to launch them in a cloud, with on-going automated management.
+
+This walkthrough will set up a sample application which you can use as foundation for creating your own applications.
+
+The sample application is a three tier web service, composed of:
+
+* an Nginx load-balancer
+* a cluster of JBoss appservers
+* a MySQL database
+
+
+## Download the Sample Project
+
+If you'd like to follow these steps on your machine, you can use Maven to
+download the Brooklyn quickstart archetype and setup a `brooklyn-sample` directory and project.
+Maven will automatically download Brooklyn and all dependencies.
+You can of course follow this walkthrough without installing it on your machine ... yet!
+
+{% if SNAPSHOT %}
+
+{% highlight bash %}
+$ export BROOKLYN_VERSION=0.7.0-SNAPSHOT
+$ mvn archetype:generate \
+ -DarchetypeGroupId=io.brooklyn \
+ -DarchetypeArtifactId=brooklyn-archetype-quickstart \
+ -DarchetypeVersion=${BROOKLYN_VERSION} \
+ -DarchetypeCatalog=https://oss.sonatype.org/content/repositories/snapshots/archetype-catalog.xml \
+ -DgroupId=com.acme.sample \
+ -DartifactId=brooklyn-sample \
+ -Dversion=0.1.0-SNAPSHOT \
+ -Dpackage=com.acme.sample.brooklyn \
+ --batch-mode
+$ cd brooklyn-sample
+{% endhighlight %}
+
+*Note*: As this is a snapshot version of Brooklyn, the code above includes a `-DarchetypeCatalog` specification.
+This can be omitted for release versions, or if you already have a local `mvn install` of Brooklyn installed as described [here]({{site.url}}/dev/code/index.html).
+
+{% else %}
+
+{% highlight bash %}
+$ export BROOKLYN_VERSION=0.7.0-SNAPSHOT
+$ mvn archetype:generate \
+ -DarchetypeGroupId=io.brooklyn \
+ -DarchetypeArtifactId=brooklyn-archetype-quickstart \
+ -DarchetypeVersion=${BROOKLYN_VERSION} \
+ -DgroupId=com.acme.sample \
+ -DartifactId=brooklyn-sample \
+ -Dversion=0.1.0-SNAPSHOT \
+ -Dpackage=com.acme.sample.brooklyn
+$ cd brooklyn-sample
+{% endhighlight %}
+
+{% endif %}
+
+## Define your Application Blueprint
+
+An application blueprint is defined as a Java class, as follows:
+
+{% highlight java %}
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
+ @Override
+ public void init() {
+ MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class));
+ ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class));
+ }
+}
+{% endhighlight %}
+
+The file `ClusterWebServerDatabaseSample.java` in `src/main/java/com/acme/sample/brooklyn/sample/app/`
+provides a template to follow.
+
+
+## Deploying the Application
+
+If you have not already done so, follow the section in the
+[Getting Started Guide]({{site.url}}/use/guide/quickstart/index.html) to create a `brooklyn.properties`
+file containing credentials for your preferred cloud provider.
+
+To launch this application, build the project and run the `start.sh` script in the resulting assembly:
+
+{% highlight bash %}
+$ mvn clean assembly:assembly
+
+$ cd target/brooklyn-sample-0.1.0-SNAPSHOT-dist/brooklyn-sample-0.1.0-SNAPSHOT/
+
+$ ./start.sh launch \
+ --app com.acme.sample.brooklyn.sample.app.ClusterWebServerDatabaseSample \
+ --location jclouds:aws-ec2:eu-west-1
+{% endhighlight %}
+
+(Amazon is used in this walkthrough, but lots of targets are supported,
+including `--location localhost`, fixed IP addresses, and
+everything supported by [jclouds](http://jclouds.org), from OpenStack to Google Compute.)
+
+Your console will inform you that it has started a Brooklyn console at [http://localhost:8081](http://localhost:8081)
+
+[](wt-starting.png)
+
+The management console provides a view on to the entities that launched,
+including the hierarchy (appservers grouped into a cluster) and their locations.
+
+Brooklyn collects information from these entities ("sensors"),
+aggregates these for clusters and other groups (using "enrichers"),
+and exposes operations ("effectors") that can be performed on entities.
+
+[](wt-tree-jboss-sensors.png)
+
+
+## Topology, Dependencies, and Management Policies
+
+Of course in the real world, application deployments are more interesting;
+they do things and need configuration. For instance you might need to:
+
+* specify a WAR file
+* initialize the database
+* tell the webapp servers where to find the database
+
+Let's show how these are done using Brooklyn.
+We assume the WAR file and the database init script are accessible
+on the classpath, but a range of URL formats is supported.
+The "dependent inter-process configuration" -- giving the database's URL
+to the webapps -- we'll do here with a JVM system property,
+but you're free to use any mechanism you wish.
+
+Under the covers, ``attributeWhenReady`` is monitoring a sensor from MySQL
+and generating a string to pass to the webapp software processes; ``formatString``
+is a similar utility that returns a string once all of its parts have been resolved.
+Due to the use of futures, the Brooklyn webapp entities will automatically
+block "at the last moment" when the value is needed
+(but after e.g. the VMs have been provisioned, to speed things up).
+
+{% highlight java %}
+public class ClusterWebServerDatabaseSample extends AbstractApplication {
+ @Override
+ public void init() {
+ MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class)
+ .configure(MySqlNode.CREATION_SCRIPT_URL, "classpath://visitors-database-setup.sql"));
+
+ ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class)
+ .configure("memberSpec", EntitySpec.create(JBoss7Server.class)
+ .configure("httpPort", "8080+")
+ .configure("war", WAR_PATH)
+ .configure(JavaEntityMethods.javaSysProp("brooklyn.example.db.url"),
+ formatString("jdbc:%s%s?user=%s\\&password=%s",
+ attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD))));
+ }
+}
+{% endhighlight %}
+
+We now see our app at the Nginx URL:
+
+[](wt-deployed-application.png)
+
+Finally, we'll bring in some active management: we're going to monitor requests per second,
+and scale out if this exceeds 100 up to a maximum of 5 servers.
+This is a naively simple policy, but it shows Brooklyn's real metier,
+running management policies for applications whose topology it knows.
+
+{% highlight java %}
+ web.getCluster().addPolicy(AutoScalerPolicy.builder().
+ metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND).
+ sizeRange(1, 5).
+ metricRange(10, 100).
+ build());
+{% endhighlight %}
+
+*Policies* in Brooklyn typically subscribe to sensors, perform some computation, and if necessary invoke effectors on entities. This is where the ability to group entities
+becomes very useful -- policies can be attached to group entities, and groups themselves can be hierarchical. It's also handy that often Brooklyn creates the entities,
+so it knows what the hierarchy is.
+
+Under the covers, this ``AutoScalerPolicy`` attaches to any ``Resizable`` entity (exposing a ``resize`` effector), and monitors a specified sensor (or function) attempting to keep it within healthy limits. A separate policy operates at the ``Controlled`` cluster to ensure the load-balancer is updated as the pool of web servers expands and contracts.
+
+Fire up a JMeter session (or other load testing tool) and blast the Nginx address. The auto-scaler policy will scale up the cluster.
+
+## What Next?
+
+In addition to the sample project created by the archetype, with its README and
+`assembly` build, you can find additional code related to this example included with Brooklyn as the ``simple-web-cluster`` example,
+described [in detail here]({{site.url}}/use/examples/webcluster).
+
+For your applications, you might want to mix in other data stores, messaging systems, or on-line services including PaaS.
+Brooklyn supports some of these out-of-the-box, including a wide-range of tools which it can use Whirr to provision, such as Hadoop.
+But if you have something you don't see,
+[let us know]({{site.url}}/meta/contact.html) --
+we want to work with you to
+[write a new entity]({{site.url}}/dev/code/entity.html) or
+[policy]({{site.url}}/dev/code/policy.html)
+and [contribute it]({{site.url}}/dev/how-to-contrib.html).
+
+
+<!--
+
+Alternatively you can just add a ``main`` method to the application class as follows:
+
+{% highlight java %}
+ public static void main(String[] argv) {
+ List<String> args = Lists.newArrayList(argv);
+ String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
+ String location = CommandLineUtil.getCommandLineOption(args, "--location", DEFAULT_LOCATION);
+
+ BrooklynServerDetails server = BrooklynLauncher.newLauncher()
+ .webconsolePort(port)
+ .launch();
+
+ Location loc = server.getManagementContext().getLocationRegistry().resolve(location);
+
+ StartableApplication app = new WebClusterDatabaseExample()
+ .appDisplayName("Brooklyn WebApp Cluster with Database example")
+ .manage(server.getManagementContext());
+
+ app.start(ImmutableList.of(loc));
+
+ Entities.dumpInfo(app);
+ }
+{% endhighlight %}
+
+Compile and run this with the [``brooklyn-all`` jar]({{site.url}}/start/download.html) on the classpath,
+pointing at your favourite WAR on your filesystem.
+(If the ``import`` packages aren't picked up correctly,
+you can cheat by looking at [the file in Github](https://github.com/brooklyncentral/brooklyn/blob/master/examples/simple-web-cluster/src/main/java/brooklyn/demo/WebClusterDatabaseExample.java);
+and you'll find a sample WAR which uses the database as configured above
+[here](https://http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/io/brooklyn/).)
+ TODO example webapp url
+
+If you want to adventure beyond ``localhost`` (the default),
+simply supply the your favourite cloud (e.g. ``aws-ec2:eu-west-1``)
+with credentials set up as described [here]({{ site.url }}/use/guide/management/index.html#startup-config).
+
+-->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-deployed-application-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-deployed-application-700.png b/docs/guide/start/walkthrough/wt-deployed-application-700.png
new file mode 100644
index 0000000..7ef90d9
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-deployed-application-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-deployed-application.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-deployed-application.png b/docs/guide/start/walkthrough/wt-deployed-application.png
new file mode 100644
index 0000000..751402e
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-deployed-application.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-starting-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-starting-700.png b/docs/guide/start/walkthrough/wt-starting-700.png
new file mode 100644
index 0000000..c87a539
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-starting-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-starting.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-starting.png b/docs/guide/start/walkthrough/wt-starting.png
new file mode 100644
index 0000000..970805f
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-starting.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png b/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png
new file mode 100644
index 0000000..3dfc7f2
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-tree-jboss-sensors-700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png
----------------------------------------------------------------------
diff --git a/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png b/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png
new file mode 100644
index 0000000..4c44ea9
Binary files /dev/null and b/docs/guide/start/walkthrough/wt-tree-jboss-sensors.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/toc-menu.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc-menu.json b/docs/guide/toc-menu.json
new file mode 100644
index 0000000..824bbbe
--- /dev/null
+++ b/docs/guide/toc-menu.json
@@ -0,0 +1,20 @@
+[
+{ "title": "Overview",
+ "file": "{{ site.url }}/index.html" },
+{ "title": "Download",
+ "file": "{{ site.url }}/start/download.html" },
+{ "title": "Getting Started",
+ "file": "{{ site.url }}/use/guide/quickstart/index.html" },
+{ "title": "Walkthrough",
+ "file": "{{ site.url }}/start/walkthrough/index.html" },
+{ "title": "User Guide",
+ "file": "{{ site.url }}/use/guide/index.html",
+ "children": {% readj ./use/guide/toc.json %} },
+{ "title": "Examples",
+ "file": "{{ site.url }}/use/examples/index.html",
+ "children": {% readj ./use/examples/toc.json %} },
+{ "title": "Contributing",
+ "file": "{{ site.url }}/dev/code/index.html",
+ "exclude": true,
+ "children": {% readj /dev/toc.json %} }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/toc.json b/docs/guide/toc.json
new file mode 100644
index 0000000..79f9e5d
--- /dev/null
+++ b/docs/guide/toc.json
@@ -0,0 +1,21 @@
+[
+{ "title": "Start",
+ "file": "{{ site.url }}/start/index.html",
+ "exclude": true,
+ "children": {% readj /start/toc.json %} },
+{ "title": "Using brooklyn",
+ "file": "{{ site.url }}/use/index.html",
+ "children": {% readj /use/toc.json %} },
+{ "title": "Contributing",
+ "file": "{{ site.url }}/dev/code/index.html",
+ "exclude": true,
+ "children": {% readj /dev/toc.json %} },
+{ "title": "License",
+ "file": "{{ site.url }}/license/index.html",
+ "exclude": true,
+ "children": {% readj /license/toc.json %} },
+{ "title": "Meta",
+ "file": "{{ site.url }}/meta/versions.html",
+ "exclude": true,
+ "children": {% readj /meta/toc.json %} }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/api/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/api/index.md b/docs/guide/use/api/index.md
new file mode 100644
index 0000000..143c345
--- /dev/null
+++ b/docs/guide/use/api/index.md
@@ -0,0 +1,11 @@
+---
+layout: guide-normal
+title: API Reference
+toc: ../../toc.json
+---
+
+*Javadoc is not available as part of this build.*
+
+Please see the [source code]({{site.url}}/dev/code) to view javadoc.
+
+<!-- This page is normally overwritten by generated javadoc. -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/contact.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/contact.md b/docs/guide/use/contact.md
new file mode 100644
index 0000000..008a5a1
--- /dev/null
+++ b/docs/guide/use/contact.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Contact
+toc: ../toc.json
+---
+
+{% readj /meta/contact.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/before-begin.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/before-begin.include.md b/docs/guide/use/examples/before-begin.include.md
new file mode 100644
index 0000000..ad9bc19
--- /dev/null
+++ b/docs/guide/use/examples/before-begin.include.md
@@ -0,0 +1,57 @@
+{% include fields.md %}
+
+## Before You Begin
+
+To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven`` (v3) installed.
+
+### Installing Brooklyn
+
+(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.)
+
+{% if SNAPSHOT %}
+
+First, grab a copy of the Brooklyn snapshot distribution you wish to use from
+[the Sonatype snapshot repo]({{ sonatype_repo_groupid_url }}brooklyn-dist/)
+(or build it yourself following instructions [here]({{ site.url }}/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/brooklyncentral/brooklyn-examples.git
+% cd brooklyn-examples
+{% if brooklyn_examples_branch == 'master' %}{% else %}% git checkout {{ brooklyn_examples_branch }}
+{% endif %}% 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.url}}/start/download.html).
+For more information on the Brooklyn CLI and launching apps,
+please visit [this section of the user guide]({{site.url}}/use/guide/management/index.html#cli).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png
new file mode 100644
index 0000000..c34217f
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details-w700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png
new file mode 100644
index 0000000..f47226a
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/console-geoscaling-details.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/console-map-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map-w700.png b/docs/guide/use/examples/global-web-fabric/console-map-w700.png
new file mode 100644
index 0000000..af353a9
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/console-map-w700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/console-map.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/console-map.png b/docs/guide/use/examples/global-web-fabric/console-map.png
new file mode 100644
index 0000000..cd0f811
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/console-map.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png
new file mode 100644
index 0000000..33c811d
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app-w700.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png
new file mode 100644
index 0000000..4e743e3
Binary files /dev/null and b/docs/guide/use/examples/global-web-fabric/geopaas-deployed-app.png differ
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/global-web-fabric/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/global-web-fabric/index.md b/docs/guide/use/examples/global-web-fabric/index.md
new file mode 100644
index 0000000..7231cda
--- /dev/null
+++ b/docs/guide/use/examples/global-web-fabric/index.md
@@ -0,0 +1,378 @@
+---
+layout: guide-normal
+title: Global Web Fabric
+toc: /toc.json
+---
+
+This example shows how to build a multi-site web application *fabric*
+with DNS configured on the front-end to combine the sites,
+routing users to the location closest to them.
+
+It can combine with the [Simple Web Cluster](../webcluster) example
+or the [Portable Cloud Foundry](https://github.com/cloudsoft/brooklyn-cloudfoundry) example,
+but does not assume knowledge of either of these.
+
+{% readj ../before-begin.include.md %}
+
+Now, go to this particular example's directory:
+
+{% highlight bash %}
+% cd global-web-fabric
+{% endhighlight %}
+
+The CLI needs to know where to find your compiled examples. You can set this up by exporting
+the ``BROOKLYN_CLASSPATH`` environment variable in the following way:
+
+{% highlight bash %}
+% export BROOKLYN_CLASSPATH=$(pwd)/target/classes
+{% endhighlight %}
+
+The project ``global-web-fabric`` contains the code used
+in this example under ``src/main/java``.
+
+
+### Setting Up Geographic DNS
+
+This example uses [geoscaling.com](http://www.geoscaling.com) to provide **free** geographic-dependent DNS services.
+This will forward a domain name of your choice to various IPs depending on a script,
+e.g. computing the nearest IP based on latitude and longitude of the requester and the targets.
+Brooklyn will automatically generate and update this script, but you do need to
+create and configure a Geoscaling account:
+
+ 1. Create the free account [here](https://www.geoscaling.com/dns2/?module=register).
+ 1. Click the link in the email you receive.
+ 1. Enter the domain name you wish to use into geoscaling (see below).
+
+The simplest domain name to choose is something unique under `geopaas.org`, e.g. `yourname.geopaas.org`,
+which we have already configured for Geoscaling to manage.
+If you are using your own domain name,
+set its nameservers as advised by geoscaling (e.g. `ns{1,2,3,4}.geoscaling.com`).
+
+Next we need to supply this information to Brooklyn at runtime.
+The simplest way is to create or add the following fields to `~/.brooklyn/brooklyn.properties`:
+
+{% highlight bash %}
+brooklyn.geoscaling.username=yourname
+brooklyn.geoscaling.password=s3cr3t
+brooklyn.geoscaling.primaryDomain=yourname.geopaas.org
+{% endhighlight %}
+
+Replace the values of these fields as appropriate, of course!
+You can, if you prefer, supply (or override) these values in your Brooklyn application.
+
+
+### Setting Up the Locations Database
+
+In order to generate the "closest-IP" script,
+Brooklyn needs a way to find out the latitude and longitude of the
+servers you are using.
+The simplest way to do this is do download the free GeoCityLite binary flatfile
+from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/#Downloads),
+unpack it, and copy it to `~/.brooklyn/GeoLite2-City.mmdb`.
+
+This will be picked up automatically if it is installed.
+You can instead specify to use an online lookup service, such as
+[utrace.de](http://www.utrace.de) by specifying
+`-Dbrooklyn.location.geo.HostGeoLookup=brooklyn.location.geo.UtraceHostGeoLookup`;
+but note this has a cap of 100 per day.
+
+This information is also used to display locations on the map
+in the Brooklyn dashboard.
+Note however that these free services are not 100% accurate;
+they are handy for dev/test but in a production system
+you may wish to specify the geographical information manually in your application,
+or purchase a commercial locations-database subscription.
+
+
+## The Code
+
+Now let's start writing our application.
+The heavy lifting will be done by off-the-shelf Brooklyn classes:
+
+ * `DynamicFabric` will create the entity specified by `factory` in each location it is given
+ * `GeoscalingDnsService` monitors children of a specified entity (the `DynamicFabric`)
+ and adds them as DNS targets for the region they are in
+
+First, however, let's create the Java class -- call it `GlobalWebFabricExample`.
+This will extend the Brooklyn `AbstractApplication`:
+
+{% highlight java %}
+package brooklyn.demo;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import brooklyn.entity.basic.AbstractApplication;
+
+public class GlobalWebFabricExample extends AbstractApplication {
+ @Override
+ public void init() {
+ // TODO create our app!
+ }
+}
+{% endhighlight %}
+
+### The Fabric
+
+The `DynamicFabric` by default has no knowledge of what it will build,
+other than the `factory` it is given to create an entity in each region.
+We'll use the class `ElasticJavaWebAppService.Factory` which creates
+an elastic Java Web App service,
+such as the `ControlledDynamicWebAppCluster` used in the
+[Simple Web Cluster](../webcluster) example, if deploying to VMs,
+or perhaps a `CloudFoundryJavaWebAppCluster` if deploying to a Cloud Foundry location
+(see [brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry)).
+
+{% highlight java %}
+ DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+ .displayName("Web Fabric")
+ .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+ .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH));
+{% endhighlight %}
+
+Here we have specified the WAR to use with `configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)`.
+The war configuration used in the previous example is only available on web-aware entities;
+configuration specified with a ConfigKey can be done on any entity,
+and is inherited at runtime, so this provides a useful way to specify the WAR to use
+even though the web-aware entities are only constructed at runtime.
+
+
+### Stitching the Fabric together with DNS
+
+To stitch these together seamlessly, another entity will run a policy
+which collects the public-facing IP address of each cluster created by the fabric,
+as it comes online, by watching for `SERVICE_UP` sensors.
+First, however, let's make sure any load-balancer proxies (e.g. nginx) in these clusters
+are listening on port 80:
+
+{% highlight java %}
+ DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class)
+ .displayName("Web Fabric")
+ .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory())
+ .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)
+ .configure(AbstractController.PROXY_HTTP_PORT, PortRanges.fromInteger(80)));
+{% endhighlight %}
+
+Let's now define the Geoscaling entity which does the stitching.
+We need to supply the username, password, and primaryDomainName for Geoscaling;
+we'll take this from the `brooklyn.properties` file mentioned above.
+We'll also specify a `smartSubdomainName`, to use Geoscaling's facility for
+lightweight sub-domains to prevent DNS caching and multiple instances of our application
+from confusing us -- e.g. `brooklyn-1234.yourname.geopaas.org`.
+
+{% highlight java %}
+ StringConfigMap config = getManagementContext().getConfig();
+
+ GeoscalingDnsService geoDns = addChild(EntitySpec.create(GeoscalingDnsService.class)
+ .displayName("GeoScaling DNS")
+ .configure("username", checkNotNull(config.getFirst("brooklyn.geoscaling.username"), "username"))
+ .configure("password", checkNotNull(config.getFirst("brooklyn.geoscaling.password"), "password"))
+ .configure("primaryDomainName", checkNotNull(config.getFirst("brooklyn.geoscaling.primaryDomain"), "primaryDomain"))
+ .configure("smartSubdomainName", "brooklyn"));
+{% endhighlight %}
+
+Lastly we need to tell this instance what entity it should monitor
+for children to include as targets:
+
+{% highlight java %}
+ geoDns.setTargetEntityProvider(webFabric);
+{% endhighlight %}
+
+
+
+### Cloud Foundry and other PaaS Targets
+
+At this point our core application is ready, and can be deployed to AWS or another VM cloud.
+This may take between 15 and 30 minutes to run,
+mainly spent downloading software
+(unless of course you specify a pre-configured `imageId` which contains the software).
+
+A quicker alternative is to deploy to a Java Web App platform-as-a-service
+such as Cloud Foundry. A major advantage here is that they can provision very quickly,
+in a matter of seconds. Code for this can be found in the
+[brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry),
+along with an example global-web-fabric app.
+
+
+### Imports
+
+Your imports should look as follows:
+
+{% highlight java %}
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import brooklyn.config.StringConfigMap;
+import brooklyn.entity.basic.AbstractApplication;
+import brooklyn.entity.basic.Attributes;
+import brooklyn.entity.dns.geoscaling.GeoscalingDnsService;
+import brooklyn.entity.group.DynamicFabric;
+import brooklyn.entity.proxy.AbstractController;
+import brooklyn.entity.proxying.EntitySpec;
+import brooklyn.entity.webapp.ElasticJavaWebAppService;
+import brooklyn.location.basic.PortRanges;
+{% endhighlight %}
+
+
+### Use of main method (optional)
+
+In this example, we will use the brooklyn CLI launcher. However, it is possible to write your own main method.
+
+The following static constants are assumed (most of these as in the [Simple Web Cluster](../webcluster) example and others):
+
+ * `WAR_PATH`, pointing to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+ * `DEFAULT_LOCATIONS`, containing a string spec of the locations to deploy to if none are supplied on the command-line;
+ for this example `localhost` will frequently not work unless Geoscaling can see it
+ (i.e. it has a public IP and appropriate firewall settings)
+
+The code (which can safely be omitted) is as follows:
+
+{% highlight java %}
+import brooklyn.launcher.BrooklynLauncher;
+import brooklyn.util.CommandLineUtil;
+
+import com.google.common.base.Joiner;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Lists;
+
+// class definition, and rest of class goes here...
+
+ public static final Logger log = LoggerFactory.getLogger(GlobalWebFabricExample.class);
+
+ // points to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here)
+ public static final String WAR_PATH = "classpath://hello-world-webapp.war";
+
+ // locations to deploy to if none are supplied on the command-line; for this example `localhost` will
+ // frequently not work unless Geoscaling can see it (i.e. it has a public IP and appropriate firewall settings)
+ static final List<String> DEFAULT_LOCATIONS = ImmutableList.of(
+ "aws-ec2:eu-west-1",
+ "aws-ec2:ap-southeast-1",
+ "aws-ec2:us-west-1" );
+
+ public static void main(String[] argv) {
+ List<String> args = Lists.newArrayList(argv);
+ String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+");
+ String locations = CommandLineUtil.getCommandLineOption(args, "--locations", Joiner.on(",").join(DEFAULT_LOCATIONS));
+
+ BrooklynLauncher launcher = BrooklynLauncher.newInstance()
+ .application(EntitySpec.create(StartableApplication.class, GlobalWebFabricExample.class).displayName("Brooklyn Global Web Fabric Example"))
+ .webconsolePort(port)
+ .locations(Arrays.asList(locations))
+ .start();
+
+ Entities.dumpInfo(app);
+ }
+{% endhighlight %}
+
+
+
+## Running the Example
+
+Now let's run this example.
+
+{% highlight bash %}
+${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.GlobalWebFabricExample \
+--location jclouds:aws-ec2:eu-west-1,jclouds:aws-ec2:ap-southeast-1,jclouds:aws-ec2:us-west-1
+{% endhighlight %}
+
+The management web console will start,
+followed by the web-app services in the locations specified
+creating the VM's as needed.
+Let's look at the management web console, on port 8081:
+
+[](console-map.png)
+
+This shows the targets (e.g. Ireland (AWS eu-west-1), Singapore (AWS ap-southeast-1), and California (AWS us-west-1)).
+This also shows the current status of the application.
+
+Navigating to the "applications" tab, we can view sensors, invoke effectors, control policies,
+and track activity,
+for instance if a cluster is slow to start and you want to find out what is going on
+(you'll find additional information in the `brooklyn.log` file).
+Let's drill down on the Geoscaling DNS entity's sensors:
+
+[](console-geoscaling-details.png)
+
+Here we see it has chosen `brooklyn-vOZ7b4BL.martincloudsoft.geopaas.org` as the geo-load-balanced domain name.
+(Yours will be under `yourname.geopaas.org`, unless you chose a different domain earlier.)
+We can also see the hosts it is forwarding to, one for each cluster, corresponding to the
+children of the Web Fabric (propagated from the nginx hostnames, in the case of the ControlledDynamicWebAppCluster instances).
+
+
+### Checking the Web App
+
+Once Geoscaling reports at least one target, you should be able to access it on the geo-load-balanced domain name:
+
+[](geopaas-deployed-app.png)
+
+Under the covers you are being routed to one of the clusters that has been deployed --
+whichever one is closest to you.
+(Due to DNS caching, at your machine or your ISP, clusters which come online after your first lookup
+will not be picked up until TTL expires, typically 10m, although often more if DNS services don't respect TTL.)
+
+
+### Checking DNS Information
+
+Let's find out exactly where we were routed:
+
+{% highlight bash %}
+% dig brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> brooklyn-csgFCzTm.geopaas.org
+
+;; QUESTION SECTION:
+;brooklyn-csgFCzTm.geopaas.org. IN A
+
+;; ANSWER SECTION:
+brooklyn-csgFCzTm.geopaas.org. 120 IN CNAME ec2-46-137-138-4.eu-west-1.compute.amazonaws.com.
+ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. 215 IN A 46.137.138.4
+{% endhighlight %}
+
+This was run from Scotland so it seems a sensible choice.
+(Some portions of the output from `dig` have been removed for readability.)
+
+We can get more information by looking at the TXT records:
+
+{% highlight bash %}
+% dig +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+; <<>> DiG 9.4.3-P3 <<>> +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org
+
+...
+
+geopaas.org. 86400 IN NS ns1.geoscaling.com.
+geopaas.org. 86400 IN NS ns2.geoscaling.com.
+geopaas.org. 86400 IN NS ns3.geoscaling.com.
+geopaas.org. 86400 IN NS ns4.geoscaling.com.
+;; Received 133 bytes from 199.249.112.1#53(a2.org.afilias-nst.info) in 45 ms
+
+brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "Request from [54,-2]-(GB) directed to Ireland (IE)"
+brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "GeoScaling config auto-updated by Brooklyn 2012-04-26 12:27:25 UTC"
+;; Received 189 bytes from 80.87.128.195#53(ns3.geoscaling.com) in 60 ms
+{% endhighlight %}
+
+
+## Next Steps
+
+This example has shown how to create a multi-region fabric, using the abstractions from
+[jclouds](http://jclouds.org) under the covers to make it easy to access different hosting providers
+simultaneously, and using higher-level abstractions in Brooklyn to mix PaaS systems with
+bare-VM (or even bare-metal, if you specify fixed IPs).
+
+This is meant as just the beginning however.
+Here are some questions to think about and code challenges to give you a steer for what to explore next.
+
+
+ 1. The routines used at Geoscaling optimize for latency between the user and the location of the web-cluster.
+ What other strategies might be used? Cost? Compliance? How would you code these?
+
+ 2. This example ignores data, but you clearly can't do that in the real world.
+ When big-data is involved, does this introduce other considerations for optimizing geo-location?
+
+ 3. Add a data tier to this system, such as MySQL or Mongo, or even Hadoop.
+ You might start with a single instance or cluster,
+ but the real fun starts with a fabric, and defining the synchronization/replication strategies
+ between the different clusters.
+ This isn't for the faint-hearted, but whatever you create will certainly be of interest
+ to people in the Brooklyn community.
+ Please [let us know]({{ site.url }}/meta/contact.html) what you've built!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/use/examples/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/use/examples/index.md b/docs/guide/use/examples/index.md
new file mode 100644
index 0000000..15e89dc
--- /dev/null
+++ b/docs/guide/use/examples/index.md
@@ -0,0 +1,18 @@
+---
+layout: guide-normal
+title: Examples
+toc: /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.url}}/dev/tips/update-docs.html)