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 <[email protected]> Authored: Tue Sep 8 14:26:32 2015 +0100 Committer: Alex Heneveld <[email protected]> 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`) + +
