Return-Path: X-Original-To: apmail-brooklyn-commits-archive@minotaur.apache.org Delivered-To: apmail-brooklyn-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 148ED184F2 for ; Mon, 1 Feb 2016 17:51:52 +0000 (UTC) Received: (qmail 30444 invoked by uid 500); 1 Feb 2016 17:45:12 -0000 Delivered-To: apmail-brooklyn-commits-archive@brooklyn.apache.org Received: (qmail 30396 invoked by uid 500); 1 Feb 2016 17:45:12 -0000 Mailing-List: contact commits-help@brooklyn.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@brooklyn.apache.org Delivered-To: mailing list commits@brooklyn.apache.org Received: (qmail 29661 invoked by uid 99); 1 Feb 2016 17:45:11 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 01 Feb 2016 17:45:11 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 52698E03BE; Mon, 1 Feb 2016 17:45:11 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: heneveld@apache.org To: commits@brooklyn.apache.org Date: Mon, 01 Feb 2016 17:45:58 -0000 Message-Id: <54a301a17c624f36a5d118ecfcc8e0d5@git.apache.org> In-Reply-To: <04e7fe8ce5ec4915b32d09a0a4643d83@git.apache.org> References: <04e7fe8ce5ec4915b32d09a0a4643d83@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [50/51] [abbrv] [partial] brooklyn-docs git commit: move subdir from incubator up a level as it is promoted to its own repo (first non-incubator commit!) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-guide-root.yml ---------------------------------------------------------------------- diff --git a/_build/config-guide-root.yml b/_build/config-guide-root.yml new file mode 100644 index 0000000..f45a593 --- /dev/null +++ b/_build/config-guide-root.yml @@ -0,0 +1,2 @@ +path: + guide: "" http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-guide-version.yml ---------------------------------------------------------------------- diff --git a/_build/config-guide-version.yml b/_build/config-guide-version.yml new file mode 100644 index 0000000..9b910a9 --- /dev/null +++ b/_build/config-guide-version.yml @@ -0,0 +1,6 @@ +path: + # BROOKLYN_VERSION_BELOW + guide: /v/0.9.0-SNAPSHOT + # BROOKLYN_VERSION_BELOW + style: /v/0.9.0-SNAPSHOT/style + website: "" http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-production.yml ---------------------------------------------------------------------- diff --git a/_build/config-production.yml b/_build/config-production.yml new file mode 100644 index 0000000..445b7a1 --- /dev/null +++ b/_build/config-production.yml @@ -0,0 +1,6 @@ +# in production we always set the URL and dependencies should come from the remote source + +url: https://brooklyn.apache.org +url_root: https://brooklyn.apache.org + +dependency_mode: remote http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-pygments.yml ---------------------------------------------------------------------- diff --git a/_build/config-pygments.yml b/_build/config-pygments.yml new file mode 100644 index 0000000..29f85d5 --- /dev/null +++ b/_build/config-pygments.yml @@ -0,0 +1,28 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# this uses python pygments engine to render code; +# with recent jekyll (dec 2014) i can't see any difference, +# and the formatting appears to be following pygments rules +# without it, so perhaps the jekyll ruby highlighter is very +# good (identical? i see a pygments gem, even if the docs +# say it is using something called "rouge"); +# included here so it is documented at least. +# NB: you may need `python easy_install pygments` +highlighter: pygments http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-rdiscount.yml ---------------------------------------------------------------------- diff --git a/_build/config-rdiscount.yml b/_build/config-rdiscount.yml new file mode 100644 index 0000000..aa82ee3 --- /dev/null +++ b/_build/config-rdiscount.yml @@ -0,0 +1,28 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# add this file as a config to use "rdiscount" markdown processor +# instead of the default ruby/jekyll one. +# rdiscount is the original, and C-based, so a bit faster +# (but not much, 7s vs 8.5s on my system -alex) +# and slightly more forgiving, e.g. for tags +# on a line directly about a section header +# (ruby markdown seems to want a blank line between the two). +# NB: this requires adding "rdiscount" to your Gemfile, then `cd ~ ; cd -` +markdown: rdiscount http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-style-latest.yml ---------------------------------------------------------------------- diff --git a/_build/config-style-latest.yml b/_build/config-style-latest.yml new file mode 100644 index 0000000..d03b87d --- /dev/null +++ b/_build/config-style-latest.yml @@ -0,0 +1,2 @@ +path: + style: /v/latest/style http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-subpath-brooklyn.yml ---------------------------------------------------------------------- diff --git a/_build/config-subpath-brooklyn.yml b/_build/config-subpath-brooklyn.yml new file mode 100644 index 0000000..ade7e19 --- /dev/null +++ b/_build/config-subpath-brooklyn.yml @@ -0,0 +1,9 @@ +# to test for absolute reference problems, prefix each of the paths and set the baseurl + +path: + style: /brooklyn/style + guide: /brooklyn/v/latest + website: /brooklyn + v: /brooklyn/v + +baseurl: /brooklyn http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/config-website-root.yml ---------------------------------------------------------------------- diff --git a/_build/config-website-root.yml b/_build/config-website-root.yml new file mode 100644 index 0000000..e5e4b07 --- /dev/null +++ b/_build/config-website-root.yml @@ -0,0 +1,3 @@ +path: + website: "" + guide: "/v/latest" http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/help.txt ---------------------------------------------------------------------- diff --git a/_build/help.txt b/_build/help.txt new file mode 100644 index 0000000..e855c10 --- /dev/null +++ b/_build/help.txt @@ -0,0 +1,22 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +See the README.md in the parent directory, +or run: + + _build/build.sh help http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/htmlproof-brooklyn.sh ---------------------------------------------------------------------- diff --git a/_build/htmlproof-brooklyn.sh b/_build/htmlproof-brooklyn.sh new file mode 100755 index 0000000..5fa6b1b --- /dev/null +++ b/_build/htmlproof-brooklyn.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env ruby_executable_hooks + +# supports --disable_external, --ignore-v-refs, --v-only + +require 'html/proofer' + +HTML::Proofer.new("./_site", { + :href_ignore => [ + /https?:\/\/127.*/, + /https?:\/\/github.com\/apache\/incubator-brooklyn\/edit.*/, + ((ARGV.include? "--ignore-v-refs") ? /.*\/v\/.*/ : /ignore/), + ((ARGV.include? "--v-only") ? /\/(|[^v].*|.[^\/].*)/ : /ignore/) + ], + :alt_ignore => [/.*/], + # don't scan javadoc files (too many errors) + # or autogen catalog items (their style files are wrong in some modes; reinstate when cleaner) + :disable_external => (ARGV.include? "--disable_external"), + :file_ignore => [ /.*\/(javadoc|apidoc|learnmore\/catalog)\/.*/ ] + # bug - must do above - see https://github.com/gjtorikian/html-proofer/issues/145 +# :file_ignore => [ /.*\/javadoc\/.*/, /.*\/learnmore\/catalog\/.*/ ] + }).run http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/javadoc-overview.html ---------------------------------------------------------------------- diff --git a/_build/javadoc-overview.html b/_build/javadoc-overview.html new file mode 100644 index 0000000..ef4819a --- /dev/null +++ b/_build/javadoc-overview.html @@ -0,0 +1,22 @@ + + + +Javadoc for Apache Brooklyn 0.9.0-SNAPSHOT + +

+ Apache Brooklyn is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the + Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the + infrastructure, communications, and decision making process have stabilized in a manner consistent with other + successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of + the code, it does indicate that the project has yet to be fully endorsed by the ASF. +

+

+ Apache Brooklyn is distributed under the Apache License v2.0. +

+ +

+ +This is the Javadoc for v 0.9.0-SNAPSHOT (git SHA1 hash ${SHA1STAMP}) auto-generated on ${DATESTAMP}. +

+ + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/list-objects-logback.xml ---------------------------------------------------------------------- diff --git a/_build/list-objects-logback.xml b/_build/list-objects-logback.xml new file mode 100644 index 0000000..4ce07ae --- /dev/null +++ b/_build/list-objects-logback.xml @@ -0,0 +1,42 @@ + + + + + + + + + + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/make-javadoc.sh ---------------------------------------------------------------------- diff --git a/_build/make-javadoc.sh b/_build/make-javadoc.sh new file mode 100755 index 0000000..c7d9a5a --- /dev/null +++ b/_build/make-javadoc.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash + +JAVADOC_TARGET1_SUBPATH=javadoc +JAVADOC_TARGET2_SUBPATH=misc/javadoc + +if [ ! -x make-javadoc.sh ]; then + echo This command must be run from the _build directory, not its parent. + exit 1 +fi + +if [ -z "$BROOKLYN_JAVADOC_SOURCE_PATHS" ]; then + echo detecting source paths for javadoc + export SOURCE_PATHS=`find ../.. -name java | grep "src/main/java$" | grep -v "^../../sandbox" | tr "\\n" ":"` +else + echo using pre-defined source paths $BROOKLYN_JAVADOC_SOURCE_PATHS + export SOURCE_PATHS=$BROOKLYN_JAVADOC_SOURCE_PATHS +fi + +mkdir -p target +rm -rf target/$JAVADOC_TARGET1_SUBPATH/ + +export YEARSTAMP=`date "+%Y"` +export DATESTAMP=`date "+%Y-%m-%d"` +export SHA1STAMP=`git rev-parse HEAD` + +# BROOKLYN_VERSION_BELOW +export BROOKLYN_JAVADOC_CLASSPATH=$( mvn -f ../../pom.xml --projects :brooklyn-all dependency:build-classpath | grep -E -v '^\[[A-Z]+\]' ) + +echo "building javadoc at $DATESTAMP from: +$SOURCE_PATHS" + +javadoc -sourcepath $SOURCE_PATHS \ + -public \ + -d target/$JAVADOC_TARGET1_SUBPATH/ \ + -subpackages "org.apache.brooklyn:io.brooklyn:brooklyn" \ + -classpath "${BROOKLYN_JAVADOC_CLASSPATH}" \ + -doctitle "Apache Brooklyn" \ + -windowtitle "Apache Brooklyn" \ + -notimestamp \ + -overview javadoc-overview.html \ + -header 'Apache Brooklyn
' \ + -footer 'Apache Brooklyn - Multi-Cloud Application Management
brooklyn.io. Apache License. © '$YEARSTAMP'.' \ +2>&1 1>/dev/null | tee target/javadoc.log + +if ((${PIPESTATUS[0]})) ; then echo ; echo ; echo "wARNING: javadoc process exited non-zero" ; echo ; echo ; fi +echo ; echo + +if [ ! -f target/$JAVADOC_TARGET1_SUBPATH/org/apache/brooklyn/api/entity/Entity.html ]; then echo "ERROR: missing expected content. Are the paths right?" ; exit 1 ; fi + +if [ ! -z "`grep warnings target/javadoc.log`" ] ; then echo "WARNINGs occurred during javadoc build. See target/javadoc.log for more information." ; fi + +sed -i.bak s/'${DATESTAMP}'/"${DATESTAMP}"/ target/$JAVADOC_TARGET1_SUBPATH/overview-summary.html +sed -i.bak s/'${SHA1STAMP}'/"${SHA1STAMP}"/ target/$JAVADOC_TARGET1_SUBPATH/overview-summary.html +rm target/$JAVADOC_TARGET1_SUBPATH/*.bak + +if [ -d ../_site/guide/$JAVADOC_TARGET2_SUBPATH/ ] ; then + echo "API directory detected in test structure _site, copying docs there so they can be served with serve-site.sh" + cp -r target/$JAVADOC_TARGET1_SUBPATH/* ../_site/guide/$JAVADOC_TARGET2_SUBPATH/ +fi + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/quick-make-few-javadoc.sh ---------------------------------------------------------------------- diff --git a/_build/quick-make-few-javadoc.sh b/_build/quick-make-few-javadoc.sh new file mode 100755 index 0000000..e78d79b --- /dev/null +++ b/_build/quick-make-few-javadoc.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +export BROOKLYN_JAVADOC_SOURCE_PATHS="../../api/src/main/java" +echo LIMITING build to $BROOKLYN_JAVADOC_SOURCE_PATHS for speed +./make-javadoc.sh + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/serve-public-site.sh ---------------------------------------------------------------------- diff --git a/_build/serve-public-site.sh b/_build/serve-public-site.sh new file mode 100755 index 0000000..70c6470 --- /dev/null +++ b/_build/serve-public-site.sh @@ -0,0 +1 @@ +ruby -run -e httpd ${BROOKLYN_SITE_DIR-../../incubator-brooklyn-site-public} -p 4000 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/serve-site.sh ---------------------------------------------------------------------- diff --git a/_build/serve-site.sh b/_build/serve-site.sh new file mode 100755 index 0000000..69cf70d --- /dev/null +++ b/_build/serve-site.sh @@ -0,0 +1 @@ +ruby -run -e httpd _site/ -p 4000 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball.md ---------------------------------------------------------------------- diff --git a/_build/tests/jsonball/test_jsonball.md b/_build/tests/jsonball/test_jsonball.md new file mode 100644 index 0000000..1dcc572 --- /dev/null +++ b/_build/tests/jsonball/test_jsonball.md @@ -0,0 +1,18 @@ +--- +layout: website-normal +title: Test Jsonball +--- + +{% jsonball j from data { "a": "data" } %} +from data: j.a is {{ j.a }} (should be data) + +{% assign v = '{ "a": "var" }' %} +{% jsonball j from var v %} +from var: j.a is {{ j.a }} (should be var) + +{% jsonball j from file test_jsonball_file.json %} +from file: j.a is {{ j.a }} (should be file) + +{% jsonball j from page test_jsonball_page.json %} +from page: j.a is {{ j.a }} (should be page) + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball_file.json ---------------------------------------------------------------------- diff --git a/_build/tests/jsonball/test_jsonball_file.json b/_build/tests/jsonball/test_jsonball_file.json new file mode 100644 index 0000000..e566a20 --- /dev/null +++ b/_build/tests/jsonball/test_jsonball_file.json @@ -0,0 +1 @@ +{ "a": "file" } http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/test_jsonball_page.json ---------------------------------------------------------------------- diff --git a/_build/tests/jsonball/test_jsonball_page.json b/_build/tests/jsonball/test_jsonball_page.json new file mode 100644 index 0000000..bb08f70 --- /dev/null +++ b/_build/tests/jsonball/test_jsonball_page.json @@ -0,0 +1,2 @@ +{% assign x = "page" %} +{ "a": "{{ x }}" } http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_build/tests/jsonball/toc.json ---------------------------------------------------------------------- diff --git a/_build/tests/jsonball/toc.json b/_build/tests/jsonball/toc.json new file mode 100644 index 0000000..cd01e1a --- /dev/null +++ b/_build/tests/jsonball/toc.json @@ -0,0 +1,6 @@ +[ +{ "title": "Test Jsonball", + "file": "test_jsonball.html" }, +{ "title": "Home", + "file": "{{ site.path.guide }}/index.html" } +] http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_config.yml ---------------------------------------------------------------------- diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..7b634b2 --- /dev/null +++ b/_config.yml @@ -0,0 +1,54 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +encoding: utf-8 +markdown: kramdown + +# where this will publish +url_root: http://0.0.0.0:4000 + +# absolute base directories where things will land on the server +path: + style: /style + guide: /guide + website: /website + v: /v + +# Use local copies of dependencies in dev build (switched to remote using URLs for prod build) +dependency_mode: local +dependency_urls: + bootstrap.css: https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css + bootstrap.js: https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js + jquery.js: https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js + +root_menu_page: /website/index.md + +# These files should not be included in the final build (in addition to _* contents) +exclude: ['/Gemfile*','/README.md'] + +sass: + sass_dir: style/css + +brooklyn-stable-version: 0.8.0-incubating + +brooklyn-version: 0.9.0-SNAPSHOT # BROOKLYN_VERSION +brooklyn-snapshot-git-branch: master # if line above is SNAPSHOT this should point to corresponding git branch (e.g. master, 0.4) + +# This is auto-detected, but you can override it if needed. +# git-branch: master http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/before-begin.include.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/before-begin.include.md b/_extra/big_examples/before-begin.include.md new file mode 100644 index 0000000..5170c64 --- /dev/null +++ b/_extra/big_examples/before-begin.include.md @@ -0,0 +1,56 @@ +{% include fields.md %} + +## Before You Begin + +To use the examples, you'll need ``curl``, ``git``, ``java`` (1.6+), and ``maven`` (v3) installed. + +### Installing Brooklyn + +(If you followed the [Getting Started](/use/guide/quickstart/index.html) instructions, you can skip to Installing the Examples.) + +{% if SNAPSHOT %} + +First, grab a copy of the Brooklyn snapshot distribution you wish to use from +[the maven repository]({{ this_dist_url_list }}) +(or build it yourself following instructions [here]({{ site.path.guide }}/dev/build/)), +unpack it to your favourite location (e.g. `$(pwd)`), +and export `BROOKLYN_HOME`: + +{% highlight bash %} +% curl -L -o brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz "{{ this_dist_url_tgz }}" +% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz +% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/ +{% endhighlight %} + +{% else %} + +Grab a copy of the Brooklyn distribution and set up `BROOKLYN_HOME`: + +{% highlight bash %} +% curl -LO "{{ this_dist_url_tgz }}" +% tar xvzf brooklyn-dist-{{ site.brooklyn-version }}-dist.tar.gz +% export BROOKLYN_HOME=$(pwd)/brooklyn-{{ site.brooklyn-version }}/ +{% endhighlight %} + +{% endif %} + +### Installing the Examples + +Grab a copy of the brooklyn-examples source code and build it with Maven: + +{% highlight bash %} +% git clone https://github.com/apache/incubator-brooklyn.git +% cd incubator-brooklyn/examples +% mvn clean install +{% endhighlight %} + +{% if SNAPSHOT %} +Please note, these instructions are for a SNAPSHOT release of Brooklyn, +so proceed with caution. +For the latest stable version, go [here](/meta/versions.html). +{% endif %} + +For more information on ways to download Brooklyn please +see the [download page]({{site.path.guide}}/start/download.html). +For more information on the Brooklyn CLI and launching apps, +please visit [this section of the user guide]({{site.path.guide}}/use/guide/management/index.html#cli). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png b/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png new file mode 100644 index 0000000..c34217f Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-geoscaling-details-w700.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-geoscaling-details.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/console-geoscaling-details.png b/_extra/big_examples/global-web-fabric/console-geoscaling-details.png new file mode 100644 index 0000000..f47226a Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-geoscaling-details.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-map-w700.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/console-map-w700.png b/_extra/big_examples/global-web-fabric/console-map-w700.png new file mode 100644 index 0000000..af353a9 Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-map-w700.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/console-map.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/console-map.png b/_extra/big_examples/global-web-fabric/console-map.png new file mode 100644 index 0000000..cd0f811 Binary files /dev/null and b/_extra/big_examples/global-web-fabric/console-map.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png b/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png new file mode 100644 index 0000000..33c811d Binary files /dev/null and b/_extra/big_examples/global-web-fabric/geopaas-deployed-app-w700.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png b/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png new file mode 100644 index 0000000..4e743e3 Binary files /dev/null and b/_extra/big_examples/global-web-fabric/geopaas-deployed-app.png differ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/global-web-fabric/index.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/global-web-fabric/index.md b/_extra/big_examples/global-web-fabric/index.md new file mode 100644 index 0000000..a8c373a --- /dev/null +++ b/_extra/big_examples/global-web-fabric/index.md @@ -0,0 +1,378 @@ +--- +layout: website-normal +title: Global Web Fabric +toc: /guide/toc.json +--- + +This example shows how to build a multi-site web application *fabric* +with DNS configured on the front-end to combine the sites, +routing users to the location closest to them. + +It can combine with the [Simple Web Cluster](../webcluster) example +or the [Portable Cloud Foundry](https://github.com/cloudsoft/brooklyn-cloudfoundry) example, +but does not assume knowledge of either of these. + +{% readj ../before-begin.include.md %} + +Now, go to this particular example's directory: + +{% highlight bash %} +% cd global-web-fabric +{% endhighlight %} + +The CLI needs to know where to find your compiled examples. You can set this up by exporting +the ``BROOKLYN_CLASSPATH`` environment variable in the following way: + +{% highlight bash %} +% export BROOKLYN_CLASSPATH=$(pwd)/target/classes +{% endhighlight %} + +The project ``global-web-fabric`` contains the code used +in this example under ``src/main/java``. + + +### Setting Up Geographic DNS + +This example uses [geoscaling.com](http://www.geoscaling.com) to provide **free** geographic-dependent DNS services. +This will forward a domain name of your choice to various IPs depending on a script, +e.g. computing the nearest IP based on latitude and longitude of the requester and the targets. +Brooklyn will automatically generate and update this script, but you do need to +create and configure a Geoscaling account: + + 1. Create the free account [here](https://www.geoscaling.com/dns2/?module=register). + 1. Click the link in the email you receive. + 1. Enter the domain name you wish to use into geoscaling (see below). + +The simplest domain name to choose is something unique under `geopaas.org`, e.g. `yourname.geopaas.org`, +which we have already configured for Geoscaling to manage. +If you are using your own domain name, +set its nameservers as advised by geoscaling (e.g. `ns{1,2,3,4}.geoscaling.com`). + +Next we need to supply this information to Brooklyn at runtime. +The simplest way is to create or add the following fields to `~/.brooklyn/brooklyn.properties`: + +{% highlight bash %} +brooklyn.geoscaling.username=yourname +brooklyn.geoscaling.password=s3cr3t +brooklyn.geoscaling.primaryDomain=yourname.geopaas.org +{% endhighlight %} + +Replace the values of these fields as appropriate, of course! +You can, if you prefer, supply (or override) these values in your Brooklyn application. + + +### Setting Up the Locations Database + +In order to generate the "closest-IP" script, +Brooklyn needs a way to find out the latitude and longitude of the +servers you are using. +The simplest way to do this is do download the free GeoCityLite binary flatfile +from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/#Downloads), +unpack it, and copy it to `~/.brooklyn/GeoLite2-City.mmdb`. + +This will be picked up automatically if it is installed. +You can instead specify to use an online lookup service, such as +[utrace.de](http://www.utrace.de) by specifying +`-Dorg.apache.brooklyn.core.location.geo.HostGeoLookup=UtraceHostGeoLookup`; +but note this has a cap of 100 per day. + +This information is also used to display locations on the map +in the Brooklyn dashboard. +Note however that these free services are not 100% accurate; +they are handy for dev/test but in a production system +you may wish to specify the geographical information manually in your application, +or purchase a commercial locations-database subscription. + + +## The Code + +Now let's start writing our application. +The heavy lifting will be done by off-the-shelf Brooklyn classes: + + * `DynamicFabric` will create the entity specified by `factory` in each location it is given + * `GeoscalingDnsService` monitors children of a specified entity (the `DynamicFabric`) + and adds them as DNS targets for the region they are in + +First, however, let's create the Java class -- call it `GlobalWebFabricExample`. +This will extend the Brooklyn `AbstractApplication`: + +{% highlight java %} +package brooklyn.demo; + +import static com.google.common.base.Preconditions.checkNotNull; +import org.apache.brooklyn.core.entity.AbstractApplication; + +public class GlobalWebFabricExample extends AbstractApplication { + @Override + public void init() { + // TODO create our app! + } +} +{% endhighlight %} + +### The Fabric + +The `DynamicFabric` by default has no knowledge of what it will build, +other than the `factory` it is given to create an entity in each region. +We'll use the class `ElasticJavaWebAppService.Factory` which creates +an elastic Java Web App service, +such as the `ControlledDynamicWebAppCluster` used in the +[Simple Web Cluster](../webcluster) example, if deploying to VMs, +or perhaps a `CloudFoundryJavaWebAppCluster` if deploying to a Cloud Foundry location +(see [brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry)). + +{% highlight java %} + DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class) + .displayName("Web Fabric") + .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory()) + .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)); +{% endhighlight %} + +Here we have specified the WAR to use with `configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH)`. +The war configuration used in the previous example is only available on web-aware entities; +configuration specified with a ConfigKey can be done on any entity, +and is inherited at runtime, so this provides a useful way to specify the WAR to use +even though the web-aware entities are only constructed at runtime. + + +### Stitching the Fabric together with DNS + +To stitch these together seamlessly, another entity will run a policy +which collects the public-facing IP address of each cluster created by the fabric, +as it comes online, by watching for `SERVICE_UP` sensors. +First, however, let's make sure any load-balancer proxies (e.g. nginx) in these clusters +are listening on port 80: + +{% highlight java %} + DynamicFabric webFabric = addChild(EntitySpec.create(DynamicFabric.class) + .displayName("Web Fabric") + .configure(DynamicFabric.FACTORY, new ElasticJavaWebAppService.Factory()) + .configure(ElasticJavaWebAppService.ROOT_WAR, WAR_PATH) + .configure(AbstractController.PROXY_HTTP_PORT, PortRanges.fromInteger(80))); +{% endhighlight %} + +Let's now define the Geoscaling entity which does the stitching. +We need to supply the username, password, and primaryDomainName for Geoscaling; +we'll take this from the `brooklyn.properties` file mentioned above. +We'll also specify a `smartSubdomainName`, to use Geoscaling's facility for +lightweight sub-domains to prevent DNS caching and multiple instances of our application +from confusing us -- e.g. `brooklyn-1234.yourname.geopaas.org`. + +{% highlight java %} + StringConfigMap config = getManagementContext().getConfig(); + + GeoscalingDnsService geoDns = addChild(EntitySpec.create(GeoscalingDnsService.class) + .displayName("GeoScaling DNS") + .configure("username", checkNotNull(config.getFirst("brooklyn.geoscaling.username"), "username")) + .configure("password", checkNotNull(config.getFirst("brooklyn.geoscaling.password"), "password")) + .configure("primaryDomainName", checkNotNull(config.getFirst("brooklyn.geoscaling.primaryDomain"), "primaryDomain")) + .configure("smartSubdomainName", "brooklyn")); +{% endhighlight %} + +Lastly we need to tell this instance what entity it should monitor +for children to include as targets: + +{% highlight java %} + geoDns.setTargetEntityProvider(webFabric); +{% endhighlight %} + + + +### Cloud Foundry and other PaaS Targets + +At this point our core application is ready, and can be deployed to AWS or another VM cloud. +This may take between 15 and 30 minutes to run, +mainly spent downloading software +(unless of course you specify a pre-configured `imageId` which contains the software). + +A quicker alternative is to deploy to a Java Web App platform-as-a-service +such as Cloud Foundry. A major advantage here is that they can provision very quickly, +in a matter of seconds. Code for this can be found in the +[brooklyn-cloudfoundry repo](https://github.com/cloudsoft/brooklyn-cloudfoundry), +along with an example global-web-fabric app. + + +### Imports + +Your imports should look as follows: + +{% highlight java %} +import static com.google.common.base.Preconditions.checkNotNull; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import org.apache.brooklyn.api.entity.EntitySpec; +import org.apache.brooklyn.config.StringConfigMap; +import org.apache.brooklyn.core.entity.AbstractApplication; +import org.apache.brooklyn.core.entity.Attributes; +import org.apache.brooklyn.entity.dns.geoscaling.GeoscalingDnsService; +import org.apache.brooklyn.entity.group.DynamicFabric; +import org.apache.brooklyn.entity.proxy.AbstractController; +import org.apache.brooklyn.entity.webapp.ElasticJavaWebAppService; +import PortRanges; +{% endhighlight %} + + +### Use of main method (optional) + +In this example, we will use the brooklyn CLI launcher. However, it is possible to write your own main method. + +The following static constants are assumed (most of these as in the [Simple Web Cluster](../webcluster) example and others): + + * `WAR_PATH`, pointing to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here) + * `DEFAULT_LOCATIONS`, containing a string spec of the locations to deploy to if none are supplied on the command-line; + for this example `localhost` will frequently not work unless Geoscaling can see it + (i.e. it has a public IP and appropriate firewall settings) + +The code (which can safely be omitted) is as follows: + +{% highlight java %} +import org.apache.brooklyn.launcher.BrooklynLauncher; +import org.apache.brooklyn.util.CommandLineUtil; + +import com.google.common.base.Joiner; +import com.google.common.collect.ImmutableList; +import com.google.common.collect.Lists; + +// class definition, and rest of class goes here... + + public static final Logger log = LoggerFactory.getLogger(GlobalWebFabricExample.class); + + // points to the webapp to deploy (a default supplied as part of the Brooklyn examples is used here) + public static final String WAR_PATH = "classpath://hello-world-webapp.war"; + + // locations to deploy to if none are supplied on the command-line; for this example `localhost` will + // frequently not work unless Geoscaling can see it (i.e. it has a public IP and appropriate firewall settings) + static final List 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 args = Lists.newArrayList(argv); + String port = CommandLineUtil.getCommandLineOption(args, "--port", "8081+"); + String locations = CommandLineUtil.getCommandLineOption(args, "--locations", Joiner.on(",").join(DEFAULT_LOCATIONS)); + + BrooklynLauncher launcher = BrooklynLauncher.newInstance() + .application(EntitySpec.create(StartableApplication.class, GlobalWebFabricExample.class).displayName("Brooklyn Global Web Fabric Example")) + .webconsolePort(port) + .locations(Arrays.asList(locations)) + .start(); + + Entities.dumpInfo(app); + } +{% endhighlight %} + + + +## Running the Example + +Now let's run this example. + +{% highlight bash %} +${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.GlobalWebFabricExample \ +--location jclouds:aws-ec2:eu-west-1,jclouds:aws-ec2:ap-southeast-1,jclouds:aws-ec2:us-west-1 +{% endhighlight %} + +The management web console will start, +followed by the web-app services in the locations specified +creating the VM's as needed. +Let's look at the management web console, on port 8081: + +[![Web Console Map](console-map-w700.png "Web Console Map")](console-map.png) + +This shows the targets (e.g. Ireland (AWS eu-west-1), Singapore (AWS ap-southeast-1), and California (AWS us-west-1)). +This also shows the current status of the application. + +Navigating to the "applications" tab, we can view sensors, invoke effectors, control policies, +and track activity, +for instance if a cluster is slow to start and you want to find out what is going on +(you'll find additional information in the `brooklyn.log` file). +Let's drill down on the Geoscaling DNS entity's sensors: + +[![Web Console Geoscaling Details](console-geoscaling-details-w700.png "Web Console Geoscaling Details")](console-geoscaling-details.png) + +Here we see it has chosen `brooklyn-vOZ7b4BL.martincloudsoft.geopaas.org` as the geo-load-balanced domain name. +(Yours will be under `yourname.geopaas.org`, unless you chose a different domain earlier.) +We can also see the hosts it is forwarding to, one for each cluster, corresponding to the +children of the Web Fabric (propagated from the nginx hostnames, in the case of the ControlledDynamicWebAppCluster instances). + + +### Checking the Web App + +Once Geoscaling reports at least one target, you should be able to access it on the geo-load-balanced domain name: + +[![Our Deployed Application](geopaas-deployed-app-w700.png "Our Deployed Application")](geopaas-deployed-app.png) + +Under the covers you are being routed to one of the clusters that has been deployed -- +whichever one is closest to you. +(Due to DNS caching, at your machine or your ISP, clusters which come online after your first lookup +will not be picked up until TTL expires, typically 10m, although often more if DNS services don't respect TTL.) + + +### Checking DNS Information + +Let's find out exactly where we were routed: + +{% highlight bash %} +% dig brooklyn-csgFCzTm.geopaas.org + +; <<>> DiG 9.4.3-P3 <<>> brooklyn-csgFCzTm.geopaas.org + +;; QUESTION SECTION: +;brooklyn-csgFCzTm.geopaas.org. IN A + +;; ANSWER SECTION: +brooklyn-csgFCzTm.geopaas.org. 120 IN CNAME ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. +ec2-46-137-138-4.eu-west-1.compute.amazonaws.com. 215 IN A 46.137.138.4 +{% endhighlight %} + +This was run from Scotland so it seems a sensible choice. +(Some portions of the output from `dig` have been removed for readability.) + +We can get more information by looking at the TXT records: + +{% highlight bash %} +% dig +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org + +; <<>> DiG 9.4.3-P3 <<>> +trace @ns1.geoscaling.com TXT brooklyn-csgFCzTm.geopaas.org + +... + +geopaas.org. 86400 IN NS ns1.geoscaling.com. +geopaas.org. 86400 IN NS ns2.geoscaling.com. +geopaas.org. 86400 IN NS ns3.geoscaling.com. +geopaas.org. 86400 IN NS ns4.geoscaling.com. +;; Received 133 bytes from 199.249.112.1#53(a2.org.afilias-nst.info) in 45 ms + +brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "Request from [54,-2]-(GB) directed to Ireland (IE)" +brooklyn-csgFCzTm.geopaas.org. 300 IN TXT "GeoScaling config auto-updated by Brooklyn 2012-04-26 12:27:25 UTC" +;; Received 189 bytes from 80.87.128.195#53(ns3.geoscaling.com) in 60 ms +{% endhighlight %} + + +## Next Steps + +This example has shown how to create a multi-region fabric, using the abstractions from +[jclouds](http://jclouds.org) under the covers to make it easy to access different hosting providers +simultaneously, and using higher-level abstractions in Brooklyn to mix PaaS systems with +bare-VM (or even bare-metal, if you specify fixed IPs). + +This is meant as just the beginning however. +Here are some questions to think about and code challenges to give you a steer for what to explore next. + + + 1. The routines used at Geoscaling optimize for latency between the user and the location of the web-cluster. + What other strategies might be used? Cost? Compliance? How would you code these? + + 2. This example ignores data, but you clearly can't do that in the real world. + When big-data is involved, does this introduce other considerations for optimizing geo-location? + + 3. Add a data tier to this system, such as MySQL or Mongo, or even Hadoop. + You might start with a single instance or cluster, + but the real fun starts with a fabric, and defining the synchronization/replication strategies + between the different clusters. + This isn't for the faint-hearted, but whatever you create will certainly be of interest + to people in the Brooklyn community. + Please [let us know]({{ site.path.guide }}/meta/contact.html) what you've built! http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/index.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/index.md b/_extra/big_examples/index.md new file mode 100644 index 0000000..b5789a3 --- /dev/null +++ b/_extra/big_examples/index.md @@ -0,0 +1,18 @@ +--- +layout: website-normal +title: Examples +toc: /guide/toc.json +--- + +We currently have the following examples on the site: + +{% capture ltocs %}{% readj toc.json %}{% endcapture %} +{% jsonball ltoc from var ltocs %} + +{% for x in ltoc %} +* {{ x.title }} +{% endfor %} + +There are examples in the code also, just check out the examples/ project. + +**Have one of your own?** [Add it here!]({{site.path.guide}}/dev/tips/update-docs.html) http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/messaging/index.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/messaging/index.md b/_extra/big_examples/messaging/index.md new file mode 100644 index 0000000..f33cecc --- /dev/null +++ b/_extra/big_examples/messaging/index.md @@ -0,0 +1,181 @@ +--- +layout: website-normal +title: Publish-Subscribe Messagiung +toc: /guide/toc.json +--- + +This example shows how a simple messaging application can be build +in brooklyn, starting with configuring and launching a broker. For +these examples we will use the Apache [Qpid](http://qpid.apache.org/) +Java AMQP message broker and clients using the +[JMS](http://docs.oracle.com/javaee/6/tutorial/doc/bnceh.html) API. + +{% readj ../before-begin.include.md %} + +Now, go to this particular example's directory: + +{% highlight bash %} +% cd simple-messaging-pubsub +{% endhighlight %} + +The CLI needs to know where to find your compiled examples. You can set this up by exporting +the ``BROOKLYN_CLASSPATH`` environment variable in the following way: + +{% highlight bash %} +% export BROOKLYN_CLASSPATH=$(pwd)/target/classes +{% endhighlight %} + +The project ``simple-messaging-pubsub`` includes a deployment +descriptor for our example messaging application and simple _Publish_ +and _Subscribe_ JMS test client scripts. + +## Single Broker + +The first example will include a Qpid broker, which we will customize +to use the Oracle [BDB](http://www.oracle.com/technetwork/products/berkeleydb/overview/index.html) +message store as an example of a typical production setup. We will +also create a queue for use by a pair of test clients. + +The ``QpidBroker`` entity is created like this, which uses the +default configuration, specifying only the AMQP port and creates +no queues or topics: + +{% highlight java %} +public class StandaloneQpidBrokerExample extends AbstractApplication { + @Override + public void init() { + // Configure the Qpid broker entity + QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class) + .configure("amqpPort", 5672)); + } +} +{% endhighlight %} + +To install the custom configuration files and extra libraries for +BDB, we specify some files to copy to the broker installation, using +the ``runtimeFiles`` property. These files should be available in +the classpath of the application when it is running, usually by +copying them to the ``src/main/resources`` directory. For example, +here we copy a custom XML configuration file and a new password +file: + +{% highlight java %} + final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml"; + final String PASSWD_PATH = "classpath://passwd"; + + QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class) + .configure("amqpPort", 5672) + .configure("amqpVersion", AmqpServer.AMQP_0_10) + .configure("runtimeFiles", ImmutableMap.builder() + .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH) + .put(QpidBroker.PASSWD, PASSWD_PATH) + .build())); +{% endhighlight %} + +Finally, we come to the complete configuration of our ``QpidBroker`` +entity using the BDB store. The additional properties here specify +the AMQP version and that a queue named _testQueue_ should be created +on startup. + +{% highlight java %} + final String CUSTOM_CONFIG_PATH = "classpath://custom-config.xml"; + final String PASSWD_PATH = "classpath://passwd"; + final String QPID_BDBSTORE_JAR_PATH = "classpath://qpid-bdbstore-0.14.jar"; + final String BDBSTORE_JAR_PATH = "classpath://je-5.0.34.jar"; + + QpidBroker broker = addChild(EntitySpec.create(QpidBroker.class) + .configure("amqpPort", 5672) + .configure("amqpVersion", AmqpServer.AMQP_0_10) + .configure("runtimeFiles", ImmutableMap.builder() + .put(QpidBroker.CONFIG_XML, CUSTOM_CONFIG_PATH) + .put(QpidBroker.PASSWD, PASSWD_PATH) + .put("lib/opt/qpid-bdbstore-0.14.jar", QPID_BDBSTORE_JAR_PATH) + .put("lib/opt/je-5.0.34.jar", BDBSTORE_JAR_PATH) + .build()) + .configure("queue", "testQueue")); +{% endhighlight %} + + +### Running the Example + +You can run the example as follows: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn -v launch --app brooklyn.demo.StandaloneQpidBrokerExample --location localhost +{% endhighlight %} + +Now, visit the Brooklyn web console on port 8081 (for pre 0.6 releases, +use the credentials admin/password). This allows you to view the Brooklyn +entities and their current state for debugging. + +Note that the installation may take some time, because the default +deployment downloads the software from the official repos. You can +monitor start-up activity for each entity in the ``Activity`` pane +in the management console, and see more detail by tailing the log +file (``tail -f brooklyn.log``). + +After starting up, the demo script should display a summary of all +the Brooklyn managed entities and their attributes. This will show +both the Qpid broker and its child entity, the queue _testQueue_ +which was created at startup. The queue entity has sensors that +monitor the depth of unread messages, which you can check while +running the test client scripts later. + +If the ``-v`` flag is passed to the startup command, all configured +entity and sensor details will be output. This includes the broker URL, +which is used to configure JMS clients to connect to this broker. +This URL can also be viewed as a sensor attribute in the web console, +named _broker.url_. + +This sensor is common to _all_ messaging brokers that Brooklyn +provides, and is usually accessed by applications to allow them to +provide it as a parameter to other entities, as shown in the code +fragment below. + +{% highlight java %} +String url = broker.getAttribute(MessageBroker.BROKER_URL) +{% endhighlight %} + +Using the URL the demo script printed, you can run the test ``Subscribe`` +and then ``Publish`` classes, to send messages using the broker. Simply +run the commands in another window, with the provided URL as the +only argument. Note that the URLs may be different to those printed +below, and that any unquoted ``&`` characters *must* be escaped, +if present. + +{% highlight bash %} +% URL="amqp://guest:guest@/localhost?brokerlist='tcp://localhost:5672'" +% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Subscribe ${URL} +% java -cp "./resources/lib/*:./target/classes" brooklyn.demo.Publish ${URL} +{% endhighlight %} + +In the _Publish_ window you should see a log message every time a +message is sent, like this: + +{% highlight bash %} +2012-05-02 14:04:38,521 INFO Sent message 65 +2012-05-02 14:04:39,522 INFO Sent message 66 +{% endhighlight %} + +Similarly, the _Subscribe_ windows should log on reciept of these +messages, as follows: + +{% highlight bash %} +2012-05-02 14:04:32,522 INFO got message 41 test message 41 +2012-05-02 14:04:33,523 INFO got message 42 test message 42 +{% endhighlight %} + +### Cloud Deployment + +With appropriate setup (as described +[here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) +this can also be deployed to your favourite cloud, let's pretend +it's Amazon Ireland, as follows: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.StandaloneQpidBrokerExample --location aws-ec2:eu-west-1 +{% endhighlight %} + +If you encounter any difficulties, please +[tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best +to help. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/nosql-cassandra/cassandra.include.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/nosql-cassandra/cassandra.include.md b/_extra/big_examples/nosql-cassandra/cassandra.include.md new file mode 100644 index 0000000..a4d1643 --- /dev/null +++ b/_extra/big_examples/nosql-cassandra/cassandra.include.md @@ -0,0 +1,282 @@ + +{% readj ../before-begin.include.md %} + +## Simple Cassandra Cluster + +Go to this particular example's directory: + +{% highlight bash %} +% cd simple-nosql-cluster +{% endhighlight %} + +The CLI needs to know where to find your compiled examples. You can set this up by exporting +the ``BROOKLYN_CLASSPATH`` environment variable in the following way: + +{% highlight bash %} +% export BROOKLYN_CLASSPATH=$(pwd)/target/classes +{% endhighlight %} + +The project ``simple-nosql-cluster`` includes several deployment descriptors +for deploying and managing Cassandra, under ``src/main/java``. + +The simplest of these, ``SimpleCassandraCluster``, will start a Cassandra cluster. The code is: + +{% highlight java %} +public class SimpleCassandraCluster extends AbstractApplication { + public void init() { + addChild(EntitySpec.create(CassandraCluster.class) + .configure(CassandraCluster.INITIAL_SIZE, 1) + .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn")); + } +} +{% endhighlight %} + +To run that example on localhost (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase): + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \ + --location localhost +{% endhighlight %} + +Then visit the Brooklyn console on ``localhost:8081``. +Note that the installation may take some time, because the default deployment downloads the software from +the official repos. You can monitor start-up activity for each entity in the ``Activity`` pane in the management console, +and see more detail by tailing the log file (``tail -f brooklyn.log``). + +This example runs successfully on a local machine because ``INITIAL_SIZE`` is configured to just one node +(a limitation of Cassandra is that every node must be on a different machine/VM). +If you want to run with more than one node in the cluster, you'll need to use a location +that either points to multiple existing machines or to a cloud provider where you can +provision new machines. + +With appropriate setup of credentials (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) +this example can also be deployed to your favourite cloud. Let's pretend it's Amazon US East, as follows: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SimpleCassandraCluster \ + --location aws-ec2:us-east-1 +{% endhighlight %} + +If you want more nodes in your cluster, you can either modify the deployment descriptor (i.e. change the ``INITIAL_SIZE`` value), +or dynamically add more nodes by calling the ``resize`` effector through the web-console. +To do the latter, select cluster entity in the tree on the left, then click on the "effectors" tab, and invoke ``resize`` +with the desired number of nodes. + + +### Testing your Cluster + +An easy way to test your cluster is to use the ``cassandra-stress`` command line tool. +For example, run: + +{% highlight bash %} +# Substitute the id below for your VM +NODE_IDS=ec2-54-221-69-95.compute-1.amazonaws.com +/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \ + --nodes ${NODE_IDS} \ + --replication-factor 1 \ + --progress-interval 1 \ + --num-keys 10000 \ + --operation INSERT +{% endhighlight %} + +This command will fire 10000 inserts at the cluster, via the nodes specified in the comma-separated node list. +If you change ``INSERT`` to ``READ``, it will read each of those 10000 values. + + +## High Availability Cassandra Cluster + +Ready for something more interesting? Try this: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.HighAvailabilityCassandraCluster \ + --location aws-ec2:us-east-1 +{% endhighlight %} + +This launches the class ``HighAvailabilityCassandraCluster``, +which launches a Cassandra cluster configured to replicate across availability zones. + +To give some background for that statement, in +[AWS](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) +(and various other clouds), a region is a +separate geographic area, consisting of multiple isolated locations known as availability zones. +To ensure high availability, the Cassandra cluster and thus the data should be spread across the +availability zones. Cassandra should be configured to ensure there is at least one replica in +each availability zone. In +[Cassandra terminology](http://www.datastax.com/docs/1.1/cluster_architecture/replication) +a region is normally mapped to a "datacenter" and an availability zone to a "rack". + +To be properly highly available, we need some automated policies to restart failed servers +and to replace unhealthy nodes. Brooklyn has these policies available out-of-the-box. +To wire them up, the essential code fragment looks like this: + +{% highlight java %} +public class HighAvailabilityCassandraCluster extends AbstractApplication { + public void init() { + addChild(EntitySpec.create(CassandraCluster.class) + .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn") + .configure(CassandraCluster.INITIAL_SIZE, 1) + .configure(CassandraCluster.ENABLE_AVAILABILITY_ZONES, true) + .configure(CassandraCluster.NUM_AVAILABILITY_ZONES, 3) + .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "GossipingPropertyFileSnitch") + .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class) + .policy(PolicySpec.create(ServiceFailureDetector.class)) + .policy(PolicySpec.create(ServiceRestarter.class) + .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED))) + .policy(PolicySpec.create(ServiceReplacer.class) + .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED))); + } +} +{% endhighlight %} + +This code is doing a lot and deserves some more detailed explanation: + +* The ``MEMBER_SPEC`` describes the configuration of the Cassandra nodes to be created in the cluster. + Assuming you're happy to use all the default thrift port etc, then the only configuration to add is + a couple of policies. +* The ``ServiceFailureDetector`` policy watches the node's sensors, and generates + an ``ENTITY_FAILED`` event if the node goes down. +* The ``ServiceRestarter`` policy responds to this failure-event + by restarting the node. Its default configuration is that: if a node does not come back up, or if it + fails again within three minutes, then it will emit an ``ENTITY_RESTART_FAILED`` event. +* Finally, the ``SERVICE_REPLACER`` policy on the cluster responds to this event by replacing the + entire VM. It sets up a new VM in the same location, and then tears down the faulty node. + +> *Troubleshooting:* + +> *In AWS, some availability zones can be constrained for particular instance sizes (see + [this bug report](https://github.com/brooklyncentral/brooklyn/issues/973) + If you get this error, the workaround is to specify explicitly the availability zones to use. + This requires an additional line of code such as:* + +{% highlight java %} + .configure(AVAILABILITY_ZONE_NAMES, ImmutableList.of("us-east-1b", "us-east-1c", "us-east-1e")) +{% endhighlight %} + +> *However, this prevents the blueprint from being truly portable. We're looking at fixing this issue.* + + +## Wide Area Cassandra Cluster + +For critical enterprise use-cases, you'll want to run your Cassandra cluster across multiple regions, +or better yet across multiple cloud providers. This gives the highest level of availability for +the service. + +Try running: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \ + --location "aws-ec2:us-east-1,aws-ec2:us-west-2" +{% endhighlight %} + +This launches the class ``WideAreaCassandraCluster`` across two AWS regions. + +Cassandra provides some great support for this with the +[EC2MultiRegionSnitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication) +The +[snitch](http://www.datastax.com/docs/1.1/cluster_architecture/replication#snitches) +maps IPs to racks and data centers; it defines how the nodes are grouped together within the overall +network topology. For wide-area deployments, it must also deal with when to use the private IPs +(within a region) and the public IPs (between regions). +You'll need a more generic snitch if you're going to span different cloud providers. +Brooklyn has a custom MultiCloudSnitch that we're looking to contribute back to Cassandra. + +The important piece of code in ``WideAreaCassandraCluster`` is: + +{% highlight java %} +public class WideAreaCassandraCluster extends AbstractApplication { + public void init() { + addChild(EntitySpec.create(CassandraFabric.class) + .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn") + .configure(CassandraCluster.INITIAL_SIZE, 2) // per location + .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch") + .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://org/apache/brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar")); + } +} +{% endhighlight %} + +The code below shows the wide-area example with the high-availability policies from the previous section also configured: + +{% highlight java %} +public class WideAreaCassandraCluster extends AbstractApplication { + public void init() { + addChild(EntitySpec.create(CassandraFabric.class) + .configure(CassandraCluster.CLUSTER_NAME, "Brooklyn") + .configure(CassandraCluster.INITIAL_SIZE, 2) // per location + .configure(CassandraCluster.ENDPOINT_SNITCH_NAME, "brooklyn.entity.nosql.cassandra.customsnitch.MultiCloudSnitch") + .configure(CassandraNode.CUSTOM_SNITCH_JAR_URL, "classpath://org/apache/brooklyn/entity/nosql/cassandra/cassandra-multicloud-snitch.jar") + .configure(CassandraFabric.MEMBER_SPEC, EntitySpec.create(CassandraCluster.class) + .configure(CassandraCluster.MEMBER_SPEC, EntitySpec.create(CassandraNode.class) + .policy(PolicySpec.create(ServiceFailureDetector.class)) + .policy(PolicySpec.create(ServiceRestarter.class) + .configure(ServiceRestarter.FAILURE_SENSOR_TO_MONITOR, ServiceFailureDetector.ENTITY_FAILED))) + .policy(PolicySpec.create(ServiceReplacer.class) + .configure(ServiceReplacer.FAILURE_SENSOR_TO_MONITOR, ServiceRestarter.ENTITY_RESTART_FAILED)))); + } +} +{% endhighlight %} + +To run Cassandra across multiple clouds, try running: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WideAreaCassandraCluster \ + --location "aws-ec2:us-east-1,google-compute-engine,rackspace-cloudservers-uk" +{% endhighlight %} + + +### Testing your Wide-Area Cluster + +You can again use the ``cassandra-stress`` command line tool to test the wide-area cluster. + +Note that the replication strategy (such as +[NetworkTopologyStrategy](http://www.datastax.com/docs/1.0/cluster_architecture/replication#networktopologystrategy) +is specified when creating a +[keyspace](http://www.datastax.com/documentation/cassandra/1.2/webhelp/index.html#cassandra/configuration/configStorage_r.html). +The example below specifies a minimum of 1 replica in each datacenter. + +To do updates against a node in a given availability zone: + +{% highlight bash %} +NODE_IDS= +/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \ + --nodes ${NODE_IDS} \ + --replication-strategy NetworkTopologyStrategy \ + --strategy-properties=us-east-1:1,us-west-2:1 \ + --progress-interval 1 \ + --num-keys 10000 \ + --operation INSERT +{% endhighlight %} + +To check that the same data is available from a different region, target the reads +against an appropriate node: + +{% highlight bash %} +NODE_IDS= +/tmp/brooklyn-aled/installs/CassandraNode/1.2.9/apache-cassandra-1.2.9/tools/bin/cassandra-stress \ + --nodes ${NODE_IDS} \ + --replication-strategy NetworkTopologyStrategy \ + --strategy-properties=us-east-1:1,us-west-2:1 \ + --progress-interval 1 \ + --num-keys 10000 \ + --operation READ +{% endhighlight %} + +To really test this, you may want to simulate the failure of a region first. +You can kill the VMs or ``kill -9`` the processes. But remember that if Brooklyn policies are configured +they will by default restart the processes automatically! You can disable the Brooklyn policies through +the brooklyn web-console (select the entity, go the policies tab, select the policy, and click "disable"). + + +## Putting it all together: CumulusRDF + +If you want to try this with a real example application using the Cassandra cluster, take a look at +[CumulusRDF](https://code.google.com/p/cumulusrdf). There is an example Brooklyn application at: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.CumulusRDFApplication \ + --location "aws-ec2:us-east-1" +{% endhighlight %} + + +## Contact us! + +If you encounter any difficulties or have any comments, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/nosql-cassandra/index.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/nosql-cassandra/index.md b/_extra/big_examples/nosql-cassandra/index.md new file mode 100644 index 0000000..7e7948e --- /dev/null +++ b/_extra/big_examples/nosql-cassandra/index.md @@ -0,0 +1,7 @@ +--- +layout: website-normal +title: Cassandra Clusters +toc: /guide/toc.json +--- + +{% readj cassandra.include.md %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/simple-web-cluster.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/simple-web-cluster.md b/_extra/big_examples/simple-web-cluster.md new file mode 100644 index 0000000..2b08a37 --- /dev/null +++ b/_extra/big_examples/simple-web-cluster.md @@ -0,0 +1,9 @@ +--- +layout: website-normal +title: Elastic Web Cluster +toc: /guide/toc.json +--- + + + +{% readj webcluster/webcluster.include.md %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/toc.json ---------------------------------------------------------------------- diff --git a/_extra/big_examples/toc.json b/_extra/big_examples/toc.json new file mode 100644 index 0000000..4bca3a1 --- /dev/null +++ b/_extra/big_examples/toc.json @@ -0,0 +1,13 @@ +[ +{ "title": "Elastic Web Cluster", + "file": "{{ site.path.guide }}/use/examples/webcluster/index.html" }, +{ "title": "Global Web Fabric", + "file": "{{ site.path.guide }}/use/examples/global-web-fabric/index.html" }, +{ "title": "Whirr Hadoop Cluster", + "file": "{{ site.path.guide }}/use/examples/whirrhadoop/index.html" }, +{ "title": "Publish-Subscribe Messaging", + "file": "{{ site.path.guide }}/use/examples/messaging/index.html" }, +{ "title": "Cassandra Cluster", + "file": "{{ site.path.guide }}/use/examples/nosql-cassandra/index.html" } + +] http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/webcluster.md b/_extra/big_examples/webcluster.md new file mode 100644 index 0000000..2b08a37 --- /dev/null +++ b/_extra/big_examples/webcluster.md @@ -0,0 +1,9 @@ +--- +layout: website-normal +title: Elastic Web Cluster +toc: /guide/toc.json +--- + + + +{% readj webcluster/webcluster.include.md %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster/index.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/webcluster/index.md b/_extra/big_examples/webcluster/index.md new file mode 100644 index 0000000..99c6b36 --- /dev/null +++ b/_extra/big_examples/webcluster/index.md @@ -0,0 +1,7 @@ +--- +layout: website-normal +title: Elastic Web Cluster +toc: /guide/toc.json +--- + +{% readj webcluster.include.md %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/big_examples/webcluster/webcluster.include.md ---------------------------------------------------------------------- diff --git a/_extra/big_examples/webcluster/webcluster.include.md b/_extra/big_examples/webcluster/webcluster.include.md new file mode 100644 index 0000000..e135998 --- /dev/null +++ b/_extra/big_examples/webcluster/webcluster.include.md @@ -0,0 +1,124 @@ + +{% readj ../before-begin.include.md %} + +## Simple Web Server + +Go to this particular example's directory: + +{% highlight bash %} +% cd simple-web-cluster +{% endhighlight %} + +The CLI needs to know where to find your compiled examples. You can set this up by exporting +the ``BROOKLYN_CLASSPATH`` environment variable in the following way: + +{% highlight bash %} +% export BROOKLYN_CLASSPATH=$(pwd)/target/classes +{% endhighlight %} + +The project ``simple-web-cluster`` includes several deployment descriptors +for rolling out a web application, under ``src/main/java``. + + + +The simplest of these, ``SingleWebServerExample``, starts JBoss on a single machine with a "Hello World" war deployed, +with a single line: + +{% highlight java %} +public class SingleWebServerExample extends AbstractApplication { + private static final String WAR_PATH = "classpath://hello-world-webapp.war"; + + @Override + public void init() { + addChild(EntitySpec.create(JBoss7Server.class) + .configure("war", WAR_PATH) + .configure("httpPort", 8080)); + } +} +{% endhighlight %} + +You can run this as follows (on *nix or Mac, assuming `ssh localhost` requires no password or passphrase): + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \ + --location localhost +{% endhighlight %} + + +Then visit the webapp on port 8080, or the Brooklyn console on localhost:8081. +Note that the installation may take some time, because the default deployment downloads the software from +the official repos. You can monitor start-up activity for each entity in the ``Activity`` pane in the management console, +and see more detail by tailing the log file (``tail -f brooklyn.log``). + +With appropriate setup (as described [here]({{ site.path.guide }}/use/guide/management/index.html#startup-config)) +this can also be deployed to your favourite cloud, let's pretend it's Amazon Ireland, as follows: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.SingleWebServerExample \ + --location aws-ec2:eu-west-1 +{% endhighlight %} + + +## Elastic Three-Tier + +Ready for something more interesting? Try this: + +{% highlight bash %} +% ${BROOKLYN_HOME}/bin/brooklyn launch --app brooklyn.demo.WebClusterDatabaseExample \ + --location localhost +{% endhighlight %} + +This launches the class ``WebClusterDatabaseExample`` (also described in the [walkthrough]({{ site.path.guide }}/start/walkthrough/index.html)) +which launches a pool of web-servers -- of size 1 initially, +but manually configurable (if you stop the policy first, in the GUI, then use the ``resize`` effector) -- +with an Nginx load-balancer set up in front of them, and backed by a MySQL database. + +The essential code fragment looks like this: + +{% highlight java %} +public class WebClusterDatabaseExample extends AbstractApplication { + public static final String WAR_PATH = "classpath://hello-world-sql-webapp.war"; + + public static final String DB_SETUP_SQL_URL = "classpath://visitors-creation-script.sql"; + + public static final String DB_TABLE = "visitors"; + public static final String DB_USERNAME = "brooklyn"; + public static final String DB_PASSWORD = "br00k11n"; + + @Override + public void init() { + MySqlNode mysql = addChild(EntitySpec.create(MySqlNode.class) + .configure("creationScriptUrl", DB_SETUP_SQL_URL)); + + ControlledDynamicWebAppCluster web = addChild(EntitySpec.create(ControlledDynamicWebAppCluster.class) + .configure("memberSpec", EntitySpec.create(JBoss7Server.class) + .configure("httpPort", "8080+") + .configure("war", WAR_PATH) + .configure(javaSysProp("brooklyn.example.db.url"), + formatString("jdbc:%s%s?user=%s\\&password=%s", + attributeWhenReady(mysql, MySqlNode.MYSQL_URL), DB_TABLE, DB_USERNAME, DB_PASSWORD)))); + + web.getCluster().addPolicy(AutoScalerPolicy.builder(). + metric(DynamicWebAppCluster.AVERAGE_REQUESTS_PER_SECOND). + sizeRange(1, 5). + metricRange(10, 100). + build()); + } +} +{% endhighlight %} + +You can, of course, try this with your favourite cloud, +tweak the database start script, or drop in your favourite WAR. + + +## A Few Other Things + +The project includes variants of the examples shown here, +including alternative syntax (the `*Alt*` files), +and a web-only cluster (no database) in `WebClusterExample``. + +The webapp that is used is included under ``examples/hello-world-webapp``. + +You may wish to check out the [Global Web Fabric example]({{ site.path.guide }}/use/examples/global-web-fabric/) next. + +If you encounter any difficulties, please [tell us]({{ site.path.guide }}/meta/contact.html) and we'll do our best to help. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/brooklyn-gpg-public-key.asc ---------------------------------------------------------------------- diff --git a/_extra/brooklyn-gpg-public-key.asc b/_extra/brooklyn-gpg-public-key.asc new file mode 100644 index 0000000..3b515a4 --- /dev/null +++ b/_extra/brooklyn-gpg-public-key.asc @@ -0,0 +1,21 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: GnuPG/MacGPG2 v2.0.18 (Darwin) +Comment: GPGTools - http://gpgtools.org + +mQENBFDsSLEBCAC2JxQHeXpL3oGN2IickcG9C49gkxIsws4hpasQModVipezrQi0 +9pLq4lkB01GgC2sfPH+XXE8rCpA9EL0e4wVA7JICz5AsLZAAJH91tKksL20tLMeU +Yrbufaq1ga7ifk3JWhF4iwvkDMBKyCjrF173nI+2TwX2XfNTQpzoQGOL1bNvS4NZ +AD9JeXGW2D996zHdSK+x3wVdY3cDECvVMuw61+5ytZrGNnyvaaWTl3lJUyydPXHQ +5TXVtbQH5WgYCLPr4E95axJ0BoY8H+fEaG1Uax1a+xLumVWhiWNp7rMvmgcZXuJO +fx+wXAIbRNlAHoJcdZ4NCReRxDIBQ+2HsU1zABEBAAG0bUJyb29rbHluIFByb2pl +Y3QgKGJyb29rbHluLmlvKSAoS2V5IHVzZWQgdG8gYXV0aGVudGljYXRlIEJyb29r +bHluIGFydGlmYWN0cykgPGJyb29rbHluLWRldkBncm91cHMuZ29vZ2xlLmNvbT6J +AT8EEwECACkFAlDsSLECGy8FCQeGH4AHCwkIBwMCAQYVCAIJCgsEFgIDAQIeAQIX +gAAKCRANhinnSRLCsOdIB/4tUVShup2NHXJ9acCah8TuEN4GmN9dBiD9YsGW66SR +/ptY0Gn9XExl2wbmQW+7TQg3QUGv8uffwYLtnMwnmCp/WwgE+uSnRmcENxa9GuTu +PLlURKKGK0C9ljTAHwXtPcIYxPNN3BT4VB56ME1DTBRCgEvudaNSANs8/kT88kE2 +eMC7x0Uo3/P38Ob8XSOfR8c6G6nSz6jILcRBXZTPNNK4svyqF5XHIru65d3/0+mr +bpfcDLcUQYms0MpPmO1RCHLZWwJLsPUIxNwGGnKJc8/RNEvQinK+Ap0cf+PGUQSX +PhB6Z81ROFIVToEVZslgSiL+u4Tc7zXDfDQDY4HeLY2t +=w/CG +-----END PGP PUBLIC KEY BLOCK----- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/deploying-yaml.md ---------------------------------------------------------------------- diff --git a/_extra/deploying-yaml.md b/_extra/deploying-yaml.md new file mode 100644 index 0000000..73010dd --- /dev/null +++ b/_extra/deploying-yaml.md @@ -0,0 +1,39 @@ +--- +title: Deploying YAML Blueprints +layout: page +toc: ../guide_toc.json +categories: [use, guide, defining-applications] +--- + +Once you've [written a YAML blueprint](creating-yaml.md), there are several ways to deploy it. +These insructions assume you have [installed]({{ site.url }}/use/guide/quickstart/) Brooklyn. +You can then: + +- Supply the YAML blueprint file on the CLI when launching the server: + +{% highlight bash %} +$ brooklyn launch --app ./blueprint.yaml +{% endhighlight %} + + +Or, assuming you've launched a server already +(usually on [http://127.0.0.1/](http://127.0.0.1/) unless you've +configured security in [`brooklyn.properties`](/use/guide/quickstart/brooklyn.properties)), +you can: + +- Curl it to the Brooklyn REST API: + +{% highlight bash %} +$ curl -T ./blueprint.yaml -X POST http://localhost:8081/v1/applications +{% endhighlight %} + +You may also need a `-H "Content-Type: application/yaml"` depending on type configuration. +(Not usually for this, but often for other calls.) + +- In the web-console, select the "YAML" tab in the "Add Application" wizard: + +[![Web Console](web-console-yaml-700.png "YAML via Web Console")](web-console-yaml.png) + + +- The web-console also has an interactive "REST API" page, + where you can paste the YAML for uploading into the `POST` to `/v1/applications`. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/highlevel1.md ---------------------------------------------------------------------- diff --git a/_extra/highlevel1.md b/_extra/highlevel1.md new file mode 100644 index 0000000..3dfafb4 --- /dev/null +++ b/_extra/highlevel1.md @@ -0,0 +1,50 @@ +## What is Brooklyn? + +**brooklyn** is a library that simplifies application deployment and management. + +For **deployment**, it is designed to tie in with other tools, +giving single-click deploy and adding the concepts of +manageable clusters and fabrics: + +* many common software entities available out-of-the-box +* integrates with [Apache Whirr](http://whirr.apache.org) + to deploy well-known services such as Hadoop and elasticsearch + (or use POBS, plain-old-bash-scripts) +* use PaaS's such as OpenShift, alongside self-built clusters, for maximum flexibility + +Brooklyn makes roll-out an integral part of the DevOps chain, +as code which can be version-controlled and programmatically tested, +and portable across many clouds or fixed IP machines, +using [jclouds](http://jclouds.org) -- +or just hitting ``localhost`` for quick dev/test. + +Brooklyn's main emphasis is post-deployment, **managing** an application once it is live: +management policies are an integral part of the deployment descriptor, +and at runtime policies have access to all aspects of the deployment. +They are aware of the deployment topology (hierarchical) and +locations (machines, PaaSes, and jurisdictions), +as well as scripts, instrumentation, and operational goals and constraints. +This means they're all set, once the application is launched, +to keep the application running optimally, +based on whatever *optimally* means in that context. + +These deployment patterns and management policies are expressed as Java (and Groovy) classes, +open-sourced here and giving you full control over what you want to happen. +More importantly, however, this code can be shared, improved, and extended. + +We're still near the beginning of figuring this out: +[join us to make it better]({{site.path.guide}}/meta/contact.html). + + +## To Get Started + +* See the [developer's walkthrough]({{site.path.guide}}/start/walkthrough/index.html) for a quick tour +* Check out the [examples]({{site.path.guide}}/use/examples/), from a global web fabric with geo-DNS to a movable PaaS target +* Jump in to the [user guide]({{site.path.guide}}/use/guide/) describing the + [concepts]({{site.path.guide}}/use/guide/defining-applications/basic-concepts.html) + and including a [tutorial]({{site.path.guide}}/use/guide/quickstart/) +* Or dive straight in to the code, either [reading]({{site.path.guide}}/dev/code/) about it + or [gitting](http://github.com/apache/incubator-brooklyn/) it + +If you like it, or if you have ideas how it could be better, +[join the discussion]({{site.path.guide}}/meta/contact.html). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/list-of-blueprints.md ---------------------------------------------------------------------- diff --git a/_extra/list-of-blueprints.md b/_extra/list-of-blueprints.md new file mode 100644 index 0000000..95a602c --- /dev/null +++ b/_extra/list-of-blueprints.md @@ -0,0 +1,160 @@ +--- +title: Systems Available Out-of-the-Box +layout: website-normal +toc: ../guide_toc.json +categories: [use, guide] +--- + +brooklyn comes bundled with support for a large number of systems and entities. + +*Some entities are in an early-access state, and documentation is incomplete. Please contact the Brooklyn Project for assistance and clarification.* + + + +Web +--- + +### Clusters and Interfaces + +The class ``ControlledDynamicWebAppCluster`` creates a load-balanced cluster of web servers. +It defaults to Nginx and JBoss 7, but this is configurable with the ``controller`` or ``controllerSpec``, and +the ``memberSpec`` configuration options. + +Most web app server processes, and some clusters and PaaS implementations, +support the interface ``WebAppService`` which defines many sensors including requests per second. +This allows app server metrics to interoperable across implementations in many cases. + + +### JBoss Application Server + +Brooklyn supports JBoss 7 in the calss ``JBoss7Server``, with a wide range of +monitoring. + +JBoss 6 is also supported using the different class ``JBoss6Server``. +(The different implementation is needed due to major differences between 6 and 7, +including switching from JMX to HTTP/JSON as the preferred metrics mechanism.) + + +### Apache Tomcat + +Apache Tomcat is supported in the class ``TomcatServer``. +(Note that this currently uses a legacy Brooklyn class hierarchy, +and could benefit from being ported to the ``JavaSoftwareProcessSshDriver`` implementation.) + + +### Nginx Load Balancer + +Nginx provides clustering support for several web/app servers. + +The install process downloads the sources for both the service and the sticky session module, configures them using GNI +autoconf and compiles them. This requires gcc and autoconf to be installed. The install script also uses the yum package manager (if available) to install openssl-devel which is required to build the service. This will only work on RHEL or CentOS Linux systems, but the install process should proceed on a vanilla system with development tools available. + +On debian/ubuntu to build nginx you can get the required libraries with: +``apt-get install zlib1g-dev libdigest-sha-perl libssl-dev``. +(The entity install script will attempt to do this with sudo, +but that may fail if sudo access is not available.) + + + +Database +-------- + +### MySQL + +MySQL is one of the most popular relational databases. +Brooklyn supports setting up individual MySQL nodes with arbitrary configuration, +which may be used to create multiple nodes using back-up and synchronization processes as desired. +(If certain patterns for configuring multiple nodes become popular, these could be +added as Brooklyn entities.) + + +### Apache Derby + +*This entity is in the sandbox.* + +Brooklyn supports Apache Derby, a pure-Java SQL database. For setting up an instance of a server see ``DerbySetup``. + + + +NoSQL +----- + +*The NoSQL entities may not be complete.* + +### Redis + +Redis is a distributed key-value store, supporting master/slave replication of a store as a clustered cache. This gives +a series of read-only slaves and a single read-write master, which propagates to the slaves with eventual consistency. + + +### MongoDB + + +### Cassandra + + +### CouchBase + + + +Messaging +--------- + +### Qpid + + +Qpid support provides a JMS broker, running over AMQP. This exposes JMS queues and topics as entities as well. +See ``QpidSetup`` for instantiating a broker. + +### ActiveMQ + + +ActiveMQ support provides a JMS broker. This exposes JMS queues and topics as entities as well. See ``ActiveMQSetup`` for +instantiating a broker. + +### RabbitMQ + + + +Downstream Projects +------------------- + +Downstream projects include those below. + +### Apache Whirr + +https://github.com/brooklyncentral/brooklyn-whirr + +Whirr allows running a variety of services on cloud providers and on localhost. This is done by providing a ``recipe`` which describes what services to launch. You can find an example of how Brooklyn integrates with Whirr [here](/use/examples/whirrhadoop/index.html#custom-whirr-recipe). + +### OpenShift + +https://github.com/cloudsoft/brooklyn-openshift + +### CloudFoundry + +https://github.com/cloudsoft/brooklyn-cloudfoundry and https://github.com/cloudsoft/brooklyn-cloudfoundry + +### MPI + +https://github.com/cloudsoft/brooklyn-openmpi + +### Waratek + +https://github.com/cloudsoft/brooklyn-waratek + +### MapR + +https://github.com/cloudsoft/brooklyn-mapr + +### Cloudera CDH + +https://github.com/cloudsoft/brooklyn-cdh + +### Drupal and Wordpress + +https://github.com/cloudsoft/brooklyn-social-apps http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/local-artifact-repo.md ---------------------------------------------------------------------- diff --git a/_extra/local-artifact-repo.md b/_extra/local-artifact-repo.md new file mode 100644 index 0000000..2fd777b --- /dev/null +++ b/_extra/local-artifact-repo.md @@ -0,0 +1,32 @@ +--- +layout: website-normal +title: Prepopulating a Local Artifact Repository +toc: /guide/toc.json +--- + +On occasion it can be useful to have/control/prepopulate a local repository of entity installers [1]. + +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 [2] 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. + +
+ +
    +
  1. 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 [3].
    2. +
  2. downloads.cloudsoftcorp.com/brooklyn/repository
    3. +
  3. This one time, Cloudsoft ran a team hackathon in a castle in the remote Highlands of Scotland. Remote Highlands != reliable big pipe internet.
    4. +
+ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/_extra/simple_java_examples/example_files/tomcat_multi-location.java ---------------------------------------------------------------------- diff --git a/_extra/simple_java_examples/example_files/tomcat_multi-location.java b/_extra/simple_java_examples/example_files/tomcat_multi-location.java new file mode 100644 index 0000000..cb92766 --- /dev/null +++ b/_extra/simple_java_examples/example_files/tomcat_multi-location.java @@ -0,0 +1,15 @@ +// TODO Untested code; see brooklyn-example for better maintained examples! +public class TomcatFabricApp extends AbstractApplication { + @Override + public void init() { + addChild(EntitySpec.create(DynamicFabric.class) + .configure("displayName", "WebFabric") + .configure("displayNamePrefix", "") + .configure("displayNameSuffix", " web cluster") + .configure("memberSpec", EntitySpec.create(ControlledDynamicWebAppCluster.class) + .configure("initialSize", 2) + .configure("memberSpec", : EntitySpec.create(TomcatServer.class) + .configure("httpPort", "8080+") + .configure("war", "/path/to/booking-mvc.war")))); + } +}