You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2016/02/01 18:45:25 UTC
[17/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/brooklyn-docs/website/learnmore/blueprint-tour.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/blueprint-tour.md b/brooklyn-docs/website/learnmore/blueprint-tour.md
deleted file mode 100644
index 0a7795b..0000000
--- a/brooklyn-docs/website/learnmore/blueprint-tour.md
+++ /dev/null
@@ -1,191 +0,0 @@
----
-layout: website-normal
-title: A Quick Tour of a Brooklyn Blueprint
-title_in_menu: Blueprint Tour
----
-
-<div class="jumobotron annotated_blueprint" markdown="1">
- <div class="code_scroller">
- <div class="initial_notice"><div><div>
- Hover over an element to learn more
- <div class="ann_light">This message will go away in <span id="countdown">3s</span></div>
- <div class="ann_play fa fa-play-circle-o"></div>
- </div></div></div>
- <div class="code_viewer">
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Describe your application
- </div>
- <div class="long"><p>
- Start by giving it a name,
- optionally adding a version and other metadata.
- The format is YAML -- a human-friendly extension to JSON --
- following the
- <a href="{{ site.path.website }}/learnmore/theory.html#standards">CAMP</a> standard.
- </p><p>
- Treat it like source code: use comments, version control it, test it with CI.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div><span class="ann_highlight"># java chatroom with ruby chatbot and couchbase backend (example)</span>
-name: Chatroom with Chatbot
-services:</div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Compose blueprints
- </div>
- <div class="long"><p>
- Choose your building blocks from a large curated catalog,
- and compose them together to form new blueprints
- you can deploy and share.
- </p><p>
- Customize with config keys, such as the initial size
- and, for Couchbase, the data buckets required.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div><span class="ann_highlight">- type: couchbase-cluster</span>
- initialSize: 3
- createBuckets: [{ bucket: chatroom }]
- id: chat-couchbase</div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Run scripts and recipes
- </div>
- <div class="long"><p>
- Use bash, with variables supplied by Brooklyn;
- or Chef recipes, with attributes passed from config;
- or package managers, dockerfiles, etc.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div>- type: bash-server
- launch.command: |
-<span class="ann_highlight"> wget http://example.com/couchbase-chat/chat-bot/{server.rb,Gemfile,install_ruby_and_libs.sh}
- bash install_ruby_and_libs.sh
- ruby ./server.rb $COUCHBASE_URL</span></div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Inject dependencies
- </div>
- <div class="long"><p>
- Connect entities with each other using
- <i>sensors</i> published at runtime to give
- just-in-time resolution for
- shell variables, template expansion, REST calls,
- and any other "happens-before" or "on-change" behaviour.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div> shell.env:
- COUCHBASE_URL:
-<span class="ann_highlight"> $brooklyn:entity("chat-couchbase").
- attributeWhenReady("couchbase.cluster.connection.url")</span></div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Configure locations
- </div>
- <div class="long"><p>
- Give generic VM properties or specific images and flavors.
- Networking topologies and geographic constraints are also supported.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div> provisioning.properties:
-<span class="ann_highlight"> osFamily: ubuntu
- minRam: 4gb</span>
-</div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Extend using Java
- </div>
- <div class="long"><p>
- Create new entities, policies, and "effector" operations
- using Java or JVM bridges to many languages, workflow systems,
- or PaaSes.
- </p><p>
- Add new blueprints to the catalog, dynamically,
- with versions and libraries handled
- under the covers automatically with OSGi.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div>- type: <span class="ann_highlight">org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster:1.1.0</span>
- war: http://example.com/couchbase-chat/chatroom.war
- java.sysprops:
- chat.db.url: $brooklyn:entity("chat-couchbase").attributeWhenReady("couchbase.cluster.connection.url")</div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Attach management logic
- </div>
- <div class="long"><p>
- Set up policies which subscribe to real-time metric sensors
- to scale, throttle, failover, or follow-the-{sun,moon,action,etc}.
- Cloud should be something that <i>applications</i> consume, not people!
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div> brooklyn.policies:
- - type: <span class="ann_highlight">autoscaler</span>
- brooklyn.config:
- metric: $brooklyn:sensor("webapp.reqs.perSec.windowed.perNode")
- metricLowerBound: 400
- metricUpperBound: 600</div></div>
-
-<div class="block">
- <div class="annotations_wrapper1"><div class="annotations_wrapper2"><div class="annotations">
- <div class="short">
- Run across many locations
- </div>
- <div class="long"><p>
- Blueprints are designed for portability.
- Pick from dozens of clouds in hundreds of datacenters.
- Or machines with fixed IP addresses, localhost,
- Docker on <a href="http://clocker.io">Clocker</a>, etc.
- </p><p>
- And you're not limited to servers:
- services, PaaS, even networks can be locations.
- </p></div>
- </div><div class="connector"><div> </div></div></div></div>
-<div>location:
- <span class="ann_highlight">jclouds:aws-ec2</span>:
- region: us-east-1
- identity: <i>AKA_YOUR_ACCESS_KEY_ID</i>
- credential: <i>[access-key-hex-digits]</i></div></div>
-
- </div></div>
-</div>
-
-<script language="JavaScript" type="application/javascript">
-
-{% comment %}
-I've done all I could manage with pure CSS. Just one thing, the bg color
-on hover doesn't apply full width to the row if it extends the code_scroller.
-Fix it with JS.
-
-Also resize the warning to be full size, and after first hover get rid of it.
-{% endcomment %}
-
-$(function() {
- maxCodeWidth = Math.max.apply(Math, $(".annotated_blueprint div.block > div:last-child").map(function(){ return this.scrollWidth; }).get());
- $(".annotated_blueprint div.block").width(maxCodeWidth);
-})
-
-$(".annotated_blueprint .code_scroller .initial_notice > div").height($(".annotated_blueprint .code_scroller .code_viewer").height());
-$(".annotated_blueprint .code_scroller .initial_notice > div").width($(".annotated_blueprint .code_scroller").width());
-$(".annotated_blueprint .code_scroller").hover(function() {
- $(".annotated_blueprint .initial_notice").css("display", "none");
-});
-$(function() {
- setTimeout(function() { $(".annotated_blueprint .initial_notice").hide(400); }, 3000);
- setTimeout(function() { $(".annotated_blueprint #countdown").text("2s"); }, 1000);
- setTimeout(function() { $(".annotated_blueprint #countdown").text("1s"); }, 2000);
-});
-</script>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/catalog/catalog-item.html
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/catalog/catalog-item.html b/brooklyn-docs/website/learnmore/catalog/catalog-item.html
deleted file mode 100644
index abff4c4..0000000
--- a/brooklyn-docs/website/learnmore/catalog/catalog-item.html
+++ /dev/null
@@ -1,138 +0,0 @@
----
-title: Catalog
----
-<!--
-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.
--->
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-<head>
- <title>Brooklyn Entity - Brooklyn Node</title>
- <meta name="fragment" content="!">
-
- {% include base-head.html %}
- <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
- <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
- <link rel="stylesheet" href="{{site.path.style}}/css/catalog_items.css" type="text/css" media="screen"/>
-</head>
-<body>
-{% include topmenu.html %}
-<div id="container">
- <div id="header">
- <div id="identity">
- <a href="http://brooklyncentral.github.com/" rel="home">Brooklyn</a>
- </div>
- </div>
-
- <div id="summary"></div>
-
- <ul class="nav nav-tabs">
- <li class="active"><a href="#configKeys" data-toggle="tab">Config Keys</a></li>
- <li id="sensorsTab"><a href="#sensors" data-toggle="tab">Sensors</a></li>
- <li id="effectorsTab"><a href="#effectors" data-toggle="tab">Effectors</a></li>
- </ul>
-
- <div class="tab-content">
- <div class="tab-pane active" id="configKeys"></div>
- <div class="tab-pane" id="sensors"></div>
- <div class="tab-pane" id="effectors"></div>
- </div>
-</div>
-
-<script src="{{site.path.style}}/js/underscore-min.js" type="text/javascript"></script>
-<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js" type="text/javascript"></script>
-<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
-<script src="{{site.path.style}}/js/catalog/common.js" type="text/javascript"></script>
-<script src="{{site.path.style}}/js/catalog/items.js" type="text/javascript"></script>
-
-<script type="text/javascript">
- $(document).ready(function () {
- $(window).on('hashchange', updateItem);
-
- updateItem(items);
-
- function updateItem(items) {
- var args, catalog_type;
- args = getArgs();
- if(args.length!=2) {
- alert('bad entity format')
- return;
- }
-
- // e.g. entities/org.apache.brooklyn.entity.brooklynnode.BrooklynNode
- if (!brooklyn) return;
- var item = brooklyn.findItemOfType(items[args[0]], args[1]);
-
- $("#summary").html(brooklyn.typeSummary(item));
- if(args[0] == 'entities') {
- catalog_type = 'Entity';
- } else if(args[0] == 'policies') {
- catalog_type = 'Policy';
- } else if(args[0] == 'locations') {
- catalog_type = 'Location'
- }
-
- document.title = 'Brooklyn ' + catalog_type + ' - ' + item.name;
-
- item.config.forEach(function (element) { $("#configKeys").append(brooklyn.configKeyCard(element)); });
-
- if(args[0] == 'entities') {
- $("#sensorsTab").show();
- $("#effectorsTab").show();
-
- item.sensors.forEach(function (element) { $("#sensors").append(brooklyn.sensorCard(element)); });
- if (item.effectors != undefined) {
- item.effectors.forEach(function (element) { $("#effectors").append(brooklyn.effectorCard(element)); });
- }
-
- } else {
- $("#sensorsTab").hide();
- $("#effectorsTab").hide();
- }
- }
-
- function getArgs() {
- var args;
- var params = window.location.hash;
- if(params) {
- if(params.length <= 2) {
- alert('No such catalog item');
- }
- args = params.substring(2).split('/');
- } else {
- params = getParameterByName('_escaped_fragment_');
- args = params.split('/');
- }
-
- return args;
-
- function getParameterByName(name) {
- var search = window.location.search || document.location.search;
- if(search === undefined) {
- alert('No get parameter specified for a catalog item')
- }
-
- name = name.replace(/[\[]/, "\\[").replace(/[\]]/, "\\]");
- var regex = new RegExp("[\\?&]" + name + "=([^&#]*)"),
- results = regex.exec(search);
- return results === null ? "" : decodeURIComponent(results[1].replace(/\+/g, " "));
- }
- }
- });
-</script>
-</body>
-</html>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/catalog/index.html
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/catalog/index.html b/brooklyn-docs/website/learnmore/catalog/index.html
deleted file mode 100644
index 10257c0..0000000
--- a/brooklyn-docs/website/learnmore/catalog/index.html
+++ /dev/null
@@ -1,161 +0,0 @@
----
-layout: base
-title: Catalog
----
-<!--
-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.
--->
-<head>
-
- {% include base-head.html %}
- <script type="text/javascript" src="{{site.path.style}}/js/catalog/items.js"></script>
- <link rel="stylesheet" href="{{site.path.style}}/css/catalog_items.css" type="text/css" media="screen"/>
-</head>
-
-
-<body>
-
-{% include topmenu.html %}
-
-
-
-<div id="container">
- <div id="header">
- <div id="identity">
- <a href="https://brooklyn.apache.org/" rel="home">Brooklyn</a>
- </div>
- </div>
-
- <ul class="nav nav-tabs">
- <li class="active"><a href="#entities" data-toggle="tab">Entities</a></li>
- <li><a href="#policies" data-toggle="tab">Policies</a></li>
- <li><a href="#locations" data-toggle="tab">Locations</a></li>
- </ul>
-
- <div class="tab-content">
- <div class="tab-pane active" id="entities">
- <input class="filter form-control" type="text" placeholder="Filter by type, e.g. webapp or nosql">
- </div>
- <div class="tab-pane" id="policies">
- <input class="filter form-control" type="text" placeholder="Filter by type, e.g. ha">
- </div>
- <div class="tab-pane" id="enrichers">
- <!-- TODO, and above -->
- <input class="filter form-control" type="text" placeholder="Filter by type, e.g. http">
- </div>
- <div class="tab-pane" id="locations">
- <input class="filter form-control" type="text" placeholder="Filter by type, e.g. http">
- </div>
- <div class="tab-pane" id="locationResolvers"></div>
- </div>
-</div>
-
-<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js" type="text/javascript"></script>
-<script src="{{site.path.style}}/js/underscore-min.js" type="text/javascript"></script>
-<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
-<script src="{{site.path.style}}/js/catalog/bloodhound.js" type="text/javascript"></script>
-<script src="{{site.path.style}}/js/catalog/common.js" type="text/javascript"></script>
-<script type="text/javascript">
-
- var filter = function (element, items) {
- var ESCAPE_KEY = 27;
-
- var $element = $(element),
- $tab = $element.parent(),
- kind = $tab.attr("id"),
- collection = items[kind];
- if (!collection) {
- console.warn("Unable to determine type for input", element);
- return;
- }
-
- // Number.MAX_VALUE configures Bloodhound to return all matches.
- var bloodhound = new Bloodhound({
- name: kind,
- local: collection,
- limit: Number.MAX_VALUE,
- datumTokenizer: function (d) {
- return Bloodhound.tokenizers.nonword(d.type);
- },
- queryTokenizer: Bloodhound.tokenizers.nonword
- });
- bloodhound.initialize();
-
- // Filter items as input changes
- var allAnchors = $tab.find("a").map(function (index, a) { return $(a); });
- var hideAnchorsNotMatchingQuery = function () {
- var query = $element.val();
- query = query.trim();
- if (!query) {
- $tab.find("a").removeClass("hide");
- } else {
- var matchedTypes = {};
- bloodhound.get(query, function (suggestions) {
- _.each(suggestions, function (s) {
- // approximate a set!
- matchedTypes[s.type] = true;
- });
- });
- _.each(allAnchors, function (a) {
- if (_.has(matchedTypes, a.data("type"))) {
- a.removeClass("hide");
- } else {
- a.addClass("hide");
- }
- });
- }
- };
- $element.on("input", hideAnchorsNotMatchingQuery);
- // In case page is loaded with text in input, e.g. from back button.
- hideAnchorsNotMatchingQuery();
-
- $element.on("keydown", function (e) {
- if (e.keyCode == ESCAPE_KEY) {
- $element.val("");
- hideAnchorsNotMatchingQuery();
- }
- });
- };
-
- $(document).ready(function () {
- updateItems(items);
-
- function updateItems(items) {
- if (!String.prototype.trim) {
- String.prototype.trim = function () {
- return this.replace(/^\s+|\s+$/g, '');
- };
- }
- var card = function (collection, cardFunction, target) {
- var cards = _.map(collection, cardFunction);
- $(target).append(cards.join(""));
- };
-
- card(items.entities, brooklyn.entityCard, "#entities");
- card(items.policies, brooklyn.policyCard, "#policies");
- //card(items.enrichers, brooklyn.enricherCard, "#enrichers");
- card(items.locations, brooklyn.locationCard, "#locations");
-
- //transformItemAndAddToElement(items.locations, brooklyn.locationCard, "#locations");
- //items.locationResolvers.forEach(function (element) { $("#locationResolvers").append("<tr><td>" + element + "</td></tr>"); });
- $("input.filter").each(function (index, element) {
- filter(element, items);
- });
- }
- });
-</script>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/blueprint-compose.png
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/blueprint-compose.png b/brooklyn-docs/website/learnmore/features/blueprint-compose.png
deleted file mode 100644
index b446c66..0000000
Binary files a/brooklyn-docs/website/learnmore/features/blueprint-compose.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/blueprint-machine-specs.png
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/blueprint-machine-specs.png b/brooklyn-docs/website/learnmore/features/blueprint-machine-specs.png
deleted file mode 100644
index 140f056..0000000
Binary files a/brooklyn-docs/website/learnmore/features/blueprint-machine-specs.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/blueprinting.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/blueprinting.md b/brooklyn-docs/website/learnmore/features/blueprinting.md
deleted file mode 100644
index c79d98b..0000000
--- a/brooklyn-docs/website/learnmore/features/blueprinting.md
+++ /dev/null
@@ -1,24 +0,0 @@
-
-### Blueprinting
-
-
-{% include feature-item.html title="Composable blueprints" %}
-
-A YAML service spec can refer to other blueprints,
-either in the catalog or by URL,
-and can supply custom configuration.
-
-{% include feature-image.html src="blueprint-compose.png" %}
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="Portable machines specs -- or location-specific identifiers" img="blueprint-machine-specs.png" %}
-
-<p>
-Define machine specs using portable constraints,
-or, when you need to, use specific <code>imageId</code>, hardware profiles, and more
-</p>
-
-{% include feature-item-end.html img="blueprint-machine-specs.png" %}
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/index.md b/brooklyn-docs/website/learnmore/features/index.md
deleted file mode 100644
index fff6864..0000000
--- a/brooklyn-docs/website/learnmore/features/index.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-layout: website-normal
-title: Features
-children:
-- { section: Blueprinting }
-- { section: Policy-based Management }
-- { section: Operations }
-- { section: Java }
----
-
-<div class="feature-list">
-
-{% readj blueprinting.md %}
-{% readj policy-based-mgmt.md %}
-{% readj operations.md %}
-{% readj java.md %}
-
-</div>
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/java-hierarchy.png
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/java-hierarchy.png b/brooklyn-docs/website/learnmore/features/java-hierarchy.png
deleted file mode 100644
index b2bd40b..0000000
Binary files a/brooklyn-docs/website/learnmore/features/java-hierarchy.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/java.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/java.md b/brooklyn-docs/website/learnmore/features/java.md
deleted file mode 100644
index 6b31865..0000000
--- a/brooklyn-docs/website/learnmore/features/java.md
+++ /dev/null
@@ -1,41 +0,0 @@
-
-
-### Java
-
-
-{% include feature-item.html title="Discoverable configuration" %}
-
-Config keys, sensors, and effectors can be defined on the classes
-such that they are automatically discoverable at runtime.
-Type information, parameters, documentation, and default values
-are returned through the REST API and shown in the GUI.
-
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="Type hierarchy" %}
-
-Use interfaces and mix-ins to share and inherit behavior in a strongly typed way.
-
-{% include feature-item-end.html img="java-hierarchy.png" %}
-
-
-
-{% include feature-item.html title="Sensor feeds" %}
-
-Fluent builder-style API's are included for collecting sensor information
-from REST endpoints, SSH commands, JMX connectors, and more.
-
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="Task libraries" %}
-
-Fluent builder-style task libraries are included for building activity
-chains which run in parallel or sequentially,
-executing SSH, REST, or arbitrary Java commands.
-Task status, result, hierarchies, and errors are exposed through the REST API and in the GUI.
-
-{% include feature-item-end.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/operations.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/operations.md b/brooklyn-docs/website/learnmore/features/operations.md
deleted file mode 100644
index 0f152ee..0000000
--- a/brooklyn-docs/website/learnmore/features/operations.md
+++ /dev/null
@@ -1,75 +0,0 @@
-
-### Operations
-
-
-{% include feature-item.html title="Brooklyn console" %}
-
-Brooklyn runs with a GUI console giving easy access to the
-management hierarchy, sensors, and activities.
-
-{% include feature-item-end.html img="ops-console.png" %}
-
-
-
-
-
-{% include feature-item.html title="High availability" %}
-
-Run standby nodes which can optionally automatically promote to master
-in the event of master failure. Hot standby nodes can provide additional
-read-only access to entity information.
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="State persistence" %}
-
-Blueprint, catalog, topology and sensor information can be
-automatically persisted to any file system or object store to
-stop Brooklyn and restart resuming where you left off.
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="REST API" %}
-
-<p>
-The console is pure JS-REST, and all the data shown in the GUI
-is available through a straightforward REST/JSON API.
-</p>
-
-<p>
-In many cases, the REST API is simply the GUI endpoint without the
-leading <code>#</code>. For instance the data for
-<code>#/v1/applications/</code> is available at <code>/v1/applications/</code>.
-And in all cases, Swagger doc is available in the product.
-</p>
-{% include feature-item-end.html img="ops-rest.png" %}
-
-
-
-{% include feature-item.html title="Groovy console" %}
-
-With the right permissions, Groovy scripts can be sent via
-the GUI or via REST, allowing open-heart surgery on your systems.
-(Use with care!)
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="Versioning" %}
-
-Blueprints in the catalog can be versioned on-the-fly.
-Running entities are attached to the version against which
-they were launched to preserve integrity, until manual
-version updates are performed.
-{% include feature-item-end.html %}
-
-
-{% include feature-item.html title="Deep task information" %}
-The console shows task flows in real-time,
-including the `stdin` and `stdout` for shell commands,
-making it simpler to debug those pesky failures.
-{% include feature-item-end.html %}
-
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/ops-console.png
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/ops-console.png b/brooklyn-docs/website/learnmore/features/ops-console.png
deleted file mode 100644
index 60a07b9..0000000
Binary files a/brooklyn-docs/website/learnmore/features/ops-console.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/ops-rest.png
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/ops-rest.png b/brooklyn-docs/website/learnmore/features/ops-rest.png
deleted file mode 100644
index c251b5f..0000000
Binary files a/brooklyn-docs/website/learnmore/features/ops-rest.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/features/policy-based-mgmt.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/features/policy-based-mgmt.md b/brooklyn-docs/website/learnmore/features/policy-based-mgmt.md
deleted file mode 100644
index 5483e84..0000000
--- a/brooklyn-docs/website/learnmore/features/policy-based-mgmt.md
+++ /dev/null
@@ -1,28 +0,0 @@
-### Policy-Based Management
-
-
-{% include feature-item.html title="Live metrics" %}
-
-Collect live metrics for use in policies,
-either from metric stores or directly using REST, JMX, SSH, and more.
-
-{% include feature-item-end.html %}
-
-
-
-{% include feature-item.html title="Management policies" %}
-<p>
-Choose from built-in policies including auto-scaling, failover, and follow-the-sun,
-or create new policies to perform custom runtime management.
-</p>
-
-<p>
-Use config keys to customize the policies to suit your systems, right in the YAML blueprint.
-</p>
-{% include feature-item-end.html %}
-
-
-{% include feature-item.html title="Dynamic reconfiguration" %}
-Reconfigure policies, suspend them, or add new ones on-the-fly
-through the REST API.
-{% include feature-item-end.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/index.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/index.md b/brooklyn-docs/website/learnmore/index.md
deleted file mode 100644
index e3b84a4..0000000
--- a/brooklyn-docs/website/learnmore/index.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-layout: website-normal
-title: Learn More
-children:
-- blueprint-tour.md
-- features/
-- { path: theory.md, title_in_menu: Theory }
-- { path: catalog/, title_in_menu: Browse Catalog }
----
-
-<!--
-TODO have a list of resources here? or start w yaml explained?
-
-Got a minute? blueprint-tour
-Got two minutes? watch the video
-Four minutes? read the features list
- cf http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2FwhatsNew%2Fplatform_whatsnew.html -- though maybe with smaller screenshots at left and bigger text for summary!)
-More time?
- Browse the catalog of Supported software, clouds, and policies
- Read on the Theory behing brooklyn
- Read the Brooklyn News
- infoq - http://www.infoq.com/news/2014/06/clocker
- Adam Davis: The case for application-driven cloud computing (Gluecon keynote) http://www.cloudsoftcorp.com/blog/2014/06/adam-davis-case-application-driven-cloud-computing/
- [showing video at min 14]
- twitter feed
- selected blog posts
--->
-
-{% include list-children.html %}
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/learnmore/theory.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/learnmore/theory.md b/brooklyn-docs/website/learnmore/theory.md
deleted file mode 100644
index eddb2f8..0000000
--- a/brooklyn-docs/website/learnmore/theory.md
+++ /dev/null
@@ -1,184 +0,0 @@
----
-layout: website-normal
-title: The Theory behind Brooklyn
-children:
-- { section: "Why Brooklyn?" }
-- { section: Blueprints }
-- { section: Benefits }
-- { section: Standards }
----
-
-<div class="jumobotron" markdown="1">
-
-Brooklyn is a framework for modeling, monitoring, and managing applications
-through autonomic blueprints.
-
-</div>
-
-## Why Brooklyn?
-
-Building and deploying applications in the cloud computing era has changed many
-things. Provision a bare server just-in-time, and use automated tools to install
-an application. Use APIs to add the server to a load balancer. When load goes
-up, provision another server; when load drops, kill a server to save money.
-
-Many new tools have appeared that take advantage of this new era. However each
-of them only solve part of the problem and don't consider the big picture. For
-example, configuration management tools such as Chef can, in a single command,
-provision a new cloud server then install and configure an application -- but
-they require extra programming to reconfigure an load balancer whenever the pool
-of web servers changes. Amazon Auto Scaling can provision new servers and update
-load balancers, but it is dependent on CloudWatch -- this means either using
-proxy metrics such as average response time, or writing more code to expose an
-application's real metrics. A dedicated monitoring tool may be able to easily
-monitor the key metrics with little effort, but its alerts will need to be
-integrated it into the server provisioning process.
-
-So all the tools are there to to create and manage a cloud-scale application
-that can adapt to demand to meet user expectations without wasting money on
-superfluous services - but you will need several such tools and it is up to you
-to integrate them into your deployment plan. Some of these tools -- such as the
-Amazon Web Services web of EC2, CloudWatch, AutoScaling and CloudFormation --
-mean that you may suffer from lock-in. Related projects in OpenStack (Heat,
-Ceilometer, Murano, Solum, etc) provide similar functionality but again for a
-restricted target. The most common policies (such as minimising request latency)
-may be easy, but less common policies such as follow-the-sun and follow-the-moon
-may be up to you to implement. Your scaling policies may understand that
-"high demand = add another server", but may not understand requirements such as
-some clustered services requiring an odd number of instances to prevent voting
-deadlocks.
-
-
-## How Brooklyn Can Help
-
-In this context the advantage of Brooklyn becomes apparent: a single tool is
-able to manage provisioning and application deployment, monitor an application's
-health and metrics, understand the dependencies between components (such as
-knowing that adding a new web server means that the load balancer needs
-reconfiguration) and apply complex policies to manage the application. The tool
-provides a REST API and a GUI, and allows the autonomic blueprints to be treated
-as an integral part of the application. With Brooklyn, these policies become
-modular components which can be reused and easily added to blueprints.
-
-Brooklyn is about deploying and managing applications: composing a full stack
-for an application; deploying to cloud and non-cloud targets; using monitoring
-tools to collect key health/performance metrics; responding to situations
-such as a failing node; and adding or removing capacity to match demand.
-
-
-## Blueprints
-
-A Brooklyn blueprint defines an application, using a declarative YAML syntax
-supporting JVM plugins. A basic blueprint might comprise a single process,
-such as a web-application server running a WAR file or a SQL database and
-its associated DDL scripts. More complex blueprints encompass combinations
-of processes across multiple machines and services, such as a load-balancing
-HTTP server or SDN controller fronting a cluster of J2EE application
-servers, in turn connected to a resilient cluster of SQL database servers.
-Even larger clustered application running in multiple regions can be
-described, with features such as message buses with resilient brokers,
-cacheing tiers of NoSQL key-value store servers, a high-availability
-database cluster and multiple application components connected across these
-layers.
-
-One main benefit of these blueprints is that they are composable:
-best-practice blueprints for one process or pattern (e.g. a Cassandra
-cluster) can be incorporated in other blueprints (e.g. an application with a
-Cassandra cluster as one component). Another major benefit is that the
-blueprints can be treated as source code as part of an applications
-codebase: tested, tracked, versioned, and hardened as an integral part of
-the devops process. In some ways, Brooklyn is to run-time what Maven is to
-build-time.
-
-
-### Blueprints Turn into Deployments
-
-Brooklyn knows about Chef, Salt, and similar tools, and APT and Yum and
-plain old shell scripts, for deploying application components. Blueprints
-are built from a mixture of both off-the-shelf packages such as Tomcat,
-MySQL, Cassandra, and many more from our library; and components that are
-bespoke to individual applications; together with policies that allow the
-application to be self-managing.
-
-Brooklyn is built for the cloud, and will take a blueprint and deploy it to
-one of many supported clouds or even to multiple different clouds, or to
-private infrastructure (bring-your-own-node), or to other platforms. It will
-dynamically configure and connect all the different components of an
-application, e.g. so load balancers know where the web servers are and the
-web applications know where the database is.
-
-Brooklyn collects key metrics to monitor the health of applications; for
-example, by sending a request and measuring latency, or installing
-monitoring tools and using those to read a server's management interface to
-determine the request queue length. These metrics can be fed into policies,
-which automatically take actions such as restarting a failed node, or
-scaling out the web tier if user demand exceeds capacity. This allows an
-application to be self-managing: to recover itself from simple failures, to
-scale out when demand increases and meet capacity; then scale in as demand
-drops and stop paying for spare capacity.
-
-In short, Brooklyn blueprints allow the best practices for deploying and
-managing complex software to be codified as part of the software development
-process.
-
-
-
-### <a id="benefits"></a> Agile and Flexible
-
-Brooklyn is a product built from the ground up for application agility. This
-includes portability across non-cloud, cloud, and PaaS targets; devops-style
-infrastructure-as-code applied to applications; and real-time autonomic
-management based on promise theory. Some introductions to these concepts,
-associated tools, and open specifications may be useful.
-
-Cloud computing at its core is about provisioning resources on-demand. The most
-widely known aspect is IaaS (infrastructure-as-a-service) such as Amazon EC2,
-Softlayer, Google Cloud Platform, Apache CloudStack, or OpenStack. By leveraging
-the Apache jclouds project (and contributing heavily to it), the Brooklyn
-project is able to work with a large number of such providers. Higher up the
-stack, however, there is an increasingly diverse set of platform targets, from
-PaaS (platform-as-a-service) such as Cloud Foundry and Apache Stratos, through
-to myriad containers and runtime fabrics such as LXC/Docker, Apache Mesos,
-Apache Karaf, Apache Hadoop, and Apache Usergrid and other backend-as-a-service
-environments. Brooklyn is based on the premise that applications may need to run
-in any or all of these, and the model must be flexible and open enough to
-support this.
-
-The buzzword-compliant trends of agile and devops have reinforced many important
-lessons:
-
-- The truth is in the code (not any ancillary documents)
-- If it isn't tested then assume it isn't working
-- Toolchain integration and APIs are key to a project's success
-- Even more critical is empowering all stakeholders to a project
-- Brooklyn's focus on blueprinting and modeling as code and APIs serves these
-principles.
-
-### Autonomic Computing
-
-Another major influence on the design of Brooklyn are the ideas of autonomic
-computing and promise theory. It is not necessary to have a thorough
-understanding of these to use Brooklyn, but contributors tend to become versed
-in these ideas quickly. Essentially, autonomics is based on the concept of
-components looking after themselves where possible (self-healing,
-self-optimizing, etc), and exposing a sensor (data outputs) and effector
-(operations) API where they may need to controlled by another element. Promise
-theory extends this approach by introducing the idea that communicating intent
-(through promises) is a more reliable basis for complex cooperating systems than
-obligation-based effectors. Tools such as CF Engine, Chef, Puppet, Ansible, and
-Salt apply promise theory to files and processes on machines; Brooklyn can
-leverage all of these tools, complementing it with an application-oriented
-model.
-
-### Standards
-
-Finally we note some emerging standards in this area. OASIS CAMP
-(<a href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=camp#technical">Cloud Application Management for Platforms</a>)
-and TOSCA
-(<a href="https://www.oasis-open.org/committees/tosca/">Topology and Orchestration Specification for Cloud Applications</a>)
-both define YAML application models similar to Brooklyn's.
-CAMP focuses on the REST API for interacting with such a
-management layer, and TOSCA focuses on declarative support for more
-sophisticated orchestration. Currently Brooklyn uses a YAML which complies with
-CAMP's syntax and exposes many of the CAMP REST API endpoints. We would like to
-support the hot-off-the-press TOSCA YAML and expand the CAMP REST API coverage.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/meta/license.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/meta/license.md b/brooklyn-docs/website/meta/license.md
deleted file mode 100644
index c7f5366..0000000
--- a/brooklyn-docs/website/meta/license.md
+++ /dev/null
@@ -1,205 +0,0 @@
----
-layout: website-normal
-title: Legal
----
-
-## License
-
-Apache Brooklyn is released to the public as open source under the
-terms of the [Apache License, v2.0](http://www.apache.org/licenses/LICENSE-2.0), a full copy of
-which is included below for reference.
-
-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.
-
-Apache Brooklyn is currently undergoing Incubation at the Apache Software Foundation.
-
-
-## Trademark
-
-The Brooklyn name and logo are trademarks owned by the Apache Software Foundation.
-
-
-## Apache License, v2.0 (reference copy)
-
-
-{% highlight text %}
-
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
- 1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
- 2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
- 3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
- 4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
- 5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
- 6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
- 7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
- 8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
- 9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-{% endhighlight %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/meta/sitemap.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/meta/sitemap.md b/brooklyn-docs/website/meta/sitemap.md
deleted file mode 100644
index 7411976..0000000
--- a/brooklyn-docs/website/meta/sitemap.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-layout: website-normal
-title: Site Map
----
-
-<div class="sitemap">
-
-<div class="search_right">
-<form method="get" id="simple_google" class="searchform" action="http://www.google.com/search">
- <input type="text" class="searchinput" name="brooklyn-search" placeholder="Google site search: type & hit enter">
- <input type="hidden" name="q" value="">
- </form>
-</div>
-
-{% assign visited = "" | split: "|" %}
-{% assign site_items = "" | split: "|" %}
-<ul>
-{% for item in site.data.menu %}
- {% push site_items item %}
- {% include sitemap-item.html %}
-{% endfor %}
-</ul>
-
-</div>
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/brooklyn-docs/website/meta/versions.md
----------------------------------------------------------------------
diff --git a/brooklyn-docs/website/meta/versions.md b/brooklyn-docs/website/meta/versions.md
deleted file mode 100644
index 4e704f4..0000000
--- a/brooklyn-docs/website/meta/versions.md
+++ /dev/null
@@ -1,98 +0,0 @@
----
-layout: website-normal
-title: Versions
----
-
-## Current Version: {{ site.brooklyn-stable-version }}
-
-The current stable version of Brooklyn is {{ site.brooklyn-stable-version }}:
-
-* [Download]({{ site.path.website }}/download/)
-* [User Guide]({{ site.path.guide }}/)
-* [Release Notes]({{ site.path.guide }}/misc/release-notes.html)
-
-This documentation was generated {{ site.time | date_to_string }}.
-
-
-## Version History
-
-Apache Brooklyn has made the following releases:
-
-* **[0.8.0-incubating](/v/0.8.0-incubating/)**: Package rename to org.apache.brooklyn.*, and many other improvements. Apache-endorsed binary release! (September 2015)
-
-* **[0.7.0-incubating](/v/0.7.0-incubating/)**: New policies, more clouds, improved Windows support and many other improvements. Apache-endorsed binary release! (July 2015)
-
-* **[0.7.0-M2-incubating](/v/0.7.0-M2-incubating/)**: YAML, persistence, Chef, Windows, Docker. The first Apache release! (December 2014)
-
-Note: These "Version History" links are to permanent versions in the archive,
-different to the "Current Version" links.
-To prevent accidentally referring to out-of-date information,
-a banner is displayed when accessing content from these.
-If you wish you can
-<a href="javascript:void(0);" onclick="set_user_versions_all();">disable all warnings</a> or
-<a href="javascript:void(0);" onclick="clear_user_versions();">re-enable all warnings</a>.
-
-
-## Snapshot Versions
-
-Current work on Apache Brooklyn is done with SNAPSHOT version labels,
-in the `master` branch or in a branch with the version label.
-This code has not been voted on and are not endorsed by The Apache Software Foundation.
-Documentation for these versions are uploaded from time to time,
-and are provided here for reference:
-
-* **[0.9.0-SNAPSHOT](/v/0.9.0-SNAPSHOT/)**: latest unreleased version
-(although docs may not be up-to-date with the latest code)
-
-* **[0.8.0-SNAPSHOT](/v/0.8.0-SNAPSHOT/)**: any changes since 0.8.0-incubating which would go into 0.8.1
-(mainly things from 0.9.0-SNAPSHOT which warranted being backported)
-
-* **[0.7.0-SNAPSHOT](/v/0.7.0-SNAPSHOT/)**: any changes since 0.7.0-incubating which would go into 0.7.1
-(mainly things from 0.8.0-SNAPSHOT which warranted being backported)
-
-
-## Ancient Versions
-
-The versions below were made prior to joining The Apache Software Foundation, therefore **they are not endorsed by
-Apache** and are not hosted by Apache or their mirrors. You can obtain the source code by
-[inspecting the branches of the pre-Apache GitHub repository](https://github.com/brooklyncentral/brooklyn/branches/stale)
-and binary releases by
-[querying Maven Central for io.brooklyn:brooklyn.dist](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22io.brooklyn%22%20AND%20a%3A%22brooklyn-dist%22).
-
-* **[0.7.0-M1](/v/0.7.0-M1/)**: YAML, Chef, catalog, persistence (Apr 2014)
-
-* **[0.6.0](/v/0.6.0/)**: use of spec objects, chef and windows support, more clouds (Nov 2013)
-
-* **[0.5.0](/v/0.5.0/)**: includes new JS GUI and REST API, rebind/persistence support, cleaner model and naming conventions, more entities (May 2013)
-
-* **[0.4.0](/v/0.4.0/)**: initial public GA release of Brooklyn to Maven Central, supporting wide range of entities and examples (Jan 2013)
-
-
-### Versioning
-
-Brooklyn follows [semantic versioning](http://semver.org/) with a leading `0.` qualifier:
-
- 0.<major>.<minor>[.<patch>]-<qualifier>
-
-Breaking backward compatibility increments the `<major>` version.
-New additions without breaking backward compatibility ups the `<minor>` version.
-Bug fixes and misc changes bumps the `<patch>` version.
-New major and minor releases zero the less significant counters.
-
-From time to time, the Brooklyn project will make snapshots, milestone releases, and other qualified versions available,
-using the following conventions:
-
-* Milestone versions (`-M<n>`) have been voted on and have been through some QA,
- but have not had the extensive testing as is done on a release.
-
-* Snapshot (`-SNAPSHOT`) is the bleeding edge.
- With good test coverage these builds are usually healthy,
- but they have not been through QA or voted on.
-
-* Nightly builds (`-N<date>`) represent a snapshot which has
- been given a permanent version number, typically for use by other projects.
- The same caveats as for snapshot releases apply (no QA or Apache vote).
-
-* Release Candidate builds (`-RC<n>`) are made in the run-up to a release;
- these should not normally be used except for deciding whether to cut a release.
-
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/favicon.ico
----------------------------------------------------------------------
diff --git a/favicon.ico b/favicon.ico
new file mode 100644
index 0000000..bdf37d2
Binary files /dev/null and b/favicon.ico differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/application-parent-membership.md
----------------------------------------------------------------------
diff --git a/guide/concepts/application-parent-membership.md b/guide/concepts/application-parent-membership.md
new file mode 100644
index 0000000..c2d0ac3
--- /dev/null
+++ b/guide/concepts/application-parent-membership.md
@@ -0,0 +1,25 @@
+---
+title: Application, Parent and Membership
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+All entities have a ***parent*** entity, which creates and manages it, with one important exception: *applications*.
+Application entities are the top-level entities created and managed externally, manually or programmatically.
+
+Applications are typically defined in Brooklyn as an ***application descriptor***.
+This is a Java class specifying the entities which make up the application,
+by extending the class ``AbstractApplication``, and specifying how these entities should be configured and managed.
+
+All entities, including applications, can be the parent of other entities.
+This means that the "child" is typically started, configured, and managed by the parent.
+For example, an application may be the parent of a web cluster; that cluster in turn is the parent of web server processes.
+In the management console, this is represented hierarchically in a tree view.
+
+A parallel concept is that of ***membership***: in addition to one fixed parent,
+and entity may be a ***member*** of any number of special entities called ***groups***.
+Membership of a group can be used for whatever purpose is required;
+for example, it can be used to manage a collection of entities together for one purpose
+(e.g. wide-area load-balancing between locations) even though they may have been
+created by different parents (e.g. a multi-tier stack within a location).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png
----------------------------------------------------------------------
diff --git a/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png b/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png
new file mode 100644
index 0000000..c2b48ba
Binary files /dev/null and b/guide/concepts/brooklyn-flow-websequencediagrams.com-w400.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/brooklyn-flow-websequencediagrams.com.png
----------------------------------------------------------------------
diff --git a/guide/concepts/brooklyn-flow-websequencediagrams.com.png b/guide/concepts/brooklyn-flow-websequencediagrams.com.png
new file mode 100644
index 0000000..78eb5c8
Binary files /dev/null and b/guide/concepts/brooklyn-flow-websequencediagrams.com.png differ
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/configuration-sensor-effectors.md
----------------------------------------------------------------------
diff --git a/guide/concepts/configuration-sensor-effectors.md b/guide/concepts/configuration-sensor-effectors.md
new file mode 100644
index 0000000..6363b8a
--- /dev/null
+++ b/guide/concepts/configuration-sensor-effectors.md
@@ -0,0 +1,40 @@
+---
+title: Configuration, Sensors and Effectors
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+### Configuration
+
+All entities contain a map of config information. This can contain arbitrary values, typically keyed under static ``ConfigKey`` fields on the ``Entity`` sub-class. These values are inherited, so setting a configuration value at the
+application level will make it available in all entities underneath unless it is overridden.
+
+Configuration is propagated when an application "goes live" (i.e. it becomes "managed", either explicitly or when its ``start()`` method is invoked), so config values must be set before this occurs.
+
+Configuration values can be specified in a configuration file (``~/.brooklyn/brooklyn.properties``)
+to apply universally, and/or programmatically to a specific entity and its descendants
+by calling `.configure(KEY, VALUE)` in the entity spec when creating it.
+There is also an ``entity.config().set(KEY, VALUE)`` method.
+
+Additionally, many common configuration parameters are available as "flags" which can be supplied as Strings when constructing
+then entity, in the form
+``EntitySpec.create˙(MyEntity.class).configure("config1", "value1").configure("config2", "value2")``.
+
+Documentation of the flags available for individual entities can normally be found in the javadocs.
+The ``@SetFromFlag`` annotations on ``ConfigKey`` static field definitions
+in the entity's interface is the recommended mechanism for exposing configuration options.
+
+
+### Sensors and Effectors
+
+***Sensors*** (activity information and notifications) and ***effectors*** (operations that can be invoked on the entity) are defined by entities as static fields on the ``Entity`` subclass.
+
+Sensors can be updated by the entity or associated tasks, and sensors from an entity can be subscribed to by its parent or other entities to track changes in an entity's activity.
+
+Effectors can be invoked by an entity's parent remotely, and the invoker is able to track the execution of that effector. Effectors can be invoked by other entities, but use this functionality with care to prevent too many managers!
+
+An entity consists of a Java interface (used when interacting with the entity) and a Java class. For resilience. it is recommended to store
+the entity's state in attributes (see ``getAttribute(AttributeKey)``). If internal fields can be used then the data will be lost on brooklyn
+restart, and may cause problems if the entity is to be moved to a different brooklyn management node.
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/dependent-configuration.md
----------------------------------------------------------------------
diff --git a/guide/concepts/dependent-configuration.md b/guide/concepts/dependent-configuration.md
new file mode 100644
index 0000000..1d08e1a
--- /dev/null
+++ b/guide/concepts/dependent-configuration.md
@@ -0,0 +1,34 @@
+---
+title: Dependent Configuration
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Under the covers Brooklyn has a sophisticated sensor event and subscription model, but conveniences around this model make it very simple to express cross-entity dependencies. Consider the example where Tomcat instances need to know the URL of a database (or a set of URLs to connect to a Monterey processing fabric, or other entities)
+
+{% highlight java %}
+setConfiguration(UsesJava.JAVA_OPTIONS, ImmutableMap.of("mysql.url",
+ attributeWhenReady(mysql, MySqlNode.MY_SQL_URL) ))
+{% endhighlight %}
+
+The ``attributeWhenReady(Entity, Sensor)`` call (a static method on the class ``DependentConfiguration``)
+causes the configuration value to be set when that given entity's attribue is ready.
+In the example, ``attributeWhenReady()`` causes the JVM system property ``mysql.url`` to be set to the value of the ``MySqlNode.MY_SQL_URL`` sensor from ``mysql`` when that value is ready. As soon as the database URL is announced by the MySql entity, the configuration value will be available to the Tomcat cluster.
+
+By default "ready" means being *set* (non-null) and, if appropriate, *non-empty* (for collections and strings) or *non-zero* (for numbers). Formally the interpretation of ready is that of "Groovy truth" defined by an ``asBoolean()`` method on the class and in the Groovy language extensions.
+
+You can customize "readiness" by supplying a ``Predicate`` (Google common) or ``Closure`` (Groovy) in a third parameter.
+This evaluates candidate values reported by the sensor until one is found to be ``true``.
+For example, passing ``{ it.size()>=3 }`` as the readiness argument would require at least three management plane URLs.
+
+More information on this can be found in the javadoc for ``DependentConfiguration``,
+along with a few other methods such as ``valueWhenAttributeReady`` which allow post-processing of an attribute value.
+
+Note that if the value of ``CONFIG_KEY`` passed to ``Entity.getConfig`` is a Closure or Task (such as returned by ``attributeWhenReady``),
+the first access of ``Entity.getConfig(CONFIG_KEY)`` will block until the task completes.
+Typically this does the right thing, blocking when necessary to generate the right start-up sequence
+without the developer having to think through the order, but it can take some getting used to.
+Be careful not to request config information until really necessary (or to use non-blocking "raw" mechanisms),
+and in complicated situations be ready to attend to circular dependencies.
+The management console gives useful information for understanding what is happening and resolving the cycle.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/entities.md
----------------------------------------------------------------------
diff --git a/guide/concepts/entities.md b/guide/concepts/entities.md
new file mode 100644
index 0000000..0afeb50
--- /dev/null
+++ b/guide/concepts/entities.md
@@ -0,0 +1,23 @@
+---
+title: Entities
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+The central concept in a Brooklyn deployment is that of an ***entity***.
+An entity represents a resource under management, either *base* entities (individual machines or software processes)
+or logical collections of these entities.
+
+Fundamental to the processing model is the capability of entities to be the *parent* of other entities (the mechanism by which collections are formed),
+with every entity having a single parent entity, up to the privileged top-level ***application*** entity.
+
+Entities are code, so they can be extended, overridden, and modified. Entities can have events, operations, and processing logic associated with them, and it is through this mechanism that the active management is delivered.
+
+The main responsibilities of an entity are:
+
+- Provisioning the entity in the given location or locations
+- Holding configuration and state (attributes) for the entity
+- Reporting monitoring data (sensors) about the status of the entity
+- Exposing operations (effectors) that can be performed on the entity
+- Hosting management policies and tasks related to the entity
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/execution.md
----------------------------------------------------------------------
diff --git a/guide/concepts/execution.md b/guide/concepts/execution.md
new file mode 100644
index 0000000..9762005
--- /dev/null
+++ b/guide/concepts/execution.md
@@ -0,0 +1,34 @@
+---
+title: Execution
+layout: website-normal
+---
+
+All processing, whether an effector invocation or a policy cycle, are tracked as ***tasks***. This allows several important capabilities:
+
+* active and historic processing can be observed by operators
+* the invocation context is available in the thread, to check entitlement (permissions) and maintain a
+hierarchical causal chain even when operations are run in parallel
+* processing can be managed across multiple management nodes
+
+Some executions create new entities, which can then have tasks associated with them, and the system will record, for example, that a start effector on the new entity is a task associated with that entity, with that task
+created by a task associated with a different entity.
+
+The execution of a typical overall start-up sequence is shown below:
+
+[](brooklyn-flow-websequencediagrams.com.png)
+
+
+## Integration
+
+One vital aspect of Brooklyn is its ability to communicate with the systems it starts. This is abstracted using a ***driver*** facility in Brooklyn, where a
+driver describes how a process or service can be installed and managed using a particular technology.
+
+For example, a ``TomcatServer`` may implement start and other effectors using a ``TomcatSshDriver`` which inherits from ``JavaSoftwareProcessSshDriver`` (for JVM and JMX start confguration), inheriting from ``AbstractSoftwareProcessSshDriver``
+(for SSH scripting support).
+
+Particularly for sensors, some technologies are used so frequently that they are
+packaged as ***feeds*** which can discover their configuration (including from drivers). These include JMX and HTTP (see ``JmxFeed`` and ``HttpFeed``).
+
+Brooklyn comes with entity implementations for a growing number of commonly used systems, including various web application servers, databases and NoSQL data stores, and messaging systems.
+
+
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/index.md
----------------------------------------------------------------------
diff --git a/guide/concepts/index.md b/guide/concepts/index.md
new file mode 100644
index 0000000..b27ea8c
--- /dev/null
+++ b/guide/concepts/index.md
@@ -0,0 +1,22 @@
+---
+title: Brooklyn Concepts
+title_in_menu: Brooklyn Concepts
+layout: website-normal
+children:
+- entities.md
+- application-parent-membership.md
+- configuration-sensor-effectors.md
+- lifecycle-managementcontext.md
+- dependent-configuration.md
+- location.md
+- policies.md
+- execution.md
+- stop-start-restart-behaviour.md
+---
+
+This introduces brooklyn and describes how it simplifies the deployment and management of big applications. It is
+intended for people who are using brooklyn-supported application components (such as web/app servers, data stores)
+to be able to use brooklyn to easily start their application in multiple locations with off-the-shelf management
+policies.
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/lifecycle-managementcontext.md
----------------------------------------------------------------------
diff --git a/guide/concepts/lifecycle-managementcontext.md b/guide/concepts/lifecycle-managementcontext.md
new file mode 100644
index 0000000..90cedcf
--- /dev/null
+++ b/guide/concepts/lifecycle-managementcontext.md
@@ -0,0 +1,44 @@
+---
+title: Lifecycle and ManagementContext
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Under-the-covers, at heart of the brooklyn management plane is the ``ManagementContext``.
+This is started automatically when using launching an application using the brooklyn CLI. For programmatic use, see
+``BrooklynLauncher.newLauncher().launch()``.
+
+A Brooklyn deployment consists of many entities in a hierarchical tree, with the privileged *application* entity at the top level.
+
+An application entity (``Application`` class) is responsible for starting the deployment of all its child entities (i.e. the entire entity tree under its ownership).
+
+An ``Application``'s ``start()`` method begins provisioning the child entities of the application (and their entities, recursively).
+
+Provisioning of entities typically happens in parallel automatically,
+although this can be customized. This is implemented as ***tasks*** which are tracked by the management plane and is accessible in the web-based management console and REST API.
+
+Customized provisioning can be useful where two starting entities depend on each other. For example, it is often necessary to delay start of one entity until another entity reaches a certain state, and to supply run-time information about the latter to the former.
+
+<!-- TODO ambiguous language; need a better description of the "manage" lifecycle -->
+When new entities are created, the entity is wired up to an application by giving it a parent. The entity is then explicitly "managed", which allows other entities to discover it.
+
+Typically a Brooklyn deployment has a single management context which records:
+
+* all entities under management that are reachable by the application(s) via the parent-child relationships,
+* the state associated with each entity,
+* subscribers (listeners) to sensor events arising from the entities,
+* active tasks (jobs) associated with any the entity,
+* which Brooklyn management node is mastering (managing) each entity.
+
+<!-- TODO Distributed brooklyn not yet supported; needs clarification in docs -->
+
+In a multi-location deployment, management operates in all regions, with brooklyn entity instances being mastered in the relevant region.
+
+When management is distributed a Brooklyn deployment may consist of multiple Brooklyn management nodes each with a ``ManagementContext`` instance.
+
+<!-- TODO - Clarify the following statements.
+The management context entity forms part of the management plane.
+The management plane is responsible for the distribution of the ``Entity`` instances across multiple machines and multiple locations,
+tracking the transfer of events (subscriptions) between ``Entity`` instances, and the execution of tasks (often initiated by management policies).
+-->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/location.md
----------------------------------------------------------------------
diff --git a/guide/concepts/location.md b/guide/concepts/location.md
new file mode 100644
index 0000000..417d0a7
--- /dev/null
+++ b/guide/concepts/location.md
@@ -0,0 +1,22 @@
+---
+title: Location
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+<!-- TODO, Clarify is how geographical location works.
+-->
+
+Entities can be provisioned/started in the location of your choice. Brooklyn transparently uses [jclouds](http://www.jclouds.org) to support different cloud providers and to support BYON (Bring Your Own Nodes).
+
+The implementation of an entity (e.g. Tomcat) is agnostic about where it will be installed/started. When writing the application definition specify the location or list of possible locations (``Location`` instances) for hosting the entity.
+
+``Location`` instances represent where they run and indicate how that location (resource or service) can be accessed.
+
+For example, a ``JBoss7Server`` will usually be running in an ``SshMachineLocation``, which contains the credentials and address for sshing to the machine. A cluster of such servers may be running in a ``MachineProvisioningLocation``, capable of creating new ``SshMachineLocation`` instances as required.
+
+<!-- TODO, incorporate the following.
+
+The idea is that you could specify the location as AWS and also supply an image id. You could configure the Tomcat entity accordingly: specify the path if the image already has Tomcat installed, or specify that Tomcat must be downloaded/installed. Entities typically use _drivers_ (such as SSH-based) to install, start, and interact with their corresponding real-world instance.
+-->
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/policies.md
----------------------------------------------------------------------
diff --git a/guide/concepts/policies.md b/guide/concepts/policies.md
new file mode 100644
index 0000000..495e57f
--- /dev/null
+++ b/guide/concepts/policies.md
@@ -0,0 +1,11 @@
+---
+title: Policies
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Policies perform the active management enabled by Brooklyn. Entities can have zero or more ``Policy`` instances attached to them.
+
+Policies can subscribe to sensors from entities or run periodically, and
+when they run they can perform calculations, look up other values, and if deemed necessary invoke effectors or emit sensor values from the entity with which they are associated.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/6e86cb02/guide/concepts/stop-start-restart-behaviour.md
----------------------------------------------------------------------
diff --git a/guide/concepts/stop-start-restart-behaviour.md b/guide/concepts/stop-start-restart-behaviour.md
new file mode 100644
index 0000000..916ea5c
--- /dev/null
+++ b/guide/concepts/stop-start-restart-behaviour.md
@@ -0,0 +1,65 @@
+---
+title: Stop/start/restart behaviour
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Many entities expose `start`, `stop` and `restart` effectors. The semantics of these operations (and the parameters they take) depends on the type of entity.
+
+## Top-level applications
+A top-level application is a grouping of other entities, pulling them together into the "application" of your choice. This could range from a single app-server, to an app that is a composite of a no-sql cluster (e.g. MongoDB sharded cluster, or Cassandra spread over multiple datacenters), a cluster of load-balanced app-servers, message brokers, etc.
+
+### start(Collection<Location>)
+This will start the application in the given location(s). Each child-entity within the application will be started concurrently, passing the location(s) to each child.
+The start effector will be called automatically when the application is deployed through the catalog.
+Is is strongly recommended to not call start again.
+
+### stop()
+Stop will terminate the application and all its child entities (including releasing all their resources).
+The application will also be unmanaged, **removing** it from Brooklyn.
+
+### restart()
+This will invoke `restart()` on each child-entity concurrently (with the default values for the child-entity's restart effector parameters).
+Is is strongly recommended to not call this, unless the application has been explicitly written to implement restart.
+
+## Software Process (e.g MySql, Tomcat, JBoss app-server, MongoDB)
+
+### start(Collection<Location>)
+This will start the software process in the given location.
+If a machine location is passed in, then the software process is started there.
+If a cloud location is passed in, then a new VM will be created in that cloud - the software process will be **installed+launched** on that new VM.
+
+The start effector will have been called automatically when deploying an application through the catalog.
+In normal usage, do not invoke start again.
+
+If calling `start()` a second time, with no locations passed in (e.g. an empty list), then it will go through the start sequence on the existing location from the previous call.
+It will **install+customize+launch** the process.
+For some entities, this could be *dangerous*. The customize step might execute a database initialisation script, which could cause data to be overwritten (depending how the initialisation script was written).
+
+If calling `start()` a second time with additional locations, then these additional locations will be added to the set of locations.
+In normal usage it is not recommended.
+This could be desired behaviour if the entity had previously been entirely stopped (including its VM terminated) - but for a simple one-entity app then you might as well have deleted the entire app and created a new one.
+
+
+### stop(boolean stopMachine)
+If `stopMachine==true`, this effector will stop the software process and then terminate the VM (if a VM had been created as part of `start()`). This behaviour is the inverse of the first `start()` effector call.
+When stopping the software process, it does not uninstall the software packages / files.
+
+If `stopMachine==false`, this effector will stop just the software process (leaving the VM and all configuration files / install artifacts in place).
+
+### restart(boolean restartMachine, boolean restartChildren)
+This will restart the software process.
+
+If `restartMachine==true`, it will also terminate the VM and create a new VM. It will then install+customize+launch the software process on the new VM. It is equivalent of invoking `stop(true)` and then `start(Collections.EMPTY_LIST)`.
+If `restartMachine==false`, it will first attempt to stop the software process (which should be a no-op if the process is not running), and will then start the software process (without going through the **install+customize** steps).
+
+If `restartChildren==true`, then after restarting itself it will call `restart(restartMachine, restartChildren)` on each child-entity concurrently.
+
+## Recommended operations
+
+The recommended operations to invoke to stop just the software process, and then to restart it are:
+
+* Select the software process entity in the tree (*not* the parent application, but the child of that application).
+* Invoke `stop(stopMachine=false)`
+* Invoke `restart(restartMachine=false, restartChildren=false)`
\ No newline at end of file