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:44 UTC
[10/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/dev/tips/release.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/release.md b/docs/dev/tips/release.md
deleted file mode 100644
index 35c5904..0000000
--- a/docs/dev/tips/release.md
+++ /dev/null
@@ -1,286 +0,0 @@
----
-layout: guide-normal
-title: Release Process
-toc: /toc.json
----
-
-<!--
-TODO
-
-vote required? see governance.
-
-
- branch-twice-then-reversion-twice
- e.g. from master=1.0.0_SNAPSHOT we will go to
- create branch: v1.0.0_SNAPSHOT
- reversion master: 1.1.0_SNAPSHOT
- create branch and reversion: v1.0.0_RC1, v1.0.0_SNAPSHOT
- describe scripts for releasing
- docs
-
-update version, using scripts
-
-push examples to repo
-
-push docs to branch and publish
-
--->
-
-Brooklyn is published to two locations:
-
-* Sonatype, for snapshots and for staging releases
-* Maven Central, for full (GA and milestone) releases
-
-Brooklyn artifacts are generally downloaded from:
-
-1. [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.brooklyn%22),
- and (http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.brooklyn%22) for pre 0.7.0 versions
-2. [Apache](https://repository.apache.org/index.html#nexus-search;quick~org.apache.brooklyn),
-2. [Sonatype](https://oss.sonatype.org/index.html#nexus-search;quick~io.brooklyn) for pre 0.7.0 versions
-3. [GitHub](https://github.com/apache/incubator-brooklyn).
-
-
-To publish:
-
-* a snapshot release:
- * mvn deploy to Sonatype
- * (optional) publish versioned docs to brooklyncentral.github.com project
-* a (milestone) release:
- * same as above, but with some git versioning
- * deploy to Sonatype, then release to Maven Central
- * deploy a version branch to brooklyn-examples
- * deploy (or update) versioned docs
-* a major release:
- * same as above, and
- * in addition to versioned examples, update brooklyn-examples master to match the current (stable) release
- * in addition to versioned docs, publish full (front page) docs to brooklyncentral.github.com project
- * bump the snapshot version in brooklyn master to the next release
-
-
-
-## Configuration
-
-Your .m2/settings.xml must be configured with the right credentials for Sonatype
-
- <servers>
- ...
- <server>
- <username> ... </username>
- <password> ... </password>
- <id>sonatype-nexus-snapshots</id>
- </server>
- <server>
- <username> ... </username>
- <password> ... </password>
- <id>sonatype-nexus-staging</id>
- </server>
- ...
- </servers>
-You must be configured to sign artifacts using PGP.
-
-If this is the first time you have used Sonatype, the [Sonatype - Maven Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) is required reading.
-
-The code snippets below use the following variables:
-{% highlight bash %}
-
-export BROOKLYN_DIR=/path/to/brooklyncentral-brooklyn
-export EXAMPLES_DIR=/path/to/brooklyncentral-brooklyn-examples
-export SITE_DIR=/path/to/brooklyncentral-brooklyncentral.github.com
-
-export SNAPSHOT_VERSION=0.6.0-SNAPSHOT
-export RELEASE_VERSION=0.6.0-M1
-{% endhighlight %}
-
-
-## Preparing a Snapshot Release
-
-### Deploy to Sonatype
-
-Execute the following:
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-### (Option) Publish snapshot docs.
-
-(Only required if there have been significant changes to docs or java docs.)
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout master
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$SNAPSHOT_VERSION
-mkdir $SITE_DIR/v/$SNAPSHOT_VERSION
-cp -r _site/* $SITE_DIR/v/$SNAPSHOT_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$SNAPSHOT_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $SNAPSHOT_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-
-## Preparing a (Milestone) Release
-
-### Prepare a Release Branch
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR
-git checkout -b $RELEASE_VERSION
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $RELEASE_VERSION
-git commit -a -m "Changed version to $RELEASE_VERSION"
-git push -u upstream $RELEASE_VERSION
-
-{% endhighlight %}
-
-### Deploy to Sonatype, and Close the repo.
-
-{% highlight bash %}
-mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
-{% endhighlight %}
-
-* Go to [oss.sonatype.org ... #stagingRepositories](https://oss.sonatype.org/index.html#stagingRepositories) (again, need credentials)
-* 'Close' the repo
-* Email the closed repo address to brooklyn-dev list, have people download and confirm it works.
-
-### Update the brooklyn-examples repo's version Branch
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-git checkout -b $RELEASE_VERSION
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "branch for $RELEASE_VERSION"
-git push -u origin $RELEASE_VERSION
-
-{% endhighlight %}
-
-
-### Update the Versioned Docs
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-git checkout $RELEASE_VERSION
-
-if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
-
-# Build the docs
-_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
-
-# Wipe any previous edition of the same version, replacing with new build.
-rm -rf $SITE_DIR/v/$RELEASE_VERSION
-mkdir $SITE_DIR/v/$RELEASE_VERSION
-cp -r _site/* $SITE_DIR/v/$RELEASE_VERSION/
-
-# and push, causing GitHub to republish with updated /v/$RELEASE_VERSION/
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated version docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-## Preparing a Full Release
-
-Complete *all* above steps.
-
-### Deploy to Maven Central
-
-* Confirm that the closed Sonatype repo has no errors
-* Return to [Sonatype: Staging Repositories](https://oss.sonatype.org/index.html#stagingRepositories)
-* 'Release' the repo
-
-### Deploy the Examples master branch.
-
-{% highlight bash %}
-
-cd $EXAMPLES_DIR
-
-pushd $BROOKLYN_DIR
-git checkout $RELEASE_VERSION
-popd
-
-if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
-git checkout master
-rm -rf *
-cp -r $BROOKLYN_DIR/examples/* .
-rm -rf target
-git add -A
-git commit -m "Updated to $RELEASE_VERSION"
-git push -u origin master
-
-{% endhighlight %}
-
-### Update the brooklyn.io Front Page Version
-
-{% highlight bash %}
-
-cd $BROOKLYN_DIR/docs
-
-pushd $SITE_DIR
-# remove old root files, but not the previous version in /v/
-if [ -f start/index.html ] ; then
- for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
-else
- echo IN WRONG DIRECTORY $SITE_DIR - export SITE_DIR to continue
- exit 1
-fi
-popd
-
-# re-build for hosting at / rather than at /v/VERSION/
-_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
-
-# copy to site dir
-cp -r _site/* $SITE_DIR/
-
-# and git push
-pushd $SITE_DIR
-git add -A .
-git commit -m "Updated root docs for version $RELEASE_VERSION"
-git push
-popd
-
-{% endhighlight %}
-
-
-### Announce
-* Email the Dev and Users mailing lists.
-* Tweet from [@brooklyncentral](https://twitter.com/brooklyncentral)
-
-### Update Snapshot Version
-
-{% highlight bash %}
-
-export NEW_SNAPSHOT_VERSION=0.7.0-SNAPSHOT
-
-cd $BROOKLYN_DIR
-git checkout master
-usage/scripts/change-version.sh $SNAPSHOT_VERSION $NEW_SNAPSHOT_VERSION
-git commit -a -m "Changed version to $NEW_SNAPSHOT_VERSION"
-git push -u upstream master
-
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/standards.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/standards.md b/docs/dev/tips/standards.md
deleted file mode 100644
index 259ab20..0000000
--- a/docs/dev/tips/standards.md
+++ /dev/null
@@ -1,15 +0,0 @@
----
-layout: guide-normal
-title: Code Standards
-toc: /toc.json
----
-
-Without being too restrictive about how you have to code as part of Brooklyn,
-there are some style points that really make life easier when sharing code
-among ourselves:
-
-* Use spaces (not tabs!) with 4 spaces indentation
-* Keep line length <=128
-* Don't reformat code or organize imports unless there's very good
- reason (this makes history and merges much harder)
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/toc.json
----------------------------------------------------------------------
diff --git a/docs/dev/tips/toc.json b/docs/dev/tips/toc.json
deleted file mode 100644
index 0be0aba..0000000
--- a/docs/dev/tips/toc.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-{ "title": "Miscellany",
- "file": "{{ site.url }}/dev/tips/index.html" },
-{ "title": "Logging",
- "file": "{{ site.url }}/dev/tips/logging.html" },
-{ "title": "Code Standards",
- "file": "{{ site.url }}/dev/tips/standards.html" },
-{ "title": "Local Artifact Repo",
- "file": "{{ site.url }}/dev/tips/local-artifact-repo.html" },
-{ "title": "Updating Docs",
- "file": "{{ site.url }}/dev/tips/update-docs.html" },
-{ "title": "Release Process",
- "file": "{{ site.url }}/dev/tips/release.html" }
-]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/dev/tips/update-docs.md
----------------------------------------------------------------------
diff --git a/docs/dev/tips/update-docs.md b/docs/dev/tips/update-docs.md
deleted file mode 100644
index 5d72e47..0000000
--- a/docs/dev/tips/update-docs.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-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/dev/toc.json
----------------------------------------------------------------------
diff --git a/docs/dev/toc.json b/docs/dev/toc.json
deleted file mode 100644
index f22e840..0000000
--- a/docs/dev/toc.json
+++ /dev/null
@@ -1,26 +0,0 @@
-[
-{ "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/dev/build/debugging-remote-brooklyn.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/debugging-remote-brooklyn.md b/docs/guide/dev/build/debugging-remote-brooklyn.md
new file mode 100644
index 0000000..d924804
--- /dev/null
+++ b/docs/guide/dev/build/debugging-remote-brooklyn.md
@@ -0,0 +1,140 @@
+---
+layout: guide-normal
+title: Brooklyn Remote Debugging
+toc: /toc.json
+---
+
+Usually during development, you will be running Brooklyn from your IDE (see [IDE Setup](ide.html)), in which case
+debugging is as simple as setting a breakpoint. There may however be times when you need to debug an existing remote
+Brooklyn instance (often referred to as Resident Brooklyn, or rBrooklyn) on another machine, usually in the cloud.
+
+Thankfully, the tools are available to do this, and setting it up is quite straightforward. The steps are as follows:
+
+* [Getting the right source code version](#sourceCodeVersion)
+* [Starting Brooklyn with a debug listener](#startingBrooklyn)
+* [Creating an SSH tunnel](#sshTunnel)
+* [Connecting your IDE](#connectingIDE)
+
+## <a name="sourceCodeVersion"></a>Getting the right source code version
+The first step is to ensure that your local copy of the source code is at the version used to build the remote Brooklyn
+instance. The git commit that was used to build Brooklyn is available via the REST API:
+
+```
+http://<remote-address>:<remote-port>/v1/server/version
+```
+
+This should return details of the build as a JSON string similar to the following (formatted for clarity):
+
+```JSON
+{
+ "version": "0.7.0-SNAPSHOT",
+ "buildSha1": "c0fdc15291702281acdebf1b11d431a6385f5224",
+ "buildBranch": "UNKNOWN"
+}
+```
+
+The value that we're interested in is `buildSha1`. This is the git commit that was used to build Brooklyn. We can now
+checkout and build the Brooklyn code at this commit by running the following in the root of your Brooklyn repo:
+
+```
+git checkout c0fdc15291702281acdebf1b11d431a6385f5224
+mvn clean install -DskipTests
+```
+
+Whilst building the code isn't strictly necessary, it can help prevent some IDE issues.
+
+## <a name="startingBrooklyn"></a>Starting Brooklyn with a debug listener
+By default, Brooklyn does not listen for a debugger to be attached, however this behaviour can be set by setting JAVA_OPTS,
+which will require a restart of the Brooklyn node. To do this, SSH to the remote Brooklyn node and run the following in the
+root of the Brooklyn installation:
+
+```
+# NOTE: Running this kill command will lose existing apps and machines if persistence is disabled.
+kill `cat pid_java`
+export JAVA_OPTS="-Xms256m -Xmx1g -XX:MaxPermSize=256m -agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8888,server=y,suspend=n"
+bin/brooklyn launch &
+```
+
+If `JAVA_OPTS` is not set, Brooklyn will automatically set it to `"-Xms256m -Xmx1g -XX:MaxPermSize=256m"`, which is why
+we have prepended the agentlib settings with these values here.
+
+You should see the following in the console output:
+
+```
+Listening for transport dt_socket at address: 8888
+```
+
+This will indicate the Brooklyn is listening on port 8888 for a debugger to be attached.
+
+## <a name="sshTunnel"></a>Creating an SSH tunnel
+If port 8888 is accessible on the remote Brooklyn server, then you can skip this step and simply use the address of the
+server in place of 127.0.0.1 in the [Connecting your IDE](#connectingIDE) section below. It will normally be possible to
+make the port accessible by configuring Security Groups, iptables, endpoints etc., but for a quick ad-hoc connection it's
+usually simpler to create an SSH tunnel. This will create an open SSH connection that will redirect traffic from a port
+on a local interface via SSH to a port on the remote machine. To create the tunnel, run the following on your local
+machine:
+
+```
+# replace this with the address or IP of the remote Brooklyn node
+REMOTE_HOST=<remote-address>
+# if you wish to use a different port, this value must match the port specified in the JAVA_OPTS
+REMOTE_PORT=8888
+# if you wish to use a different local port, this value must match the port specified in the IDE configuration
+LOCAL_PORT=8888
+# set this to the login user you use to SSH to the remote Brooklyn node
+SSH_USER=root
+# The private key file used to SSH to the remote node. If you use a password, see the alternative command below
+PRIVATE_KEY_FILE=~/.ssh/id_rsa
+
+ssh -YNf -i $PRIVATE_KEY_FILE -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
+
+```
+
+If you use a password to SSH to the remote Brooklyn node, simply remove the `-i $PRIVATE_KEY_FILE` section like so:
+
+```
+ssh -YNf -l $SSH_USER -L $LOCAL_PORT:127.0.0.1:$REMOTE_PORT $REMOTE_HOST
+```
+
+If you are using a password to connect, you will be prompted to enter your password to connect to the remote node upon
+running the SSH command.
+
+The SSH tunnel should now be redirecting traffic from port 8888 on the local 127.0.0.1 network interface via the SSH
+tunnel to port 8888 on the remote 127.0.0.1 interface. It should now be possible to connect the debugger and start
+debugging.
+
+## <a name="connectingIDE"></a> Connecting your IDE
+Setting up your IDE will differ depending upon which IDE you are using. Instructions are given here for Eclipse and
+IntelliJ, and have been tested with Eclipse Luna and IntelliJ Ultimate 14.
+
+### Eclipse Setup
+To debug using Eclipse, first open the Brooklyn project in Eclipse (see [IDE Setup](ide.html)).
+
+Now create a debug configuration by clicking `Run` | `Debug Configurations...`. You will then be presented with the
+Debug Configuration dialog.
+
+Select `Remote Java Application` from the list and click the 'New' button to create a new configuration. Set the name
+to something suitable such as 'Remote debug on 8888'. The Project can be set to any of the Brooklyn projects, the
+Connection Type should be set to 'Standard (Socket Attach)'. The Host should be set to either localhost or 127.0.0.1
+and the Port should be set to 8888. Click 'Debug' to start debugging.
+
+### IntelliJ Setup
+To debug using IntelliJ, first open the Brooklyn project in IntelliJ (see [IDE Setup](ide.html)).
+
+Now create a debug configuration by clicking `Run` | `Edit Configurations`. You will then be presented with the
+Run/Debug Configurations dialog.
+
+Click on the `+` button and select 'Remote' to create a new remote configuration. Set the name to something suitable
+such as 'Remote debug on 8888'. The first three sections simply give the command line arguments for starting the java
+process using different versions of java, however we have already done this in
+[Starting Brooklyn with a debug listener](#startingBrooklyn). The Transport option should be set to 'Socket', the Debugger Mode should be set to 'Attach', the
+Host should be set to localhost or 127.0.0.1 (or the address of the remote machine if you are not using an SSH tunnel),
+and the Port should be set to 8888. The 'Search sources' section should be set to `<whole project>`. Click OK to save the
+configuration, then select the configuration from the configurations drop-down and click the debug button to start
+debugging.
+
+### Testing
+The easiest way to test that remote debugging has been setup correctly is to set a breakpoint and see if it is hit. An
+easy place to start is to create a breakpoint in the `ServerResource.java` class, in the `getStatus()`
+method.
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/developers-catalog.xml
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/developers-catalog.xml b/docs/guide/dev/build/developers-catalog.xml
new file mode 100644
index 0000000..f190024
--- /dev/null
+++ b/docs/guide/dev/build/developers-catalog.xml
@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<catalog>
+ <name>Brooklyn Developers Catalog</name>
+
+ <template type="io.cloudsoft.cloudera.SampleClouderaManagedCluster" name="Cloudera CDH4">
+ <description>Launches Cloudera Distribution for Hadoop Manager with a Cloudera Manager and an initial cluster of 4 CDH nodes
+ (resizable) and default services including HDFS, MapReduce, and HBase</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloudera-icon.jpeg</iconUrl>
+ </template>
+
+ <template type="io.cloudsoft.mapr.MyM3App" name="M3 Cluster">
+ <description>Map Reduce using MapR</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mapr-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.SimpleMongoDBReplicaSet" name="Simple MongoDB replica set">
+ <description>Launches a MongoDB replica set</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/mongo-db-icon.jpeg</iconUrl>
+ </template>
+
+ <template type="brooklyn.example.cloudfoundry.MovableCloudFoundryClusterExample" name="Stackato Movable CloudFoundry Cluster Example">
+ <description>Brooklyn Stackato</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
+ </template>
+
+ <template type="brooklyn.example.cloudfoundry.MovableElasticWebAppCluster" name="Stackato Movable Elastic Web Cluster">
+ <description>Brooklyn Stackato</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/stackato-icon.jpeg</iconUrl>
+ </template>
+
+ <template type="io.cloudsoft.socialapps.drupal.examples.BasicDrupalApp" name="Basic Drupal App">
+ <description>Brooklyn Social Apps - Basic. (Requires Debian)</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-icon.png</iconUrl>
+ </template>
+
+ <template type="io.cloudsoft.socialapps.drupal.examples.ClusteredDrupalApp" name="Clustered Drupal App">
+ <description>Brooklyn Social Apps - Cluster. (Requires Debian)</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/drupal-text-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.extras.cloudfoundry.CloudFoundryJavaClusterExample" name="Cloud Foundry Web App">
+ <description>Deploys a web application to a Cloud Foundry target</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cloud-foundry-logo-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.SimpleRedisCluster" name="Redis Cluster">
+ <description>Launches a Redis cluster</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/redis-sq-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.SimpleCassandraCluster" name="Cassandra Cluster">
+ <description>Launches a Cassandra cluster</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/cassandra-sq-icon.jpg</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.SimpleCouchDBCluster" name="CouchDB Cluster">
+ <description>Launches a CouchDB cluster</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/couchdb-logo-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo 2: GeoDNS Web Fabric DB">
+ <description>Deploys a demonstration web application to JBoss clusters around the world</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
+ </template>
+
+ <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo 1: Web Cluster with DB">
+ <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description>
+ <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat-icon.png</iconUrl>
+ </template>
+
+
+ <classpath>
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-web-cluster-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-SNAPSHOT/brooklyn-example-global-web-fabric-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-global-web-fabric/0.7.0-SNAPSHOT/brooklyn-example-global-web-fabric-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-portable-cloudfoundry/0.7.0-SNAPSHOT/brooklyn-example-portable-cloudfoundry-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-web-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-web-cluster-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.7.0-SNAPSHOT/brooklyn-example-hello-world-sql-webapp-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-messaging-pubsub/0.7.0-SNAPSHOT/brooklyn-example-simple-messaging-pubsub-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-parent/0.7.0-SNAPSHOT/brooklyn-examples-parent-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-hello-world-webapp/0.7.0-SNAPSHOT/brooklyn-example-hello-world-webapp-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-example-simple-nosql-cluster/0.7.0-SNAPSHOT/brooklyn-example-simple-nosql-cluster-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ <entry>file://~/.m2/repository/io/brooklyn/example/brooklyn-examples-webapps-parent/0.7.0-SNAPSHOT/brooklyn-examples-webapps-parent-0.7.0-SNAPSHOT.jar</entry> <!-- BROOKLYN_VERSION -->
+ </classpath>
+
+
+</catalog>
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/eclipse.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/eclipse.include.md b/docs/guide/dev/build/eclipse.include.md
new file mode 100644
index 0000000..b1cf5ea
--- /dev/null
+++ b/docs/guide/dev/build/eclipse.include.md
@@ -0,0 +1,15 @@
+
+- Maven Plugin: m2e from [download.eclipse.org/technology/m2e/releases](http://download.eclipse.org/technology/m2e/releases), or for kepler [http://download.eclipse.org/releases/kepler](http://download.eclipse.org/releases/kepler)
+ (typically bundled with Eclipse or available in the default update site set)
+
+- Git Plugin: egit from [download.eclipse.org/egit/updates](http://download.eclipse.org/egit/updates)
+ (typically bundled with Eclipse or available in the default update site set)
+
+- Groovy Plugin: GRECLIPSE from
+ [dist.springsource.org/release/GRECLIPSE/e4.3](http://dist.springsource.org/release/GRECLIPSE/e4.3)
+ (or for Eclipse [4.2](http://dist.springsource.org/release/GRECLIPSE/e4.2)
+ or [3.7](http://dist.springsource.org/release/GRECLIPSE/e3.7)).
+ Be sure to include Groovy 2.3.4 compiler support and Maven-Eclipse (m2e) support.
+ More details are at the [groovy update site](http://groovy.codehaus.org/Eclipse+Plugin).
+
+- TestNG Plugin: beust TestNG from [beust.com/eclipse](http://beust.com/eclipse)
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/ide.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/ide.md b/docs/guide/dev/build/ide.md
new file mode 100644
index 0000000..bdc7478
--- /dev/null
+++ b/docs/guide/dev/build/ide.md
@@ -0,0 +1,123 @@
+---
+layout: guide-normal
+title: IDE Setup
+toc: /toc.json
+---
+
+Gone are the days when IDE integration always just works... Maven and Eclipse fight,
+neither quite gets along perfectly with Groovy,
+git branch switches (sooo nice) can be slow, etc etc.
+
+But with a bit of a dance the IDE can still be your friend,
+making it much easier to run tests and debug.
+
+As a general tip, don't always trust the IDE to build correctly; if you hit a snag,
+do a command-line ``mvn clean install`` (optionally with ``-DskipTests``)
+then refresh the project.
+
+See instructions below for specific IDEs.
+
+
+## Eclipse
+
+If you're an Eclipse user, you'll probably want the Maven (m2e) plugin
+and the Groovy Eclipse plugin (used for testing and examples primarily).
+You may also want Git and TestNG plugins.
+You can install these using Help -> Install New Software, or from the Eclipse Marketplace:
+
+{% readj eclipse.include.md %}
+
+As of this writing, Eclipse 4.2 and Eclipse 4.3 are commonly used,
+and the codebase can be imported (Import -> Existing Maven Projects)
+and successfully built and run inside an IDE.
+However there are quirks, and mileage may vary.
+
+If you encounter issues, the following hints may be helpful:
+
+* If you attempt to import projects before the plugins are installed, you may encounter errors such as
+ '``No marketplace entries found to handle maven-compiler-plugin:2.3.2:compile in Eclipse``',
+ and the projects will not be recognized as java projects. If you do, simply cancel the import
+ (or delete the imported projects if they have been imported) and install the plugins as described above.
+ If you have installed plugins from alternative locations, remove them and re-install them from the locations
+ specified above.
+
+* A quick command-line build (`mvn clean install -DskipTests`) followed by a workspace refresh
+ can be useful to re-populate files which need to be copied to `target/`
+
+* m2e likes to put `excluding="**"` on `resources` directories; if you're seeing funny missing files
+ (things like not resolving jclouds/aws-ec2 locations or missing WARs), try building clean install
+ from the command-line then doing Maven -> Update Project (clean uses a maven-replacer-plugin to fix
+ `.classpath`s).
+ Alternatively you can go through and remove these manually in Eclipse (Build Path -> Configure)
+ or the filesystem, or use
+ the following command to remove these rogue blocks in the generated `.classpath` files:
+
+{% highlight bash %}
+% find . -name .classpath -exec sed -i.bak 's/[ ]*..cluding="[\*\/]*\(\.java\)*"//g' {} \;
+{% endhighlight %}
+
+* If m2e reports import problems, it is usually okay (even good) to mark all to "Resolve All Later".
+ The build-helper connector is useful if you're prompted for it, but
+ do *not* install the Tycho OSGi configurator (this causes show-stopping IAE's, and we don't need Eclipse to make bundles anyway).
+ You can manually mark as permanently ignored certain errors;
+ this updates the pom.xml (and should be current).
+
+* You may need to ensure ``src/main/{java,resources}`` is created in each project dir,
+ if (older versions) complain about missing directories,
+ and the same for ``src/test/{java,resources}`` *if* there are tests (``src/test`` exists):
+
+{% highlight bash %}
+find . \( -path "*/src/main" -or -path "*/src/test" \) -exec echo {} \; -exec mkdir -p {}/{java,resources} \;
+{% endhighlight %}
+
+* You may need to add the groovy nature (or even java nature) to projects;
+ with some maven-eclipse plugins this works fine,
+ but for others (older ones) you may need to handcraft these
+ (either right-click the project in the Package Explorer and choose Configure,
+ or edit the ``.project`` manually adding it to the project properties).
+ The tips [for jclouds maven-eclipse](http://www.jclouds.org/documentation/devguides/using-eclipse) might be helpful.
+
+If the pain starts to be too much, come find us on IRC #brooklyncentral or [elsewhere]({{site.url}}/meta/contact.html) and we can hopefully share our pearls.
+(And if you have a tip we haven't mentioned please let us know that too!)
+
+
+
+## IntelliJ IDEA
+
+To develop or debug Brooklyn in IntelliJ, you will need to ensure that the Groovy and TestNG plugins are installed
+via the IntelliJ IDEA | Preferences | Plugins menu. Once installed, you can open Brooklyn from the root folder,
+(e.g. ``~/myfiles/brooklyn``) which will automatically open the subprojects.
+
+There have previously been issues where the java 6 compiler incorrectly identified the return type of functions that use
+generics. These issues have been refactored away, however may return in future. If so, you can either set the java compiler
+level to 1.7, or setup IntelliJ to use the Eclipse compiler as per the instructions provided by JetBeans:
+
+> The problem seems to be caused by bug in java compiler from JDK 1.6, it is known to sometimes produce compilation
+> errors for complicated code involving generic types. Java compiler from JDK 1.7 compiles your code successfully so I would
+> recommend you to consider upgrading to JDK 1.7. If it isn't possible you can switch to Eclipse Compiler (Settings |
+> Compiler | Java Compiler | "Use Compiler" combobox).
+
+
+## Netbeans
+
+Tips from Netbeans users wanted!
+
+
+
+## Debugging Tips
+
+To debug Brooklyn, create a launch configuration which launches the ``BrooklynJavascriptGuiLauncher`` class. NOTE: You may
+need to add additional projects or folders to the classpath of the run configuration (e.g. add the brooklyn-software-nosql
+project if you wish to deploy a MongoDBServer). You will also need to ensure that the working directory is set to the jsgui
+folder. For IntelliJ, you can set the 'Working directory' of the Run/Debug Configuration to ``$MODULE_DIR/../jsgui``. For
+Eclipse, use the default option of ``${workspace_loc:brooklyn-jsgui}``.
+
+To debug the jsgui (the Brooklyn web console), you will need to build Brooklyn with -DskipOptimization to prevent the build from minifying the javascript.
+When building via the command line, use the command ``mvn clean install -DskipOptimization``, and if you are using IntelliJ IDEA, you can add the option
+to the Maven Runner by clicking on the Maven Settings icon in the Maven Projects tool window and adding the ``skipOptimization`` property with no value.
+
+When running at the command line you can enable remote connections so that one can attach a debugger to the Java process:
+ Run Java with the following on the command line or in JAVA_OPTS: ``-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005``
+
+To debug a brooklyn instance that has been run with the above JAVA_OPTS, create a remote build configuration (IntelliJ -
+Run | Edit Configurations | + | Remote) with the default options, ensuring the port matches the address specified in JAVA_OPTS.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/index.md b/docs/guide/dev/build/index.md
new file mode 100644
index 0000000..7dd3412
--- /dev/null
+++ b/docs/guide/dev/build/index.md
@@ -0,0 +1,184 @@
+---
+layout: guide-normal
+title: Maven Build
+toc: /toc.json
+---
+
+## The Basics
+
+To build the code, you need Maven (v3) installed and Java (1.6).
+With that in place, you should be able to build everything with a:
+
+{% highlight bash %}
+brooklyn% mvn clean install
+{% endhighlight %}
+
+Key things to note if you're new to Maven:
+
+* You may need more JVM memory, e.g. at the command-line (or in `.profile`):
+
+ ``export MAVEN_OPTS="-Xmx1024m -Xms512m -XX:MaxPermSize=256m``
+
+* You can do this in specific projects as well.
+
+* Add ``-DskipTests`` to skip tests.
+
+* Run ``-PIntegration`` to run integration tests, or ``-PLive`` to run live tests
+ ([tests described here](tests.html))
+
+* Nearly all the gory details are in the root ``pom.xml``, which is referenced by child project poms.
+
+* You can also open and use the code in your favourite IDE,
+ although you may hit a few **[snags](ide.html)**
+ (that link has some tips for resolving them too)
+
+
+## When the RAT Bites
+
+We use RAT to ensure that all files are compliant to Apache standards. Most of the time you shouldn't see it or need to know about it, but if it detects a violation, you'll get a message such as:
+
+ [ERROR] Failed to execute goal org.apache.rat:apache-rat-plugin:0.10:check (default) on project brooklyn-parent: Too many files with unapproved license: 1 See RAT report in: /Users/alex/Data/cloudsoft/dev/gits/brooklyn/target/rat.txt -> [Help 1]
+
+If there's a problem, see the file `rat.txt` in the `target` directory of the failed project. (Maven will show you this link in its output.)
+
+Often the problem is one of the following:
+
+* You've added a file which requires the license header but doesn't have it
+
+ **Resolution:** Simply copy the header from another file
+
+* You've got some temporary files which RAT things should have headers
+
+ **Resolution:** Move the files away, add headers, or turn off RAT (see below)
+
+* The project structure has changed and you have stale files (e.g. in a `target` directory)
+
+ **Resolution:** Remove the stale files, e.g. with `git clean -df` (and if needed a `find . -name target -prune -exec rm -rf {} \;` to delete folders named `target`)
+
+To disable RAT checking on a build, set `rat.ignoreErrors`, e.g. `mvn -Drat.ignoreErrors=true clean install`. (But note you will need RAT to pass in order for a PR to be accepted!)
+
+If there is a good reason that a file, pattern, or directory should be permanently ignored, that is easy to add inside the root `pom.xml`.
+
+
+## Other Handy Hints
+
+* On some **Ubuntu** (e.g. 10.4 LTS) maven v3 is not currently available from the repositories.
+ Some instructions for installing at are [at superuser.com](http://superuser.com/questions/298062/how-do-i-install-maven-3).
+
+* The **mvnf** script
+ ([get the gist here](https://gist.github.com/2241800))
+ simplifies building selected projects, so if you just change something in ``software-webapp``
+ and then want to re-run the examples you can do:
+
+ ``examples/simple-web-cluster% mvnf ../../{software/webapp,usage/all}``
+
+* The **developers catalog** ([developers-catalog.xml](developers-catalog.xml)) uses artifacts from your local `~/.m2/repository/...` (after building from source). This avoids unnecessary web requests to Maven Central or Sonatype, and will allow you to work off-line.
+
+ ``wget {{site.url}}/dev/build/developers-catalog.xml > ~/.brooklyn/catalog.xml``
+
+## Appendix: Sample Output
+
+A healthy build will look something like the following,
+including a few warnings (which we have looked into and
+understand to be benign and hard to get rid of them,
+although we'd love to if anyone can help!):
+
+{% highlight bash %}
+brooklyn% mvn clean install
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Build Order:
+[INFO]
+[INFO] Brooklyn Parent Project
+[INFO] Brooklyn Utilities to Support Testing (listeners etc)
+[INFO] Brooklyn Logback Includable Configuration
+[INFO] Brooklyn Common Utilities
+[INFO] Brooklyn Groovy Utilities
+[INFO] Brooklyn API
+
+...
+
+[WARNING] Ignoring project type war - supportedProjectTypes = [jar]
+
+...
+
+[WARNING] We have a duplicate org/xmlpull/v1/XmlPullParser.class in /Users/aled/.m2/repository/xpp3/xpp3_min/1.1.4c/xpp3_min-1.1.4c.jar
+
+...
+
+[INFO] — maven-assembly-plugin:2.3:single (build-distribution-dir) @ brooklyn-dist —
+[INFO] Reading assembly descriptor: src/main/config/build-distribution-dir.xml
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+[INFO] Copying files to /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist
+[WARNING] Assembly file: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-dist is not a regular file (it may be a directory). It cannot be attached to the project build for installation or deployment.
+
+...
+
+[INFO] — maven-assembly-plugin:2.3:single (build-distribution-archive) @ brooklyn-dist —
+[INFO] Reading assembly descriptor: src/main/config/build-distribution-archive.xml
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+[INFO] Building tar: /Users/aled/repos/apache/incubator-brooklyn/usage/dist/target/brooklyn-0.7.0-SNAPSHOT-dist.tar.gz
+[WARNING] Cannot include project artifact: io.brooklyn:brooklyn-dist:jar:0.7.0-SNAPSHOT; it doesn't have an associated file or directory.
+
+...
+
+[WARNING] Don't override file /Users/aled/repos/apache/incubator-brooklyn/usage/archetypes/quickstart/target/test-classes/projects/integration-test-1/project/brooklyn-sample/src/main/resources/sample-icon.png
+
+...
+
+[INFO] Reactor Summary:
+[INFO]
+[INFO] Brooklyn Parent Project ........................... SUCCESS [3.072s]
+[INFO] Brooklyn Utilities to Support Testing (listeners etc) SUCCESS [3.114s]
+[INFO] Brooklyn Logback Includable Configuration ......... SUCCESS [0.680s]
+[INFO] Brooklyn Common Utilities ......................... SUCCESS [7.263s]
+[INFO] Brooklyn Groovy Utilities ......................... SUCCESS [5.193s]
+[INFO] Brooklyn API ...................................... SUCCESS [2.146s]
+[INFO] Brooklyn Test Support ............................. SUCCESS [2.517s]
+[INFO] CAMP Server Parent Project ........................ SUCCESS [0.075s]
+[INFO] CAMP Base ......................................... SUCCESS [4.079s]
+[INFO] Brooklyn REST Swagger Apidoc Utilities ............ SUCCESS [1.983s]
+[INFO] Brooklyn Logback Configuration .................... SUCCESS [0.625s]
+[INFO] CAMP Server ....................................... SUCCESS [5.446s]
+[INFO] Brooklyn Core ..................................... SUCCESS [1:24.122s]
+[INFO] Brooklyn Policies ................................. SUCCESS [44.425s]
+[INFO] Brooklyn Hazelcast Storage ........................ SUCCESS [7.143s]
+[INFO] Brooklyn Jclouds Location Targets ................. SUCCESS [16.488s]
+[INFO] Brooklyn Secure JMXMP Agent ....................... SUCCESS [8.634s]
+[INFO] Brooklyn JMX RMI Agent ............................ SUCCESS [2.315s]
+[INFO] Brooklyn Software Base ............................ SUCCESS [28.538s]
+[INFO] Brooklyn Network Software Entities ................ SUCCESS [3.896s]
+[INFO] Brooklyn OSGi Software Entities ................... SUCCESS [4.589s]
+[INFO] Brooklyn Web App Software Entities ................ SUCCESS [17.484s]
+[INFO] Brooklyn Messaging Software Entities .............. SUCCESS [7.106s]
+[INFO] Brooklyn Database Software Entities ............... SUCCESS [5.229s]
+[INFO] Brooklyn NoSQL Data Store Software Entities ....... SUCCESS [11.901s]
+[INFO] Brooklyn Monitoring Software Entities ............. SUCCESS [4.027s]
+[INFO] Brooklyn CAMP REST API ............................ SUCCESS [15.285s]
+[INFO] Brooklyn REST API ................................. SUCCESS [4.489s]
+[INFO] Brooklyn REST Server .............................. SUCCESS [30.270s]
+[INFO] Brooklyn REST Client .............................. SUCCESS [7.007s]
+[INFO] Brooklyn REST JavaScript Web GUI .................. SUCCESS [24.397s]
+[INFO] Brooklyn Launcher ................................. SUCCESS [15.923s]
+[INFO] Brooklyn Command Line Interface ................... SUCCESS [9.279s]
+[INFO] Brooklyn All Things ............................... SUCCESS [13.875s]
+[INFO] Brooklyn Distribution ............................. SUCCESS [49.370s]
+[INFO] Brooklyn Quick-Start Project Archetype ............ SUCCESS [12.053s]
+[INFO] Brooklyn Examples Aggregator Project .............. SUCCESS [0.085s]
+[INFO] Brooklyn Examples Support Aggregator Project - Webapps SUCCESS [0.053s]
+[INFO] hello-world-webapp Maven Webapp ................... SUCCESS [0.751s]
+[INFO] hello-world-sql-webapp Maven Webapp ............... SUCCESS [0.623s]
+[INFO] Brooklyn Simple Web Cluster Example ............... SUCCESS [5.398s]
+[INFO] Brooklyn Global Web Fabric Example ................ SUCCESS [3.176s]
+[INFO] Brooklyn Simple Messaging Publish-Subscribe Example SUCCESS [3.217s]
+[INFO] Brooklyn NoSQL Cluster Examples ................... SUCCESS [6.790s]
+[INFO] Brooklyn QA ....................................... SUCCESS [7.117s]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 8:33.983s
+[INFO] Finished at: Mon Jul 21 14:56:46 BST 2014
+[INFO] Final Memory: 66M/554M
+[INFO] ------------------------------------------------------------------------
+
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/tests.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/tests.md b/docs/guide/dev/build/tests.md
new file mode 100644
index 0000000..16f6810
--- /dev/null
+++ b/docs/guide/dev/build/tests.md
@@ -0,0 +1,26 @@
+---
+layout: guide-normal
+title: Tests
+toc: /toc.json
+---
+
+We have the following tests groups:
+
+* normal (i.e. no group) -- should run quickly, not need internet, and not side effect the machine (apart from a few /tmp files)
+* Integration -- deploys locally, may read and write from internet, takes longer.
+ If you change an entity, rerun the relevant integration test to make sure all is well!
+* Live -- deploys remotely, may provision machines (but should clean up, getting rid of them in a try block)
+* Live-sanity -- a sub-set of "Live" that can be run regularly; a trade-off of optimal code coverage for the
+ time/cost of those tests.
+* WIP -- short for "work in progress", this will disable the test from being run by the normal brooklyn maven profiles,
+ while leaving the test enabled so that one can work on it in IDEs or run the selected test(s) from the command line.
+* Acceptance -- this (currently little-used) group is for very long running tests, such as soak tests
+
+To run these from the command line, use something like the following:
+
+* normal: `mvn clean install`
+* integration: `mvn clean verify -PEssentials,Locations,Entities,Integration -Dmaven.test.failure.ignore=true`
+* Live: `mvn clean verify -PEntities,Locations,Entities,Live -Dmaven.test.failure.ignore=true`
+* Live-sanity: `mvn clean verify -PEntities,Locations,Entities,Live-sanity -Dmaven.test.failure.ignore=true`
+
+<!-- TODO describe how to run each of these, as a group, and individually; and profiles -->
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/build/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/build/toc.json b/docs/guide/dev/build/toc.json
new file mode 100644
index 0000000..fca9b70
--- /dev/null
+++ b/docs/guide/dev/build/toc.json
@@ -0,0 +1,8 @@
+[
+{ "title": "Maven",
+ "file": "{{ site.url }}/dev/build/index.html" },
+{ "title": "IDE",
+ "file": "{{ site.url }}/dev/build/ide.html" },
+{ "title": "Tests",
+ "file": "{{ site.url }}/dev/build/tests.html" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/code/entity.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/entity.md b/docs/guide/dev/code/entity.md
new file mode 100644
index 0000000..7001612
--- /dev/null
+++ b/docs/guide/dev/code/entity.md
@@ -0,0 +1,91 @@
+---
+layout: guide-normal
+title: Writing an Entity
+toc: /toc.json
+---
+
+## Ways to write an entity
+
+There are several ways to write a new entity:
+
+* Write pure-java, extending existing base-classes and using utilities such as `HttpTool` and `BashCommands`.
+* Write scripts, and configure (e.g. using YAML) a **`VanillaSoftwareProcess`**.
+* Use Chef recipes, and wire these into the entity by using `ChefConfig` and `ChefLifecycleEffectorTasks`.
+* Use an equivalent of Chef (e.g. Salt or Puppet; support for these is currently less mature than for Chef)
+
+The rest of this section covers writing an entity in pure-java (or other JVM languages).
+
+
+## Things To Know
+
+All entities have an interface and an implementation. The methods on the interface
+are its effectors; the interface also defines its sensors.
+
+Entities are created through the management context (rather than calling the
+constructor directly). This returns a proxy for the entity rather than the real
+instance, which is important in a distributed management plane.
+
+All entity implementations inherit from `AbstractEntity`,
+often through one of the following:
+
+* **`SoftwareProcessImpl`**: if it's a software process
+* **`VanillaJavaAppImpl`**: if it's a plain-old-java app
+* **`JavaWebAppSoftwareProcessImpl`**: if it's a JVM-based web-app
+* **`DynamicClusterImpl`**, **`DynamicGroupImpl`** or **`AbstractGroupImpl`**: if it's a collection of other entities
+
+Software-based processes tend to use *drivers* to install and
+launch the remote processes onto *locations* which support that driver type.
+For example, `AbstractSoftwareProcessSshDriver` is a common driver superclass,
+targetting `SshMachineLocation` (a machine to which Brooklyn can ssh).
+The various `SoftwareProcess` entities above (and some of the exemplars
+listed at the end of this page) have their own dedicated drivers.
+
+Finally, there are a collection of *traits*, such as `Resizable`,
+in the package ``brooklyn.entity.trait``. These provide common
+sensors and effectors on entities, supplied as interfaces.
+Choose one (or more) as appropriate.
+
+
+
+## Key Steps
+
+So to get started:
+
+1. Create your entity interface, extending the appropriate selection from above,
+ to define the effectors and sensors.
+2. Include an annotation like `@ImplementedBy(YourEntityImpl.class)` on your interface,
+ where `YourEntityImpl` will be the class name for your entity implementation.
+3. Create your entity class, implementing your entity interface and extending the
+ classes for your chosen entity super-types. Naming convention is a suffix "Impl"
+ for the entity class, but this is not essential.
+4. Create a driver interface, again extending as appropriate (e.g. `SoftwareProcessDriver`).
+ The naming convention is to have a suffix "Driver".
+5. Create the driver class, implementing your driver interface, and again extending as appropriate.
+ Naming convention is to have a suffix "SshDriver" for an ssh-based implementation.
+ The correct driver implementation is found using this naming convention, or via custom
+ namings provided by the `BasicEntityDriverFactory`.
+6. Wire the `public Class getDriverInterface()` method in the entity implementation, to specify
+ your driver interface.
+7. Provide the implementation of missing lifecycle methods in your driver class (details below)
+8. Connect the sensors from your entity (e.g. overriding `connectSensors()` of `SoftwareProcessImpl`)..
+ See the sensor feeds, such as `HttpFeed` and `JmxFeed`.
+
+Any JVM language can be used to write an entity. However use of pure Java is encouraged for
+entities in core brooklyn.
+
+
+## Helpful References
+
+A few handy pointers will help make it easy to build your own entities.
+Check out some of the exemplar existing entities
+(note, some of the other entities use deprecated utilities and a deprecated class
+hierarchy; it is suggested to avoid these, looking at the ones below instead):
+
+* `JBoss7Server`
+* `MySqlNode`
+
+You might also find the following helpful:
+
+* **[Entity Design Tips]({{site.url}}/dev/tips/index.html#EntityDesign)**
+* The **[User Guide]({{site.url}}/use/guide/index.html)**
+* The **[Mailing List](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)**
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/code/index.include.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.include.md b/docs/guide/dev/code/index.include.md
new file mode 100644
index 0000000..a213cd6
--- /dev/null
+++ b/docs/guide/dev/code/index.include.md
@@ -0,0 +1,99 @@
+## The Basics
+
+Brooklyn is available at [GitHub brooklyncentral/brooklyn](http://github.com/brooklyncentral/brooklyn). Check it out using:
+
+{% highlight bash %}
+git clone git@github.com:brooklyncentral/brooklyn.git
+cd brooklyn
+{% endhighlight %}
+
+Build it with:
+
+{% highlight bash %}
+mvn clean install
+{% endhighlight %}
+
+And launch it with:
+
+{% highlight bash %}
+cd usage/dist/target/brooklyn-dist/
+bin/brooklyn launch
+{% endhighlight %}
+
+Plenty of examples are in the **examples** sub-dir,
+described [here]({{site.url}}/use/examples),
+and pushed to the [brooklyn-examples](http://github.com/brooklyncentral/brooklyn-examples)
+GitHub project when a version is released.
+
+Information on using Brooklyn -- configuring locations (in `brooklyn.properties`)
+and adding new projects to a catalog -- can be found in the [User's Guide]({{site.url}}/use/guide/quickstart/index.html).
+This document is intended to help people become familiar with the codebase.
+
+## Project Structure
+
+Brooklyn is split into the following projects and sub-projects:
+
+* **``camp``**: the components for a server which speaks the CAMP REST API and which understands the CAMP YAML plan language
+* **``api``**: the pure-Java interfaces for interacting with the system
+* **``core``**: the base class implementations for entities and applications, entity traits, locations, policies, sensor and effector support, tasks, and more
+* **``locations``**: specific location integrations
+ * **``jclouds``**: integration with many cloud APIs and providers, via Apache jclouds
+* **``policies``**: collection of useful policies for automating entity activity
+* **``software``**: entities which are mainly launched by launched software processes on machines, and collections thereof
+ * **``base``**: software process lifecycle abstract classes and drivers (e.g. SSH)
+ * **``webapp``**: web servers (JBoss, Tomcat), load-balancers (Nginx), and DNS (Geoscaling)
+ * **``database``**: relational databases (SQL)
+ * **``nosql``**: datastores other than RDBMS/SQL (often better in distributed environments)
+ * **``messaging``**: messaging systems, including Qpid, Apache MQ, RabbitMQ
+ * **``monitoring``**: monitoring tools, including Monit
+ * **``osgi``**: OSGi servers
+ * **...**
+* **``utils``**: projects which lower level utilities
+ * **common**: Utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+ * **groovy**: Groovy extensions and utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+ * **jmx/jmxmp-ssl-agent**: An agent implementation that can be attached to a Java process, to give expose secure JMXMP
+ * **jmx/jmxrmi-agent**: An agent implementation that can be attached to a Java process, to give expose JMX-RMI without requiring all high-number ports to be open
+ * **rest-swagger**: Swagger REST API utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+ * **test-support**: Test utility classes and methods developed for Brooklyn but not dependendent on Brooklyn
+* **``usage``**: projects which make Brooklyn easier to use, either for end-users or Brooklyn developers
+ * **all**: maven project to supply a shaded JAR (containing all dependencies) for convenience
+ * **archetypes**: A maven archetype, for easily generating the structure of a new downstream projects
+ * **camp**: Brooklyn bindings for the CAMP REST API
+ * **cli**: backing implementation for Brooklyn's command line interface
+ * **dist**: builds brooklyn as a downloadable .zip and .tar.gz
+ * **jsgui**: Javascript web-app for the brooklyn management web console (builds a WAR)
+ * **launcher**: for launching brooklyn, either using a main method or invoked from the cli project
+ * **logback-includes**: Various helpful logback XML files that can be included; does not contain logback.xml
+ * **logback-xml**: Contains a logback.xml that references the include files in brooklyn-logback-includes
+ * **rest-api**: The API classes for the Brooklyn REST api
+ * **rest-client**: A client Java implementation for using the Brooklyn REST API
+ * **rest-server**: The server-side implementation of the Brooklyn REST API
+ * **scripts**: various scripts useful for building, updating, etc. (see comments in the scripts)
+ * **qa**: longevity and stress tests
+ * **test-support**: provides Brooklyn-specific support for tests, used by nearly all projects in scope ``test``
+* **``docs``**: the markdown source code for this documentation, as described [here]({{site.url}}/dev/tips/update-docs.html)
+* **``examples``**: some canonical examples, as listed [here]({{site.url}}/use/examples)
+* **``sandbox``**: various projects, entities, and policies which the Brooklyn Project is incubating
+
+
+## Next Steps
+
+If you're interested in building and editing the code, check out:
+
+* [Maven setup](../build/index.html)
+* [IDE setup](../build/ide.html)
+* [Tests](../build/tests.html)
+* [Tips](../tips/index.html)
+* [Remote Debugging](../build/debugging-remote-brooklyn.html)
+
+If you want to start writing your own policies and entities, have a look at:
+
+* [Writing a Brooklyn Entity](entity.html)
+* [Writing a Brooklyn Policy](policy.html)
+* Or see the [User Guide]({{ site.url }}/use/guide/index.html)
+ on [policies]({{ site.url }}/use/guide/policies/index.html)
+ and [entities]({{ site.url }}/use/guide/entities/index.html)
+
+Where things aren't documented **please ask us** at
+[the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)
+so we can remedy this!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/code/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/index.md b/docs/guide/dev/code/index.md
new file mode 100644
index 0000000..ecf9fcf
--- /dev/null
+++ b/docs/guide/dev/code/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Code Structure
+toc: /toc.json
+---
+
+{% readj index.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/code/policy.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/policy.md b/docs/guide/dev/code/policy.md
new file mode 100644
index 0000000..7bbbcad
--- /dev/null
+++ b/docs/guide/dev/code/policy.md
@@ -0,0 +1,47 @@
+---
+layout: guide-normal
+title: Writing a Policy
+toc: /toc.json
+---
+
+Policies perform the active management enabled by Brooklyn.
+Each policy instance is associated with an entity,
+and at runtime it will typically subscribe to sensors on that entity or children,
+performing some computation and optionally actions when a subscribed sensor event occurs.
+This action might be invoking an effector or emitting a new sensor,
+depending the desired behvaiour is.
+
+Writing a policy is straightforward.
+Simply extend ``AbstractPolicy``,
+overriding the ``setEntity`` method to supply any subscriptions desired:
+
+{% highlight java %}
+ @Override
+ public void setEntity(EntityLocal entity) {
+ super.setEntity(entity)
+ subscribe(entity, TARGET_SENSOR, this)
+ }
+{% endhighlight %}
+
+and supply the computation and/or activity desired whenever that event occurs:
+
+{% highlight java %}
+ @Override
+ public void onEvent(SensorEvent<Integer> event) {
+ int val = event.getValue()
+ if (val % 2 == 1)
+ entity.sayYoureOdd();
+ }
+{% endhighlight %}
+
+You'll want to do more complicated things, no doubt,
+like access other entities, perform multiple subscriptions,
+and emit other sensors -- and you can.
+See the source code, and see some commonly used policies
+in ``AutoScalerPolicy`` and ``RollingMeanEnricher``.
+
+One rule of thumb, to close on:
+try to keep policies simple, and compose them together at runtime;
+for instance, if a complex computation triggers an action,
+define one **enricher** policy to aggregate other sensors and emit a new sensor,
+then write a second policy to perform that action.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/code/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/code/toc.json b/docs/guide/dev/code/toc.json
new file mode 100644
index 0000000..d599dbe
--- /dev/null
+++ b/docs/guide/dev/code/toc.json
@@ -0,0 +1,10 @@
+[
+{ "title": "Structure",
+ "file": "{{ site.url }}/dev/code/index.html" },
+{ "title": "Writing an Entity",
+ "file": "{{ site.url }}/dev/code/entity.html" },
+{ "title": "Writing a Policy",
+ "file": "{{ site.url }}/dev/code/policy.html" },
+{ "title": "brooklyn.git (github)",
+ "file": "http://github.com/brooklyncentral/brooklyn" }
+]
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/how-to-contrib.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/how-to-contrib.md b/docs/guide/dev/how-to-contrib.md
new file mode 100644
index 0000000..b5a8306
--- /dev/null
+++ b/docs/guide/dev/how-to-contrib.md
@@ -0,0 +1,38 @@
+---
+layout: guide-normal
+title: How to Contribute
+toc: /toc.json
+---
+
+### The Process
+
+If you've built something which you think others could use, or are interested in doing so --
+whether a new supported entity, or a policy, or an example --
+it's easy to give back to the community. Just:
+
+1. **Tell [the brooklyn mailing list](https://mail-archives.apache.org/mod_mbox/incubator-brooklyn-dev/)** about your work or interest
+
+1. **Create your fork** of the project on GitHub
+
+1. **Clone it** to your local machine and do your work on it
+
+1. **Push it**, and tell everyone about it
+
+1. **Sign the relevant Apache contributor agreement(s)**
+
+1. **Issue a pull request** from your GitHub repo
+
+The same process holds for contributing to this documentation (web site and user guide),
+but see the additional [tips for updating documentation]({{ site.url }}/dev/tips/update-docs.html).
+
+
+### Some Words of Advice
+
+* Do early-stage work in the ``/sandbox``, which means we can pulled it in to ``master`` more often --
+ keeping branches short-lived and making it easier to collaborate!
+
+* Include javadoc and tests
+
+* See the [tips here]({{site.url}}/dev/tips/index.html)
+
+* If you get blocked, **[hollar]({{site.url}}/meta/contact.html)**!
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/index.md b/docs/guide/dev/index.md
new file mode 100644
index 0000000..11377d7
--- /dev/null
+++ b/docs/guide/dev/index.md
@@ -0,0 +1,7 @@
+---
+layout: guide-normal
+title: Getting to Code
+toc: /toc.json
+---
+
+{% readj code/index.include.md %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/links.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/links.md b/docs/guide/dev/links.md
new file mode 100644
index 0000000..4be8f30
--- /dev/null
+++ b/docs/guide/dev/links.md
@@ -0,0 +1,18 @@
+---
+layout: guide-normal
+title: Development Bookmarks
+toc: ../toc.json
+---
+
+
+Handy places:
+
+* **Code** is in Github at [https://github.com/brooklyncentral/brooklyn](https://github.com/brooklyncentral/brooklyn)
+
+* **Issues** are also on Github at [https://github.com/brooklyncentral/brooklyn/issues](https://github.com/brooklyncentral/brooklyn/issues)
+
+* **Maven repositories** are at [http://developers.cloudsoftcorp.com/download/maven2/](http://developers.cloudsoftcorp.com/download/maven2/) for releases
+ and [http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/](http://ccweb.cloudsoftcorp.com/maven/libs-snapshot-local/) for snapshots
+ (under ``io/brooklyn``)
+
+* **CI server** is currently a private server managed by Cloudsoft. There is a proposal to move to CloudBees.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md
new file mode 100644
index 0000000..664a95e
--- /dev/null
+++ b/docs/guide/dev/tips/index.md
@@ -0,0 +1,50 @@
+---
+layout: guide-normal
+title: Miscellaneous Tips and Tricks
+toc: /toc.json
+---
+
+## General Good Ways of Working
+
+* If working on something which could be contributed to Brooklyn,
+ do it in a project under the ``sandbox`` directory.
+ This means we can accept pulls more easily (as sandbox items aren't built as part of the main build)
+ and speed up collaboration.
+
+* When debugging an entity, make sure the [brooklyn.SSH logger](logging.html) is set to DEBUG and accessible.
+
+* Use tests heavily! These are pretty good to run in the IDE (once you've completed [IDE setup]({{site.url}}/dev/build/ide.html)),
+ and far quicker to spot problems than runtime, plus we get early-warning of problems introduced in the future.
+ (In particular, Groovy's laxity with compilation means it is easy to introduce silly errors which good test coverage will find much faster.)
+
+* If you hit inexplicable problems at runtime, try clearing your Maven caches,
+ or the brooklyn-relevant parts, under ``~/.m2/repository``.
+ Also note your IDE might be recompiling at the same time as a Maven command-line build,
+ so consider turning off auto-build.
+
+
+<a name="EntityDesign"></a>
+## Entity Design Tips
+
+* Look at related entities and understand what they've done, in particular which
+ sensors and config keys can be re-used.
+ (Many are inherited from interfaces, where they are declared as constants,
+ e.g. ``Attributes`` and ``UsesJmx``.)
+
+* Understand the location hierarchy: software process entities typically get an ``SshMachineLocation``,
+ and use a ``*SshDriver`` to do what they need. This will usually have a ``MachineProvisioningLocation`` parent, e.g. a
+ ``JcloudsLocation`` (e.g. AWS eu-west-1 with credentials) or possibly a ``LocalhostMachineProvisioningLocation``.
+ Clusters will take such a ``MachineProvisioningLocation`` (or a singleton list); fabircs take a list of locations.
+ Some PaaS systems have their own location model, such as ``OpenShiftLocation``.
+
+Finally, don't be shy about [talking with others]({{site.url}}/meta/contact.html),
+that's far better than spinning your wheels (or worse, having a bad experience),
+plus it means we can hopefully improve things for other people!
+
+
+## Project Maintenance
+
+* Adding a new project may need updates to ``/pom.xml`` ``modules`` section and ``usage/all`` dependencies
+
+* Adding a new example project may need updates to ``/pom.xml`` and ``/examples/pom.xml`` (and the documentation too!)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/local-artifact-repo.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/local-artifact-repo.md b/docs/guide/dev/tips/local-artifact-repo.md
new file mode 100644
index 0000000..a96c62f
--- /dev/null
+++ b/docs/guide/dev/tips/local-artifact-repo.md
@@ -0,0 +1,32 @@
+---
+layout: guide-normal
+title: Prepopulating a Local Artifact Repository
+toc: /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/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/logging.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/logging.md b/docs/guide/dev/tips/logging.md
new file mode 100644
index 0000000..4e6b001
--- /dev/null
+++ b/docs/guide/dev/tips/logging.md
@@ -0,0 +1,144 @@
+---
+layout: guide-normal
+title: Logging
+toc: /toc.json
+---
+
+## Logging: A Quick Overview
+
+For logging, we use **logback** which implements the slf4j API.
+This means you can use any slf4j compliant logging framework,
+with a default configuration which just works out of the box
+and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...)
+if you prefer one of those.
+
+To use:
+
+* **Users**:
+If using a brooklyn binary installation, simply edit the ``logback.xml``
+or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/``
+directory.
+
+* **Developers**:
+When setting up a new project, if you want logging it is recommended to include
+the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency,
+and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``,
+as described below.
+
+
+## Customizing Your Logging
+
+The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration,
+with a mechanism which allows it to be easily customized, consumed, and overridden.
+You may wish to include this as an *optional* dependency so that it is not forced
+upon downstream projects. This ``logback.xml`` file supplied contains just one instruction,
+to include ``logback-main.xml``, and that file in turn includes:
+
+* ``logback-custom.xml``
+* ``brooklyn/logback-appender-file.xml``
+* ``brooklyn/logback-appender-stdout.xml``
+* ``brooklyn/logback-logger-excludes.xml``
+* ``brooklyn/logback-debug.xml``
+
+For the most common customizations, simply create a ``logback-custom.xml`` on your classpath
+(ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom)
+and supply your customizations there:
+
+{% highlight xml %}
+<included>
+ <!-- filename to log to -->
+ <property name="logging.basename" scope="context" value="acme-app" />
+
+ <!-- additional loggers -->
+ <logger name="com.acme.app" level="DEBUG"/>
+</included>
+{% endhighlight %}
+
+For other configuration, you can override individual files listed above.
+For example:
+
+* To remove debug logging, create a trivial ``brooklyn/logback-debug.xml``,
+ containing simply ``<included/>``.
+* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO,
+ create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT.
+* To discard all brooklyn's default logging, create a ``logback-main.xml`` which
+ contains your configuration. This should look like a standard logback
+ configuration file, except it should be wrapped in ``<included>`` XML tags rather
+ than ``<configuration>`` XML tags (because it is included from the ``logback.xml``
+ which comes with ``brooklyn-logback-xml``.)
+* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``.
+ This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything
+ logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else
+ will end up in ``jclouds.log``.
+
+You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``.
+If you do, logback will detect multiple files with that name and will scream at you.
+If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-logback-xml``.
+(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.)
+
+You can set a specific logback config file to use with:
+
+{% highlight bash %}
+-Dlogback.configurationFile=/path/to/config.xml
+{% endhighlight %}
+
+
+## Assemblies
+
+When building an assembly, it is recommended to create a ``conf/logback.xml`` which
+simply includes ``logback-main.xml`` (which comes from the classpath). Users of the assembly
+can then edit the ``logback.xml`` file in the usual way, or they can plug in to the configuration
+mechanisms described above, by creating files such as ``logback-custom.xml`` under ``conf/``.
+
+Including ``brooklyn-logback-xml`` as an *optional* and *provided* dependency means everything
+should work correctly in IDE's but it will not include the extra ``logback.xml`` file in the assembly.
+(Alternatively if you include the ``conf/`` dir in your IDE build, you should exclude this dependency.)
+
+With this mechanism, you can include ``logback-custom.xml`` and/or other files underneath
+``src/main/resources/`` of a project, as described above (for instance to include custom
+logging categories and define the log file name) and it should get picked up,
+both in the IDE and in the assembly.
+
+
+## Tests
+
+Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project
+which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml``
+when available (ie when running tests). However the ``logback-test.xml`` Brooklyn uses
+includes the same ``logback-main.xml`` call path above, so your configurations should still work.
+
+The only differences of the ``logback-test.xml`` configuration is that:
+
+* Debug logging is included for all Brooklyn packages
+* The log file is called ``brooklyn-tests.log``
+
+
+## Caveats
+
+* logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x.
+ If you have dependent projects using 1.5.x (such as older Grails) things may break.
+
+* If you're not getting the logging you expect in the IDE, make sure
+ ``src/main/resources`` is included in the classpath.
+ (In eclipse, right-click the project, the Build Path -> Configure,
+ then make sure all dirs are included (All) and excluded (None) --
+ ``mvn clean install`` should do this for you.)
+
+* You may find that your IDE logs to a file ``brooklyn-tests.log``
+ if it doesn't distinguish between test build classpaths and normal classpaths.
+
+* Logging configuration using file overrides such as this is very sensitive to
+ classpath order. To get a separate `brooklyn-tests.log` file during testing,
+ for example, the `brooklyn-test-support` project with scope `test` must be
+ declared as a dependency *before* `brooklyn-logback-includes`, due to the way
+ both files declare `logback-appender-file.xml`.
+
+* Similarly note that the `logback-custom.xml` file is included *after*
+ logging categories and levels are declared, but before appenders are declared,
+ so that logging levels declared in that file dominate, and that
+ properties from that file apply to appenders.
+
+* Finally remember this is open to improvement. It's the best system we've found
+ so far but we welcome advice. In particular if it could be possible to include
+ files from the classpath with wildcards in alphabetical order, we'd be able
+ to remove some of the quirks listed above (though at a cost of some complexity!).
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/release.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/release.md b/docs/guide/dev/tips/release.md
new file mode 100644
index 0000000..35c5904
--- /dev/null
+++ b/docs/guide/dev/tips/release.md
@@ -0,0 +1,286 @@
+---
+layout: guide-normal
+title: Release Process
+toc: /toc.json
+---
+
+<!--
+TODO
+
+vote required? see governance.
+
+
+ branch-twice-then-reversion-twice
+ e.g. from master=1.0.0_SNAPSHOT we will go to
+ create branch: v1.0.0_SNAPSHOT
+ reversion master: 1.1.0_SNAPSHOT
+ create branch and reversion: v1.0.0_RC1, v1.0.0_SNAPSHOT
+ describe scripts for releasing
+ docs
+
+update version, using scripts
+
+push examples to repo
+
+push docs to branch and publish
+
+-->
+
+Brooklyn is published to two locations:
+
+* Sonatype, for snapshots and for staging releases
+* Maven Central, for full (GA and milestone) releases
+
+Brooklyn artifacts are generally downloaded from:
+
+1. [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.brooklyn%22),
+ and (http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.brooklyn%22) for pre 0.7.0 versions
+2. [Apache](https://repository.apache.org/index.html#nexus-search;quick~org.apache.brooklyn),
+2. [Sonatype](https://oss.sonatype.org/index.html#nexus-search;quick~io.brooklyn) for pre 0.7.0 versions
+3. [GitHub](https://github.com/apache/incubator-brooklyn).
+
+
+To publish:
+
+* a snapshot release:
+ * mvn deploy to Sonatype
+ * (optional) publish versioned docs to brooklyncentral.github.com project
+* a (milestone) release:
+ * same as above, but with some git versioning
+ * deploy to Sonatype, then release to Maven Central
+ * deploy a version branch to brooklyn-examples
+ * deploy (or update) versioned docs
+* a major release:
+ * same as above, and
+ * in addition to versioned examples, update brooklyn-examples master to match the current (stable) release
+ * in addition to versioned docs, publish full (front page) docs to brooklyncentral.github.com project
+ * bump the snapshot version in brooklyn master to the next release
+
+
+
+## Configuration
+
+Your .m2/settings.xml must be configured with the right credentials for Sonatype
+
+ <servers>
+ ...
+ <server>
+ <username> ... </username>
+ <password> ... </password>
+ <id>sonatype-nexus-snapshots</id>
+ </server>
+ <server>
+ <username> ... </username>
+ <password> ... </password>
+ <id>sonatype-nexus-staging</id>
+ </server>
+ ...
+ </servers>
+You must be configured to sign artifacts using PGP.
+
+If this is the first time you have used Sonatype, the [Sonatype - Maven Usage Guide](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide) is required reading.
+
+The code snippets below use the following variables:
+{% highlight bash %}
+
+export BROOKLYN_DIR=/path/to/brooklyncentral-brooklyn
+export EXAMPLES_DIR=/path/to/brooklyncentral-brooklyn-examples
+export SITE_DIR=/path/to/brooklyncentral-brooklyncentral.github.com
+
+export SNAPSHOT_VERSION=0.6.0-SNAPSHOT
+export RELEASE_VERSION=0.6.0-M1
+{% endhighlight %}
+
+
+## Preparing a Snapshot Release
+
+### Deploy to Sonatype
+
+Execute the following:
+{% highlight bash %}
+mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
+{% endhighlight %}
+
+### (Option) Publish snapshot docs.
+
+(Only required if there have been significant changes to docs or java docs.)
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+git checkout master
+
+if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
+
+# Build the docs
+_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
+
+# Wipe any previous edition of the same version, replacing with new build.
+rm -rf $SITE_DIR/v/$SNAPSHOT_VERSION
+mkdir $SITE_DIR/v/$SNAPSHOT_VERSION
+cp -r _site/* $SITE_DIR/v/$SNAPSHOT_VERSION/
+
+# and push, causing GitHub to republish with updated /v/$SNAPSHOT_VERSION/
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated version docs for version $SNAPSHOT_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+
+
+## Preparing a (Milestone) Release
+
+### Prepare a Release Branch
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR
+git checkout -b $RELEASE_VERSION
+usage/scripts/change-version.sh $SNAPSHOT_VERSION $RELEASE_VERSION
+git commit -a -m "Changed version to $RELEASE_VERSION"
+git push -u upstream $RELEASE_VERSION
+
+{% endhighlight %}
+
+### Deploy to Sonatype, and Close the repo.
+
+{% highlight bash %}
+mvn -Dbrooklyn.deployTo=sonatype -DskipTests clean install deploy
+{% endhighlight %}
+
+* Go to [oss.sonatype.org ... #stagingRepositories](https://oss.sonatype.org/index.html#stagingRepositories) (again, need credentials)
+* 'Close' the repo
+* Email the closed repo address to brooklyn-dev list, have people download and confirm it works.
+
+### Update the brooklyn-examples repo's version Branch
+
+{% highlight bash %}
+
+cd $EXAMPLES_DIR
+
+pushd $BROOKLYN_DIR
+git checkout $RELEASE_VERSION
+popd
+
+if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
+git checkout master
+git checkout -b $RELEASE_VERSION
+rm -rf *
+cp -r $BROOKLYN_DIR/examples/* .
+rm -rf target
+git add -A
+git commit -m "branch for $RELEASE_VERSION"
+git push -u origin $RELEASE_VERSION
+
+{% endhighlight %}
+
+
+### Update the Versioned Docs
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+git checkout $RELEASE_VERSION
+
+if [ ! -f $SITE_DIR/index.html ] ; then echo "could not find docs in $SITE_DIR" ; exit 1 ; fi
+
+# Build the docs
+_scripts/build.sh || { echo "failed to build docs" ; exit 1 ; }
+
+# Wipe any previous edition of the same version, replacing with new build.
+rm -rf $SITE_DIR/v/$RELEASE_VERSION
+mkdir $SITE_DIR/v/$RELEASE_VERSION
+cp -r _site/* $SITE_DIR/v/$RELEASE_VERSION/
+
+# and push, causing GitHub to republish with updated /v/$RELEASE_VERSION/
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated version docs for version $RELEASE_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+## Preparing a Full Release
+
+Complete *all* above steps.
+
+### Deploy to Maven Central
+
+* Confirm that the closed Sonatype repo has no errors
+* Return to [Sonatype: Staging Repositories](https://oss.sonatype.org/index.html#stagingRepositories)
+* 'Release' the repo
+
+### Deploy the Examples master branch.
+
+{% highlight bash %}
+
+cd $EXAMPLES_DIR
+
+pushd $BROOKLYN_DIR
+git checkout $RELEASE_VERSION
+popd
+
+if [ ! -d simple-web-cluster ] ; then echo "wrong dir" ; exit 1 ; fi
+git checkout master
+rm -rf *
+cp -r $BROOKLYN_DIR/examples/* .
+rm -rf target
+git add -A
+git commit -m "Updated to $RELEASE_VERSION"
+git push -u origin master
+
+{% endhighlight %}
+
+### Update the brooklyn.io Front Page Version
+
+{% highlight bash %}
+
+cd $BROOKLYN_DIR/docs
+
+pushd $SITE_DIR
+# remove old root files, but not the previous version in /v/
+if [ -f start/index.html ] ; then
+ for x in * ; do if [[ $x != "v" ]] ; then rm -rf $x ; fi ; done
+else
+ echo IN WRONG DIRECTORY $SITE_DIR - export SITE_DIR to continue
+ exit 1
+fi
+popd
+
+# re-build for hosting at / rather than at /v/VERSION/
+_scripts/build.sh --url "" || { echo "failed to build docs" ; exit 1 ; }
+
+# copy to site dir
+cp -r _site/* $SITE_DIR/
+
+# and git push
+pushd $SITE_DIR
+git add -A .
+git commit -m "Updated root docs for version $RELEASE_VERSION"
+git push
+popd
+
+{% endhighlight %}
+
+
+### Announce
+* Email the Dev and Users mailing lists.
+* Tweet from [@brooklyncentral](https://twitter.com/brooklyncentral)
+
+### Update Snapshot Version
+
+{% highlight bash %}
+
+export NEW_SNAPSHOT_VERSION=0.7.0-SNAPSHOT
+
+cd $BROOKLYN_DIR
+git checkout master
+usage/scripts/change-version.sh $SNAPSHOT_VERSION $NEW_SNAPSHOT_VERSION
+git commit -a -m "Changed version to $NEW_SNAPSHOT_VERSION"
+git push -u upstream master
+
+{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/standards.md
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/standards.md b/docs/guide/dev/tips/standards.md
new file mode 100644
index 0000000..259ab20
--- /dev/null
+++ b/docs/guide/dev/tips/standards.md
@@ -0,0 +1,15 @@
+---
+layout: guide-normal
+title: Code Standards
+toc: /toc.json
+---
+
+Without being too restrictive about how you have to code as part of Brooklyn,
+there are some style points that really make life easier when sharing code
+among ourselves:
+
+* Use spaces (not tabs!) with 4 spaces indentation
+* Keep line length <=128
+* Don't reformat code or organize imports unless there's very good
+ reason (this makes history and merges much harder)
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/ba6612ec/docs/guide/dev/tips/toc.json
----------------------------------------------------------------------
diff --git a/docs/guide/dev/tips/toc.json b/docs/guide/dev/tips/toc.json
new file mode 100644
index 0000000..0be0aba
--- /dev/null
+++ b/docs/guide/dev/tips/toc.json
@@ -0,0 +1,14 @@
+[
+{ "title": "Miscellany",
+ "file": "{{ site.url }}/dev/tips/index.html" },
+{ "title": "Logging",
+ "file": "{{ site.url }}/dev/tips/logging.html" },
+{ "title": "Code Standards",
+ "file": "{{ site.url }}/dev/tips/standards.html" },
+{ "title": "Local Artifact Repo",
+ "file": "{{ site.url }}/dev/tips/local-artifact-repo.html" },
+{ "title": "Updating Docs",
+ "file": "{{ site.url }}/dev/tips/update-docs.html" },
+{ "title": "Release Process",
+ "file": "{{ site.url }}/dev/tips/release.html" }
+]