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 2015/09/15 18:53:23 UTC
[04/15] incubator-brooklyn git commit: update ops docs - add REST
reference, update others
update ops docs - add REST reference, update others
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/bbe83662
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/bbe83662
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/bbe83662
Branch: refs/heads/master
Commit: bbe83662e64582a4ddc180e098e6160905b1093a
Parents: 1e24fb5
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Tue Sep 8 14:26:32 2015 +0100
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Tue Sep 8 14:47:57 2015 +0100
----------------------------------------------------------------------
docs/guide/ops/cli-reference.md | 201 +++++++++++++++++++++++++
docs/guide/ops/index.md | 9 +-
docs/guide/ops/install-on-server.md | 131 ----------------
docs/guide/ops/launch.md | 201 -------------------------
docs/guide/ops/production-installation.md | 103 +++++++++++++
docs/guide/ops/requirements.md | 2 +-
docs/guide/ops/rest.md | 89 +++++++++++
7 files changed, 399 insertions(+), 337 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/cli-reference.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/cli-reference.md b/docs/guide/ops/cli-reference.md
new file mode 100644
index 0000000..c4fd929
--- /dev/null
+++ b/docs/guide/ops/cli-reference.md
@@ -0,0 +1,201 @@
+---
+title: CLI Reference
+layout: website-normal
+---
+
+## Launch command
+
+To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
+
+{% highlight bash %}
+% nohup bin/brooklyn launch > /dev/null 2&>1 &
+{% endhighlight %}
+
+With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
+No password is set, but the server is listening only on the loopback network interface for security.
+Once [security is configured](brooklyn_properties.html), Brooklyn will listen on all network interfaces by default.
+By default, Brooklyn will write log messages at the INFO level or above to `brooklyn.info.log` and messgages at the
+DEBUG level or above to `brooklyn.debug.log`. Redirecting the output to `/dev/null` prevents the default console output
+being written to `nohup.out`.
+
+You may wish to [add Brooklyn to your path](#path-setup);
+assuming you've done this, to get information the supported CLI options
+at any time, just run `brooklyn help`:
+
+{% highlight bash %}
+% bin/brooklyn help
+
+usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
+
+The most commonly used brooklyn commands are:
+ help Display help information about brooklyn
+ info Display information about brooklyn
+ launch Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
+
+See 'brooklyn help <command>' for more information on a specific command.
+{% endhighlight %}
+
+It is important that Brooklyn is launched with either `nohup ... &` or `... & disown`, to ensure
+it keeps running after the shell terminates.
+
+
+### Other CLI Arguments
+
+The CLI arguments for [persistence and HA](persistence/) are described separately.
+
+
+### Path Setup
+
+In order to have easy access to the cli it is useful to configure the PATH environment
+variable to also point to the cli's bin directory:
+
+{% highlight bash %}
+BROOKLYN_HOME=/path/to/brooklyn/
+export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
+{% endhighlight %}
+
+
+### Memory Usage
+
+The amount of memory required by the Brooklyn process depends on the usage
+- for example the number of entities/VMs under management.
+
+For a standard Brooklyn deployment, the defaults are to start with 256m, and to grow to 1g of memory.
+These numbers can be overridden by setting the environment variable `JAVA_OPTS` before launching
+the `brooklyn script`:
+
+ JAVA_OPTS=-Xms1g -Xmx1g -XX:MaxPermSize=256m
+
+Brooklyn stores a task history in-memory using [soft references](http://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html).
+This means that, once the task history is large, Brooklyn will continually use the maximum allocated
+memory. It will only expunge tasks from memory when this space is required for other objects within the
+Brooklyn process.
+
+
+## Configuration
+
+### Configuration Files
+
+Brooklyn reads configuration from a variety of places. It aggregates the configuration.
+The list below shows increasing precedence (i.e. the later ones will override values
+from earlier ones, if exactly the same property is specified multiple times).
+
+1. `classpath://brooklyn/location-metadata.properties` is shipped as part of Brooklyn, containing
+ generic metadata such as jurisdiction and geographic information about Cloud providers.
+1. The file `~/.brooklyn/location-metadata.properties` (unless `--noGlobalBrooklynProperties` is specified).
+ This is intended to contain custom metadata about additional locations.
+1. The file `~/.brooklyn/brooklyn.properties` (unless `--noGlobalBrooklynProperties` is specified).
+1. Another properties file, if the `--localBrooklynProperties <local brooklyn.properties file>` is specified.
+1. Shell environment variables
+1. System properties, supplied with ``-D`` on the brooklyn (Java) command-line.
+
+These properties are described in more detail [here](brooklyn_properties.html).
+
+
+### Extending the Classpath
+
+The default Brooklyn directory structure includes:
+
+* `./conf/`: for configuration resources.
+* `./lib/patch/`: for Jar files containing patches.
+* `./lib/brooklyn/`: for the brooklyn libraries.
+* `./lib/dropins/`: for additional Jars.
+
+Resources added to `conf/` will be available on the classpath.
+
+A patch can be applied by adding a Jar to the `lib/patch/` directory, and restarting Brooklyn.
+All jars in this directory will be at the head of the classpath.
+
+Additional Jars should be added to `lib/dropins/`, prior to starting Brooklyn. These jars will
+be at the end of the classpath.
+
+The initial classpath, as set in the `brooklyn` script, is:
+
+ conf:lib/patch/*:lib/brooklyn/*:lib/dropins/*
+
+Additional entries can be added at the head of the classpath by setting the environment variable
+`BROOKLYN_CLASSPATH` before running the `brooklyn` script.
+
+
+### Replacing the web-console
+
+*Work in progress.*
+
+The Brooklyn web-console is loaded from the classpath as the resource `classpath://brooklyn.war`.
+
+To replace this, an alternative WAR with that name can be added at the head of the classpath.
+However, this approach is likely to change in a future release - consider this feature as "beta".
+
+
+## Cloud Explorer
+
+The `brooklyn` command line tool includes support for querying (and managing) cloud
+compute resources and blob-store resources.
+
+For example, `brooklyn cloud-compute list-instances --location aws-ec2:eu-west-1`
+will use the AWS credentials from `brooklyn.properties` and list the VM instances
+running in the given EC2 region.
+
+Use `brooklyn help` and `brooklyn help cloud-compute` to find out more information.
+
+This functionality is not intended as a generic cloud management CLI, but instead
+solves specific Brooklyn use-cases. The main use-case is discovering the valid
+configuration options on a given cloud, such as for `imageId` and `hardwareId`.
+
+
+### Cloud Compute
+
+The command `brooklyn cloud-compute` has the following options:
+
+* `list-images`: lists VM images within the given cloud, which can be chosen when
+ provisioning new VMs.
+ This is useful for finding the possible values for the `imageId` configuration.
+
+* `get-image <imageId1> <imageId2> ...`: retrieves metadata about the specific images.
+
+* `list-hardware-profiles`: lists the ids and the details of the hardware profiles
+ available when provisioning.
+ This is useful for finding the possible values for the `hardwareId` configuration.
+
+* `default-template`: retrieves metadata about the image and hardware profile that will
+ be used by Brooklyn for that location, if no additional configuration options
+ are supplied.
+
+* `list-instances`: lists the VM instances within the given cloud.
+
+* `terminate-instances <instanceId1> <instanceId2> ...`: Terminates the instances with
+ the given ids.
+
+
+### Blob Store
+
+The command `brooklyn cloud-blobstore` is used to access a given object store, such as S3
+or Swift. It has the following options:
+
+* `list-containers`: lists the containers (i.e. buckets in S3 terminology) within the
+ given object store.
+
+* `list-container <containerName>`: lists all the blobs (i.e. objects) contained within
+ the given container.
+
+* `blob --container <containerName> --blob <blobName>`: retrieves the given blob
+ (i.e. object), including metadata and its contents.
+
+
+## Running from a Source Build
+
+Here is an example of the commands you might run to get the Brooklyn code,
+compile it and launch an application:
+
+{% highlight bash %}
+git clone https://github.com/apache/incubator-brooklyn.git
+cd brooklyn
+mvn clean install -DskipTests
+BROOKLYN_HOME=$(pwd)
+export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
+export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
+nohup brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost &
+{% endhighlight %}
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md
index 1cb28aa..1f74074 100644
--- a/docs/guide/ops/index.md
+++ b/docs/guide/ops/index.md
@@ -2,16 +2,17 @@
title: Operations
layout: website-normal
children:
-- requirements.md
-- install-on-server.md
-- launch.md
+- cli-reference.md
- brooklyn_properties.md
- locations/
- persistence/
- high-availability.md
- catalog/
+- rest.md
- logging.md
+- requirements.md
+- production-installation.md
- troubleshooting/
---
-{% include list-children.html %}
\ No newline at end of file
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/install-on-server.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/install-on-server.md b/docs/guide/ops/install-on-server.md
deleted file mode 100644
index 48a527e..0000000
--- a/docs/guide/ops/install-on-server.md
+++ /dev/null
@@ -1,131 +0,0 @@
----
-layout: website-normal
-title: Installing Apache Brooklyn
----
-
-{% include fields.md %}
-
-Here we present two *alternatives* to install Apache Brooklyn:
-
-- [Running the *installation script*](#script)
-- [Manual installation](#manual)
-
-
-## <a id="script"></a> Running the Installation Script
-
-There is a simple bash script available to help with the installation process.
-
-#### Script prerequisites
-The script assumes that the server is a recent *RHEL/CentOS 6.x Linux* or *Ubuntu 12.04* installation, but other Linux variants have been tested successfully.
-
-The script will install Java 7 and other required packages if they are not present.
-You must have root access over [passwordless SSH]({{ site.path.guide }}/ops/locations/ssh-keys.html)
-to install Brooklyn, but the service runs as an ordinary user once installed.
-
-To manage the Brooklyn service you must also be able to connect to port 8081 remotely.
-
-Once the above prerequisites are satisfied, you should be able to run successfully:
-{% highlight bash %}
-$ curl -o brooklyn-install.sh -L https://github.com/apache/incubator-brooklyn/raw/master/brooklyn-install.sh
-$ chmod +x ./brooklyn-install.sh
-$ ./brooklyn-install.sh -s -r <your-server-ip>
-{% endhighlight %}
-
-
-## <a id="manual"></a> Manual Installation
-
-1. [Set up the prerequisites](#prerequisites)
-1. [Download Apache Brooklyn](#download)
-1. [Configuring brooklyn.properties](#configuring-properties)
-1. [Configuring default.catalog.bom](#configuring-catalog)
-1. [Test the installation](#confirm)
-
-
-### <a id="prerequisites"></a>Set up the Prerequisites
-
-Before installing Brooklyn, it is recommended to configure the host as follows.
-
-* install Java JRE or JDK (version 7 or later)
-* install an [SSH key]({{ site.path.guide }}/ops/locations/ssh-keys.html), if not available
-* enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/ssh-keys.html)
-* create a `~/.brooklyn` directory on the host with `$ mkdir ~/.brooklyn`
-* check your `iptables` or other firewall service, making sure that incoming connections on port 8443 is not blocked
-* check that the [linux kernel entropy]({{ site.path.website }}/documentation/increase-entropy.html) is sufficient
-
-
-### <a id="download"></a>Download Apache Brooklyn
-
-Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download/).
-
-{% if brooklyn_version contains 'SNAPSHOT' %}
-Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
-{% else %}
-Expand the `tar.gz` archive:
-{% endif %}
-
-{% if brooklyn_version contains 'SNAPSHOT' %}
-{% highlight bash %}
-$ tar -zxf apache-brooklyn-dist-{{ site.brooklyn-stable-version }}-timestamp-dist.tar.gz
-{% endhighlight %}
-{% else %}
-{% highlight bash %}
-$ tar -zxf apache-brooklyn-{{ site.brooklyn-stable-version }}-dist.tar.gz
-{% endhighlight %}
-{% endif %}
-
-This will create a `apache-brooklyn-{{ site.brooklyn-stable-version }}` folder.
-
-Let's setup some paths for easy commands.
-
-{% highlight bash %}
-$ cd apache-brooklyn-{{ site.brooklyn-stable-version }}
-$ BROOKLYN_DIR="$(pwd)"
-$ export PATH=$PATH:$BROOKLYN_DIR/bin/
-{% endhighlight %}
-
-
-### <a id="configuring-properties"></a>Configuring brooklyn.properties
-
-Brooklyn deploys applications to Locations. *Locations* can be clouds, machines with fixed IPs or localhost (for testing).
-
-By default Brooklyn loads configuration parameters (including credentials for any cloud accounts) from
-
-`~/.brooklyn/brooklyn.properties`
-
-The `brooklyn.properties` is the main configuration file for deployment locations. Contains the connection details and credentials for all public or on-premises cloud providers, as well as controlling some application startup and security options.
-
-Create a `.brooklyn` folder in your home directory and download the template [brooklyn.properties]({{brooklyn_properties_url_path}}) to that folder.
-
-{% highlight bash %}
-$ mkdir -p ~/.brooklyn
-$ wget -O ~/.brooklyn/brooklyn.properties {{brooklyn_properties_url_live}}
-$ chmod 600 ~/.brooklyn/brooklyn.properties
-{% endhighlight %}
-
-You may need to edit `~/.brooklyn/brooklyn.properties` to ensure that brooklyn can access cloud locations for application deployment.
-
-
-### <a id="configuring-catalog"></a>Configuring the Catalog
-
-By default Brooklyn loads the catalog of available application components and services from
-`default.catalog.bom` on the classpath. The initial catalog is in `conf/brooklyn/` in the dist.
-If you have a preferred catalog, simply replace that file.
-
-
-### <a id="confirm"></a>Confirm Installation
-
-We can do a quick test drive by launching Brooklyn:
-
-{% highlight bash %}
-$ brooklyn launch
-{% endhighlight %}
-
-Brooklyn will output the address of the management interface:
-
-{% highlight bash %}
-INFO Starting brooklyn web-console on loopback interface because no security config is set
-
-INFO Started Brooklyn console at http://127.0.0.1:8081/, running classpath://brooklyn.war and []
-{% endhighlight %}
-
-Stop Brooklyn with ctrl-c.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/launch.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/launch.md b/docs/guide/ops/launch.md
deleted file mode 100644
index bdfa47d..0000000
--- a/docs/guide/ops/launch.md
+++ /dev/null
@@ -1,201 +0,0 @@
----
-title: Launching Brooklyn
-layout: website-normal
----
-
-## Launch command
-
-To launch Brooklyn, from the directory where Brooklyn is unpacked, run:
-
-{% highlight bash %}
-% nohup bin/brooklyn launch > /dev/null 2&>1 &
-{% endhighlight %}
-
-With no configuration, this will launch the Brooklyn web console and REST API on [`http://localhost:8081/`](http://localhost:8081/).
-No password is set, but the server is listening only on the loopback network interface for security.
-Once [security is configured](brooklyn_properties.html), Brooklyn will listen on all network interfaces by default.
-By default, Brooklyn will write log messages at the INFO level or above to `brooklyn.info.log` and messgages at the
-DEBUG level or above to `brooklyn.debug.log`. Redirecting the output to `/dev/null` prevents the default console output
-being written to `nohup.out`.
-
-You may wish to [add Brooklyn to your path](#path-setup);
-assuming you've done this, to get information the supported CLI options
-at any time, just run `brooklyn help`:
-
-{% highlight bash %}
-% bin/brooklyn help
-
-usage: brooklyn [(-q | --quiet)] [(-v | --verbose)] <command> [<args>]
-
-The most commonly used brooklyn commands are:
- help Display help information about brooklyn
- info Display information about brooklyn
- launch Starts a brooklyn application. Note that a BROOKLYN_CLASSPATH environment variable needs to be set up beforehand to point to the user application classpath.
-
-See 'brooklyn help <command>' for more information on a specific command.
-{% endhighlight %}
-
-It is important that Brooklyn is launched with either `nohup ... &` or `... & disown`, to ensure
-it keeps running after the shell terminates.
-
-
-### Other CLI Arguments
-
-The CLI arguments for [persistence and HA](persistence/) are described separately.
-
-
-### Path Setup
-
-In order to have easy access to the cli it is useful to configure the PATH environment
-variable to also point to the cli's bin directory:
-
-{% highlight bash %}
-BROOKLYN_HOME=/path/to/brooklyn/
-export PATH=$PATH:$BROOKLYN_HOME/usage/dist/target/brooklyn-dist/bin/
-{% endhighlight %}
-
-
-### Memory Usage
-
-The amount of memory required by the Brooklyn process depends on the usage
-- for example the number of entities/VMs under management.
-
-For a standard Brooklyn deployment, the defaults are to start with 256m, and to grow to 1g of memory.
-These numbers can be overridden by setting the environment variable `JAVA_OPTS` before launching
-the `brooklyn script`:
-
- JAVA_OPTS=-Xms1g -Xmx1g -XX:MaxPermSize=256m
-
-Brooklyn stores a task history in-memory using [soft references](http://docs.oracle.com/javase/7/docs/api/java/lang/ref/SoftReference.html).
-This means that, once the task history is large, Brooklyn will continually use the maximum allocated
-memory. It will only expunge tasks from memory when this space is required for other objects within the
-Brooklyn process.
-
-
-## Configuration
-
-### Configuration Files
-
-Brooklyn reads configuration from a variety of places. It aggregates the configuration.
-The list below shows increasing precedence (i.e. the later ones will override values
-from earlier ones, if exactly the same property is specified multiple times).
-
-1. `classpath://brooklyn/location-metadata.properties` is shipped as part of Brooklyn, containing
- generic metadata such as jurisdiction and geographic information about Cloud providers.
-1. The file `~/.brooklyn/location-metadata.properties` (unless `--noGlobalBrooklynProperties` is specified).
- This is intended to contain custom metadata about additional locations.
-1. The file `~/.brooklyn/brooklyn.properties` (unless `--noGlobalBrooklynProperties` is specified).
-1. Another properties file, if the `--localBrooklynProperties <local brooklyn.properties file>` is specified.
-1. Shell environment variables
-1. System properties, supplied with ``-D`` on the brooklyn (Java) command-line.
-
-These properties are described in more detail [here](brooklyn_properties.html).
-
-
-### Extending the Classpath
-
-The default Brooklyn directory structure includes:
-
-* `./conf/`: for configuration resources.
-* `./lib/patch/`: for Jar files containing patches.
-* `./lib/brooklyn/`: for the brooklyn libraries.
-* `./lib/dropins/`: for additional Jars.
-
-Resources added to `conf/` will be available on the classpath.
-
-A patch can be applied by adding a Jar to the `lib/patch/` directory, and restarting Brooklyn.
-All jars in this directory will be at the head of the classpath.
-
-Additional Jars should be added to `lib/dropins/`, prior to starting Brooklyn. These jars will
-be at the end of the classpath.
-
-The initial classpath, as set in the `brooklyn` script, is:
-
- conf:lib/patch/*:lib/brooklyn/*:lib/dropins/*
-
-Additional entries can be added at the head of the classpath by setting the environment variable
-`BROOKLYN_CLASSPATH` before running the `brooklyn` script.
-
-
-### Replacing the web-console
-
-*Work in progress.*
-
-The Brooklyn web-console is loaded from the classpath as the resource `classpath://brooklyn.war`.
-
-To replace this, an alternative WAR with that name can be added at the head of the classpath.
-However, this approach is likely to change in a future release - consider this feature as "beta".
-
-
-## Cloud Explorer
-
-The `brooklyn` command line tool includes support for querying (and managing) cloud
-compute resources and blob-store resources.
-
-For example, `brooklyn cloud-compute list-instances --location aws-ec2:eu-west-1`
-will use the AWS credentials from `brooklyn.properties` and list the VM instances
-running in the given EC2 region.
-
-Use `brooklyn help` and `brooklyn help cloud-compute` to find out more information.
-
-This functionality is not intended as a generic cloud management CLI, but instead
-solves specific Brooklyn use-cases. The main use-case is discovering the valid
-configuration options on a given cloud, such as for `imageId` and `hardwareId`.
-
-
-### Cloud Compute
-
-The command `brooklyn cloud-compute` has the following options:
-
-* `list-images`: lists VM images within the given cloud, which can be chosen when
- provisioning new VMs.
- This is useful for finding the possible values for the `imageId` configuration.
-
-* `get-image <imageId1> <imageId2> ...`: retrieves metadata about the specific images.
-
-* `list-hardware-profiles`: lists the ids and the details of the hardware profiles
- available when provisioning.
- This is useful for finding the possible values for the `hardwareId` configuration.
-
-* `default-template`: retrieves metadata about the image and hardware profile that will
- be used by Brooklyn for that location, if no additional configuration options
- are supplied.
-
-* `list-instances`: lists the VM instances within the given cloud.
-
-* `terminate-instances <instanceId1> <instanceId2> ...`: Terminates the instances with
- the given ids.
-
-
-### Blob Store
-
-The command `brooklyn cloud-blobstore` is used to access a given object store, such as S3
-or Swift. It has the following options:
-
-* `list-containers`: lists the containers (i.e. buckets in S3 terminology) within the
- given object store.
-
-* `list-container <containerName>`: lists all the blobs (i.e. objects) contained within
- the given container.
-
-* `blob --container <containerName> --blob <blobName>`: retrieves the given blob
- (i.e. object), including metadata and its contents.
-
-
-## Running from a Source Build
-
-Here is an example of the commands you might run to get the Brooklyn code,
-compile it and launch an application:
-
-{% highlight bash %}
-git clone https://github.com/apache/incubator-brooklyn.git
-cd brooklyn
-mvn clean install -DskipTests
-BROOKLYN_HOME=$(pwd)
-export PATH=${PATH}:${BROOKLYN_HOME}/usage/dist/target/brooklyn-dist/bin/
-export BROOKLYN_CLASSPATH=${BROOKLYN_HOME}/examples/simple-web-cluster/target/classes
-nohup brooklyn launch --app brooklyn.demo.SingleWebServerExample --location localhost &
-{% endhighlight %}
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/production-installation.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/production-installation.md b/docs/guide/ops/production-installation.md
new file mode 100644
index 0000000..b0110d5
--- /dev/null
+++ b/docs/guide/ops/production-installation.md
@@ -0,0 +1,103 @@
+---
+layout: website-normal
+title: Production Installation
+---
+
+{% include fields.md %}
+
+To install Apache Brooklyn on a production server:
+
+1. [Set up the prerequisites](#prerequisites)
+1. [Download Apache Brooklyn](#download)
+1. [Configuring brooklyn.properties](#configuring-properties)
+1. [Configuring default.catalog.bom](#configuring-catalog)
+1. [Test the installation](#confirm)
+
+This guide covers the basics. You may also wish to configure:
+
+* [Logging](logging.md)
+* [Persistence](persistence/)
+* [High availability](high-availability.md)
+
+
+### <a id="prerequisites"></a>Set up the Prerequisites
+
+Check that the server meets the [requirements](requirements.md).
+Then configure the server as follows:
+
+* install Java JRE or JDK (version 7 or later)
+* install an [SSH key]({{ site.path.guide }}/ops/locations/ssh-keys.html), if not available
+* enable [passwordless ssh login]({{ site.path.guide }}/ops/locations/ssh-keys.html)
+* create a `~/.brooklyn` directory on the host with `$ mkdir ~/.brooklyn`
+* check your `iptables` or other firewall service, making sure that incoming connections on port 8443 is not blocked
+* check that the [linux kernel entropy]({{ site.path.website }}/documentation/increase-entropy.html) is sufficient
+
+
+### <a id="download"></a>Download Apache Brooklyn
+
+Download Brooklyn and obtain a binary build as described on [the download page]({{site.path.website}}/download/).
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+Expand the `tar.gz` archive (note: as this is a -SNAPSHOT version, your filename will be slightly different):
+{% else %}
+Expand the `tar.gz` archive:
+{% endif %}
+
+{% if brooklyn_version contains 'SNAPSHOT' %}
+{% highlight bash %}
+% tar -zxf apache-brooklyn-dist-{{ site.brooklyn-stable-version }}-timestamp-dist.tar.gz
+{% endhighlight %}
+{% else %}
+{% highlight bash %}
+% tar -zxf apache-brooklyn-{{ site.brooklyn-stable-version }}-dist.tar.gz
+{% endhighlight %}
+{% endif %}
+
+This will create a `apache-brooklyn-{{ site.brooklyn-stable-version }}` folder.
+
+Let's setup some paths for easy commands.
+
+{% highlight bash %}
+% cd apache-brooklyn-{{ site.brooklyn-stable-version }}
+% BROOKLYN_DIR="$(pwd)"
+% export PATH=$PATH:$BROOKLYN_DIR/bin/
+{% endhighlight %}
+
+
+### <a id="configuring-properties"></a>Configuring brooklyn.properties
+
+Set up `brooklyn.properties` as described [here](brooklyn_properties.md):
+
+* Configure the users who should have access
+* Turn on HTTPS
+* Supply credentials for any pre-defined clouds
+
+It may be useful to use the following script to install an initial `brooklyn.properties`:
+
+{% highlight bash %}
+% mkdir -p ~/.brooklyn
+% wget -O ~/.brooklyn/brooklyn.properties {{brooklyn_properties_url_live}}
+% chmod 600 ~/.brooklyn/brooklyn.properties
+{% endhighlight %}
+
+
+### <a id="configuring-catalog"></a>Configuring the Catalog
+
+By default Brooklyn loads the catalog of available application components and services from
+`default.catalog.bom` on the classpath. The initial catalog is in `conf/brooklyn/` in the dist.
+If you have a preferred catalog, simply replace that file.
+
+[More information on the catalog is available here.](catalog/)
+
+
+### <a id="confirm"></a>Confirm Installation
+
+Launch Brooklyn in a disconnected session so it will remain running after you have logged out:
+
+{% highlight bash %}
+% nohup bin/brooklyn launch > /dev/null 2&>1 &
+{% endhighlight %}
+
+Apache Brooklyn should now be running on port 8081 (or other port if so specified).
+
+
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/requirements.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/requirements.md b/docs/guide/ops/requirements.md
index e86629e..634e4e6 100644
--- a/docs/guide/ops/requirements.md
+++ b/docs/guide/ops/requirements.md
@@ -15,7 +15,7 @@ For dev/test or when there are only a handful of VMs being managed, a small VM i
For example, an AWS m3.medium with one vCPU, 3.75GiB RAM and 4GB disk.
For larger production uses, a more appropriate machine spec would be two or more cores,
-at least 8GB RAM and 20GB disk. The disk is just for logs, a small amount of persisted state, and
+at least 8GB RAM and 100GB disk. The disk is just for logs, a small amount of persisted state, and
any binaries for custom blueprints/integrations.
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/bbe83662/docs/guide/ops/rest.md
----------------------------------------------------------------------
diff --git a/docs/guide/ops/rest.md b/docs/guide/ops/rest.md
new file mode 100644
index 0000000..c1d7b64
--- /dev/null
+++ b/docs/guide/ops/rest.md
@@ -0,0 +1,89 @@
+---
+title: REST API
+layout: website-normal
+---
+
+Apache Brooklyn exposes a powerful REST API,
+allowing it to be scripted from bash or integrated with other systems.
+
+For many commands, the REST call follows the same structure as the web console URL
+scheme, but with the `#` at the start of the path removed; for instance the catalog
+item `cluster` in the web console is displayed at:
+
+<!-- BROOKLYN_VERSION_BELOW -->
+ http://localhost:8081/#v1/catalog/entities/cluster:0.9.0-SNAPSHOT
+
+And in the REST API it is accessed at:
+
+<!-- BROOKLYN_VERSION_BELOW -->
+ http://localhost:8081/v1/catalog/entities/cluster:0.9.0-SNAPSHOT
+
+A full reference for the REST API is automatically generated by the server at runtime.
+It can be found in the Brooklyn web console, under the Script tab.
+
+Here we include some of the most common REST examples and other advice for working with the REST API.
+
+
+### Tooling Tips
+
+For command-line access, we recommend `curl`, with tips below.
+
+For navigating in a browser we recommend getting a plugin for
+working with REST; these are available for most browsers and
+make it easier to authenticate, set headers, and see JSON responses.
+
+For manipulating JSON responses on the command-line,
+the library `jq` from [stedolan's github](https://stedolan.github.io/jq/)
+is very useful, and available in most package repositories, including `port` and `brew` on Mac.
+
+
+### Common REST Examples
+
+Here are some useful snippets:
+
+* List applications
+
+ curl http://localhost:8081/v1/applications
+
+* Deploy an application from `__FILE__`
+
+ curl http://localhost:8081/v1/applications --data-binary @__FILE__
+
+* Get details of a task with ID `__ID__` (where the `id` is returned by the above,
+ optionally piped to `jq .id`)
+
+ curl http://localhost:8081/v1/activities/__ID__
+
+* Get the value of sensor `service.state` on entity `e1` in application `app1`
+ (note you can use either the entity's ID or its name)
+
+ curl http://localhost:8081/v1/applications/app1/entities/e1/sensors/service.state
+
+* Get all sensor values (using the pseudo-sensor `current-state`)
+
+ curl http://localhost:8081/v1/applications/app1/entities/e1/sensors/service.state
+
+* Invoke an effector `eff` on `e1`, with argument `arg1` equal to `hi`
+ (note if no arguments, you must specify `-d ""`; for multiple args, just use multiple `-d` entries,
+ or a JSON file with `--data-binary @...`)
+
+ curl http://localhost:8081/v1/applications/app1/entities/e1/effectors/eff -d arg1=hi
+
+* Add an item to the catalog from `__FILE__`
+
+ curl http://localhost:8081/v1/catalog --data-binary @__FILE__
+
+
+### Curl Cheat Sheet
+
+* if authentication is required, use `--user username:password`
+* to see detailed output, including headers, code, and errors, use `-v`
+* where the request is not a simple HTTP GET, use `-X POST` or `-X DELETE`
+* to pass key-value data to a post, use `-d key=value`
+* where you are posting from a file `__FILE__`, use `--data-binary @__FILE__` (implies a POST) or `-T __FILE__ -X POST`
+* to add a header, use `-H "key: value"`, for example `-H "Brooklyn-Allow-Non-Master-Access: true"`
+* to specify that a specific content-type is being uploaded, use `-H "Content-Type: application/json"` (or `application/yaml`)
+* to specify the content-type required for the result, use `-H "Accept: application/json"`
+ (or `application/yaml`, or for sensor values, `text/plain`)
+
+