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 <[email protected]> Authored: Wed Dec 23 11:01:46 2015 +0000 Committer: Alex Heneveld <[email protected]> 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 %} + + +
