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/12/23 12:07:33 UTC
[70/71] [abbrv] incubator-brooklyn git commit: This closes #1118
This closes #1118
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/9eadd25d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/9eadd25d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/9eadd25d
Branch: refs/heads/master
Commit: 9eadd25ddd95bf99648087159b066c8e97460289
Parents: 39c1974 743515e
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Wed Dec 23 11:01:46 2015 +0000
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Wed Dec 23 11:01:46 2015 +0000
----------------------------------------------------------------------
brooklyn-docs/guide/ops/index.md | 1 +
brooklyn-docs/guide/ops/server-cli-reference.md | 3 +
docs/guide/ops/cli/cli-ref-guide.md | 310 ++++++++++++
docs/guide/ops/cli/cli-usage-guide.md | 477 +++++++++++++++++++
docs/guide/ops/cli/index.md | 12 +
5 files changed, 803 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/9eadd25d/brooklyn-docs/guide/ops/index.md
----------------------------------------------------------------------
diff --cc brooklyn-docs/guide/ops/index.md
index 0dfd8ea,0000000..78644d9
mode 100644,000000..100644
--- a/brooklyn-docs/guide/ops/index.md
+++ b/brooklyn-docs/guide/ops/index.md
@@@ -1,21 -1,0 +1,22 @@@
+---
+title: Operations
+layout: website-normal
+children:
+- server-cli-reference.md
++- cli/
+- gui/
+- brooklyn_properties.md
+- locations/
+- persistence/
+- high-availability.md
+- catalog/
+- rest.md
+- logging.md
+- externalized-configuration.md
+- requirements.md
+- production-installation.md
+- security-guidelines.md
+- troubleshooting/
+---
+
+{% include list-children.html %}
http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/9eadd25d/brooklyn-docs/guide/ops/server-cli-reference.md
----------------------------------------------------------------------
diff --cc brooklyn-docs/guide/ops/server-cli-reference.md
index b964b26,0000000..cd8668b
mode 100644,000000..100644
--- a/brooklyn-docs/guide/ops/server-cli-reference.md
+++ b/brooklyn-docs/guide/ops/server-cli-reference.md
@@@ -1,201 -1,0 +1,204 @@@
+---
+title: Server CLI Reference
+layout: website-normal
+---
+
++**NOTE:** This document is for information on starting a Brooklyn Server. For information on using the Brooklyn Client CLI to access an
++already running Brooklyn Server, refer to [Client CLI Reference](cli/index.html).
++
+## 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 Server CLI Arguments
+
+The Server CLI arguments for [persistence and HA](persistence/) are described separately.
+
+
+### Path Setup
+
+In order to have easy access to the server 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 %}
+
+
+