install a default.catalog.bom, and update docs and tweak poms to exclude license since these are config files the user is meant to edit; remove the old catalog.xml, including mentions in the docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/49a6ef7b Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/49a6ef7b Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/49a6ef7b Branch: refs/heads/master Commit: 49a6ef7b7ba0e75b23c33cde434ee5e7c91bba14 Parents: fab1caf Author: Alex Heneveld <[email protected]> Authored: Wed May 6 15:00:39 2015 +0100 Committer: Alex Heneveld <[email protected]> Committed: Fri May 8 18:22:23 2015 +0100 ---------------------------------------------------------------------- docs/guide/ops/catalog/index.md | 15 +++++++ docs/guide/ops/install-on-server.md | 23 ++++------- docs/guide/start/blueprints.md | 13 +++---- docs/guide/start/catalog.xml | 22 ----------- pom.xml | 5 +-- .../entity/brooklynnode/BrooklynNode.java | 6 +++ .../main/resources/brooklyn/default.catalog.bom | 4 ++ usage/dist/pom.xml | 10 +++++ .../main/dist/conf/brooklyn/default.catalog.bom | 41 ++++++++++++++++++++ usage/dist/src/main/dist/conf/catalog.xml | 37 ------------------ usage/dist/src/main/dist/conf/logback.xml | 18 --------- 11 files changed, 91 insertions(+), 103 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/docs/guide/ops/catalog/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/catalog/index.md b/docs/guide/ops/catalog/index.md index dcedcd8..7cb0e84 100644 --- a/docs/guide/ops/catalog/index.md +++ b/docs/guide/ops/catalog/index.md @@ -8,6 +8,8 @@ children: - { section: Adding to the Catalog, title: Adding and Deleting } - { section: Templates and the Add-Application Wizard, title: Templates } - { section: Versioning } +- { section: CLI Options } + --- Brooklyn provides a **catalog**, which is a persisted collection of versioned blueprints and other resources. @@ -289,6 +291,19 @@ When referencing a blueprint, if a version number is not specified the latest non-snapshot version will be loaded when an entity is instantiated. +### CLI Options + +The `brooklyn` CLI includes several commands for working with the catalog. + +* `--catalogAdd <file.bom>` will add the catalog items in the `bom` file +* `--catalogReset` will reset the catalog to the initial state + (based on `brooklyn/default.catalog.bom` on the classpath, by default in a dist in the `conf/` directory) +* `--catalogInitial <file.bom>` will set the catalog items to use on first run, + on a catalog reset, or if persistence is off + +If [persistence](../persistence/) is enabled, catalog additions will remain between runs. +For more information on these commands, run `brooklyn help launch`. + <!-- TODO: make test cases from the code snippets here, and when building the docs assert that they match test cases http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/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 index d4711db..6c3455f 100644 --- a/docs/guide/ops/install-on-server.md +++ b/docs/guide/ops/install-on-server.md @@ -11,7 +11,7 @@ Here we present two *alternatives* to install Brooklyn: - [Manual installation](#manual) -## <a id="script"></a> Running the installation script +## <a id="script"></a> Running the Installation Script There is a simple bash script available to help with the installation process. @@ -32,16 +32,16 @@ $ ./brooklyn-install.sh -s -r <your-server-ip> {% endhighlight %} -## <a id="manual"></a> Manual installation +## <a id="manual"></a> Manual Installation 1. [Set up the prerequisites](#prerequisites) 1. [Download Brooklyn](#download) 1. [Configuring brooklyn.properties](#configuring-properties) -1. [Configuring catalog.xml](#configuring-catalog) +1. [Configuring default.catalog.bom](#configuring-catalog) 1. [Test the installation](#confirm) -### <a id="prerequisites"></a>Set up the prerequisites +### <a id="prerequisites"></a>Set up the Prerequisites Before installing Apache Brooklyn, it is recommented to configure the host as follows. @@ -105,21 +105,14 @@ $ chmod 600 ~/.brooklyn/brooklyn.properties 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 catalog.xml +### <a id="configuring-catalog"></a>Configuring the Catalog By default Brooklyn loads the catalog of available application components and services from -`~/.brooklyn/catalog.xml`. - -{% highlight bash %} -$ wget -O ~/.brooklyn/catalog.xml {{site.url_root}}{{site.path.website}}/quickstart/catalog.xml -{% endhighlight %} - -The `catalog.xml` is the application blueprint catalog. The above example file contains some blueprints which will be automatically downloaded from the web if you run them. - -You may need to edit `~/.brooklyn/catalog.xml` to update links to any resources for download. +`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 +### <a id="confirm"></a>Confirm Installation We can do a quick test drive by launching Brooklyn: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/docs/guide/start/blueprints.md ---------------------------------------------------------------------- diff --git a/docs/guide/start/blueprints.md b/docs/guide/start/blueprints.md index 9986178..5966b77 100644 --- a/docs/guide/start/blueprints.md +++ b/docs/guide/start/blueprints.md @@ -45,17 +45,14 @@ application. Your application will be shown as "Starting" on the web console's f Instead of pasting the YAML blueprint each time, this blueprint can be [added to the catalog](../ops/catalog/). -Or, even easier, you can download a sample [catalog.xml](catalog.xml). -Install this to your `~/.brooklyn/` folder and relaunch Brooklyn -(navigating to the "Help" tab in order to shutdown Brooklyn *and* the application you launched in the previous step). - -Now when the web console is re-opened, the catalog contains our blueprints. -Select the "Demo Web Cluster with DB" and click "Next". +With this YAML blueprint added, including the location, the Add Application dialog will offer +the "Demo Web Cluster with DB" as a template. [](images/add-application-catalog-web-cluster-with-db-large.png) -Select the location to use, give your application a name, and then click "Finish". - +<!-- TODO: more detail for adding to catalog? but wait for persistence to be the default, + rather than extensively document default.catalog.bom. + also need to include instructions on stopping (currently in help, including stopping apps) --> ## Next http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/docs/guide/start/catalog.xml ---------------------------------------------------------------------- diff --git a/docs/guide/start/catalog.xml b/docs/guide/start/catalog.xml deleted file mode 100644 index 6cff554..0000000 --- a/docs/guide/start/catalog.xml +++ /dev/null @@ -1,22 +0,0 @@ -<catalog> - <name>Brooklyn Demos</name> - - - <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB"> - <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description> - <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl> - </template> - - <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB"> - <description>Deploys a demonstration web application to JBoss clusters around the world</description> - <iconUrl>http://downloads.cloudsoftcorp.com/brooklyn/catalog/logos/JBoss_by_Red_Hat.png</iconUrl> - </template> - - <classpath> - <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION --> - <entry>https://oss.sonatype.org/service/local/artifact/maven/redirect?r=releases&g=io.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION --> - </classpath> - - -</catalog> - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 962bc30..e887422 100644 --- a/pom.xml +++ b/pom.xml @@ -1005,10 +1005,9 @@ <artifactId>apache-rat-plugin</artifactId> <configuration> <excludes combine.children="append"> - <!-- - Excluding sandbox because not part of distribution: not in tgz, and not uploaded to maven-central. - --> + <!-- Exclude sandbox because not part of distribution: not in tgz, and not uploaded to maven-central --> <exclude>sandbox/**</exclude> + <!-- Exclude netbeans config files (not part of the project, but often on users' drives --> <exclude>**/nbactions.xml</exclude> <exclude>**/nb-configuration.xml</exclude> </excludes> http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/software/base/src/main/java/brooklyn/entity/brooklynnode/BrooklynNode.java ---------------------------------------------------------------------- diff --git a/software/base/src/main/java/brooklyn/entity/brooklynnode/BrooklynNode.java b/software/base/src/main/java/brooklyn/entity/brooklynnode/BrooklynNode.java index 20626f9..0a95327 100644 --- a/software/base/src/main/java/brooklyn/entity/brooklynnode/BrooklynNode.java +++ b/software/base/src/main/java/brooklyn/entity/brooklynnode/BrooklynNode.java @@ -171,14 +171,20 @@ public interface BrooklynNode extends SoftwareProcess, UsesJava { "brooklynnode.brooklynproperties.local.contents", "Contents for the launch-specific brooklyn properties file", null); // For use in testing primarily + /** @deprecated since 0.7.0; TODO this should support BOM files */ + @Deprecated @SetFromFlag("brooklynCatalogRemotePath") public static final ConfigKey<String> BROOKLYN_CATALOG_REMOTE_PATH = ConfigKeys.newStringConfigKey( "brooklynnode.brooklyncatalog.remotepath", "Remote path for the brooklyn catalog.xml file to be uploaded", "${HOME}/.brooklyn/catalog.xml"); + /** @deprecated since 0.7.0; TODO this should support BOM files */ + @Deprecated @SetFromFlag("brooklynCatalogUri") public static final ConfigKey<String> BROOKLYN_CATALOG_URI = ConfigKeys.newStringConfigKey( "brooklynnode.brooklyncatalog.uri", "URI for the brooklyn catalog.xml file (uploaded to ~/.brooklyn/catalog.xml)", null); + /** @deprecated since 0.7.0; TODO this should support BOM files */ + @Deprecated @SetFromFlag("brooklynCatalogContents") public static final ConfigKey<String> BROOKLYN_CATALOG_CONTENTS = ConfigKeys.newStringConfigKey( "brooklynnode.brooklyncatalog.contents", "Contents for the brooklyn catalog.xml file (uploaded to ~/.brooklyn/catalog.xml)", null); http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/usage/cli/src/main/resources/brooklyn/default.catalog.bom ---------------------------------------------------------------------- diff --git a/usage/cli/src/main/resources/brooklyn/default.catalog.bom b/usage/cli/src/main/resources/brooklyn/default.catalog.bom index cddb832..0db2f20 100644 --- a/usage/cli/src/main/resources/brooklyn/default.catalog.bom +++ b/usage/cli/src/main/resources/brooklyn/default.catalog.bom @@ -15,5 +15,9 @@ # specific language governing permissions and limitations # under the License. # + +# this catalog bom simply scans. +# in a dist a default.catalog.bom from the conf/ dir takes precedence. + brooklyn.catalog: scanJavaAnnotations: true http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/usage/dist/pom.xml ---------------------------------------------------------------------- diff --git a/usage/dist/pom.xml b/usage/dist/pom.xml index 3b7f1e6..ff0db95 100644 --- a/usage/dist/pom.xml +++ b/usage/dist/pom.xml @@ -63,6 +63,16 @@ <build> <plugins> <plugin> + <groupId>org.apache.rat</groupId> + <artifactId>apache-rat-plugin</artifactId> + <configuration> + <excludes combine.children="append"> + <!-- Exclude sample config files because they are illustrative, intended for changing --> + <exclude>src/main/dist/conf/**</exclude> + </excludes> + </configuration> + </plugin> + <plugin> <artifactId>maven-assembly-plugin</artifactId> <executions> <execution> http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/usage/dist/src/main/dist/conf/brooklyn/default.catalog.bom ---------------------------------------------------------------------- diff --git a/usage/dist/src/main/dist/conf/brooklyn/default.catalog.bom b/usage/dist/src/main/dist/conf/brooklyn/default.catalog.bom new file mode 100644 index 0000000..42672ae --- /dev/null +++ b/usage/dist/src/main/dist/conf/brooklyn/default.catalog.bom @@ -0,0 +1,41 @@ + +# this catalog bom is an illustration supplying a few useful sample items +# and templates to get started using Brooklyn + +brooklyn.catalog: + version: 0.7.0-SNAPSHOT # BROOKLYN_VERSION + items: + + # load everything in the classpath with a @Catalog annotation + - scanJavaAnnotations: true + + - id: server + description: | + Provision a server, with customizable provisioning.properties and credentials installed, + but no other special software process or scripts executed. + item: + type: brooklyn.entity.basic.EmptySoftwareProcess + name: Server + + - id: server-template + itemType: template + name: Server Template + description: | + Sample YAML to provision a server in a cloud with illustrative VM properties + item: + name: My App with a single VM + services: + - type: server + name: My VM + location: + jclouds:aws-ec2: + identity: <REPLACE> + credential: <REPLACE> + region: eu-west-1 + # we want Ubuntu, with a lot of RAM + osFamily: ubuntu + minRam: 8gb + # set up this user and password (default is to authorize a public key) + user: sample + password: s4mpl3 + http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/usage/dist/src/main/dist/conf/catalog.xml ---------------------------------------------------------------------- diff --git a/usage/dist/src/main/dist/conf/catalog.xml b/usage/dist/src/main/dist/conf/catalog.xml deleted file mode 100644 index 343e1da..0000000 --- a/usage/dist/src/main/dist/conf/catalog.xml +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - 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. ---> -<catalog> - <name>Brooklyn Demos</name> - - <template type="brooklyn.demo.WebClusterDatabaseExample" name="Demo Web Cluster with DB"> - <description>Deploys a demonstration web application to a managed JBoss cluster with elasticity, persisting to a MySQL</description> - <iconUrl>http://releng3.cloudsoftcorp.com/downloads/brooklyn/img/JBoss_by_Red_Hat.png</iconUrl> - </template> - <template type="brooklyn.demo.GlobalWebFabricExample" name="Demo GeoDNS Web Fabric DB"> - <description>Deploys a demonstration web application to JBoss clusters around the world</description> - <iconUrl>http://releng3.cloudsoftcorp.com/downloads/brooklyn/img/JBoss_by_Red_Hat.png</iconUrl> - </template> - - <classpath> - <entry>https://repository.apache.org/service/local/artifact/maven/redirect?r=releases&g=org.apache.brooklyn.example&a=brooklyn-example-simple-web-cluster&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION --> - <entry>https://repository.apache.org/service/local/artifact/maven/redirect?r=releases&g=org.apache.brooklyn.example&a=brooklyn-example-global-web-fabric&v=0.7.0-SNAPSHOT&e=jar</entry> <!-- BROOKLYN_VERSION --> - </classpath> -</catalog> - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/49a6ef7b/usage/dist/src/main/dist/conf/logback.xml ---------------------------------------------------------------------- diff --git a/usage/dist/src/main/dist/conf/logback.xml b/usage/dist/src/main/dist/conf/logback.xml index 0224ac1..e70862c 100644 --- a/usage/dist/src/main/dist/conf/logback.xml +++ b/usage/dist/src/main/dist/conf/logback.xml @@ -1,22 +1,4 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- - 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. ---> <configuration> <!-- to supply custom logging, either change this file, supply your own logback-main.xml
