You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by aledsage <gi...@git.apache.org> on 2015/01/16 19:28:13 UTC
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
GitHub user aledsage opened a pull request:
https://github.com/apache/incubator-brooklyn/pull/456
Docs: separate ops/launching page; adds cloud-explorer; updated catalog description
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/aledsage/incubator-brooklyn docs/cli
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-brooklyn/pull/456.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #456
----
commit aed2f1c8ae96e44d9a65ee8e994a28e494794a35
Author: Aled Sage <al...@gmail.com>
Date: 2015-01-15T16:51:22Z
docs: separate “launching” and “runtime management”
commit b36436b30b69d052b9e7c5c5e0cee2ebbb3f5537
Author: Aled Sage <al...@gmail.com>
Date: 2015-01-15T17:01:55Z
docs: add cloud-explorer CLI
commit 1ca11bd3edbf84c25b0d1b16989ff0024f8c1ef9
Author: Aled Sage <al...@gmail.com>
Date: 2015-01-16T13:44:34Z
docs: fix REST api description
commit f008e27a913006f1d0a077308f64d6a7463e0862
Author: Aled Sage <al...@gmail.com>
Date: 2015-01-16T17:37:18Z
docs: move catalog.md from yaml to ops section
- renaming file from catalog-maintenance.md to catalog/index.md
commit 1f48765fc3e868adcf541a1af0dc8f4f1cb8f792
Author: Aled Sage <al...@gmail.com>
Date: 2015-01-16T18:22:58Z
docs: update catalog description
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161863
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+
+
+### Deleting from the Catalog
+
+You can delete a versioned item from the catalog using the REST API. For example, to delete
+the item with id `org.example.MySQL` and version `1.0`:
+
+{% highlight bash %}
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
+rebinding the catalog item is used to reconstruct the entity.
+
+
+### Versioning
+
+Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
+For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+
+If you attempt to deploy the same version of a catalog item a second time, you will receive an
+error stating `Updating existing catalog entries is forbidden`.
+To update the blueprint, you will need to change the version number in your yaml file and then
+POST the new YAML file.
--- End diff --
Inconsistent capitalisation of "yaml"/"YAML".
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161664
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
--- End diff --
Is it true that the icon cannot be supplied by any of the OSGi bundles in the `libraries` list? If so this seems to be a weakness in Brooklyn...
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23193697
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
--- End diff --
+1 @robertgmoss commented on this elsewhere btw
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161753
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
--- End diff --
Could you also describe how to do this in general terms? Giving a `curl` example is fine but I think it is more important that a non-application-specific description is given first.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23193758
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+
+
+### Deleting from the Catalog
+
+You can delete a versioned item from the catalog using the REST API. For example, to delete
+the item with id `org.example.MySQL` and version `1.0`:
+
+{% highlight bash %}
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
+rebinding the catalog item is used to reconstruct the entity.
--- End diff --
agree this would be nice, along with `force` flag to force deletion even if in use ("because i know what i'm doing")
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#issuecomment-70576323
+1 @rdowner - this is an improvement. have merge. i'll make many of the other suggestions in #458.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23193981
--- Diff: docs/guide/ops/launching/index.md ---
@@ -0,0 +1,143 @@
+---
+title: Launching Brooklyn
+layout: website-normal
+---
+
+There are several ways to launch applications with brooklyn, and useful configuration options,
+as well as a debug-view web console.
+
+This chapter describes how to launch brooklyn.
+
+
+Startup Configuration
+---------------------
+
+brooklyn can read configuration from a variety of places:
+
+* the file ``~/.brooklyn/brooklyn.properties``
+* ``-D`` defines on the brooklyn (java) command-line
+* shell environment variables
--- End diff --
double back-tick is old markdown format. behaviour is the same, i think.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23193634
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
--- End diff --
that would mean loading all osgi bundles simply to be able to render the catalog
have added text to this effect
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161948
--- Diff: docs/guide/ops/launching/index.md ---
@@ -0,0 +1,143 @@
+---
+title: Launching Brooklyn
+layout: website-normal
+---
+
+There are several ways to launch applications with brooklyn, and useful configuration options,
+as well as a debug-view web console.
+
+This chapter describes how to launch brooklyn.
+
+
+Startup Configuration
+---------------------
+
+brooklyn can read configuration from a variety of places:
+
+* the file ``~/.brooklyn/brooklyn.properties``
+* ``-D`` defines on the brooklyn (java) command-line
+* shell environment variables
--- End diff --
Does the double-backtick have a different meaning to the single-backtick we normally use in Markdown?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161609
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
--- End diff --
s/section/line ? (and below too)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-brooklyn/pull/456
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#issuecomment-70500185
A few comments - however I didn't see until the end that some of these things were effectively file-moves but hadn't been recorded by Git as such, so you get me nitpicking at the contents of files you simply renamed :smile: Some of my comments are also perhaps comments about Brooklyn issues - they are documented here but might be better off being fixed in Brooklyn. And finally the "runtime management" page links to some horrifically outdated screenshots of Brooklyn.
But almost all of the above existed in the document before so are not regressions as such. In general I think this is good to merge, but please coordinate with @ahgittin before updating the public website as I believe he has a PR that is to be imminently merged.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23161848
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+
+
+### Deleting from the Catalog
+
+You can delete a versioned item from the catalog using the REST API. For example, to delete
+the item with id `org.example.MySQL` and version `1.0`:
+
+{% highlight bash %}
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
+rebinding the catalog item is used to reconstruct the entity.
--- End diff --
Should Brooklyn refuse the `DELETE` if this is the case?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] incubator-brooklyn pull request: Docs: separate ops/launching page...
Posted by ahgittin <gi...@git.apache.org>.
Github user ahgittin commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/456#discussion_r23193769
--- Diff: docs/guide/ops/catalog/index.md ---
@@ -0,0 +1,163 @@
+---
+title: Catalog
+layout: website-normal
+---
+
+Brooklyn has a 'catalog', which is a collection of versioned blueprints.
+These can be deployed directly or referenced by other blueprints.
+Blueprints in the catalog can be deployed via the Brooklyn REST API, or from
+the web-console's 'Catalog' section of the 'Create Application' dialog box.
+
+
+<!--
+TODO: Clean up confusion in terminology between Catalog item and Blueprint (and Java blueprint?)?
+-->
+
+### Catalog items
+
+An item to be added to the catalog is defined in YAML. This looks like any other
+YAML blueprint, but also has a `brooklyn.catalog` section giving appropriate metadata.
+
+An example is shown below.
+
+{% highlight yaml %}
+brooklyn.catalog:
+ id: org.example.MySQL
+ version: 1.0
+ iconUrl: classpath://mysql.png
+ description: MySql is an open source relational database management system (RDBMS)
+ libraries:
+ - url: http://example.com/path/to/my-dependency-1.2.3.jar
+ - url: http://example.com/path/to/my-other-dependency-4.5.6.jar
+
+services:
+- type: brooklyn.entity.database.mysql.MySqlNode
+{% endhighlight %}
+
+To explain the `brooklyn.catalog` section:
+
+- The `id: MySQL` section specifies a unique ID used by Brooklyn to identify the catalog item.
+ Other blueprints can reference the catalog item using this id.
+- The `version: 1.0` section provides a unique version for the *blueprint*. NOTE: This is *not* the version of the software
+being installed (in this case MySQL).
+- The `iconUrl: classpath://...` is an optional, but recommended, section that allows you to provide the URL of a graphic to be
+displayed in the 'Add Application' dialog alongside the blueprint name. If using a URL of the form `classpath://...`, then
+the image should be on Brooklyn's classpath (e.g. in the `conf` folder of the Brooklyn distro).
+- The `description: ...` section allows you to give a free-format description of the blueprint, which is displayed in the
+'Add Application' dialog.
+
+The `libraries` section references OSGi bundles required for the blueprint. It can be omitted if everything
+required by the blueprint is already on the Brooklyn classpath. The URLs should be to stable OSGi bundles -
+if the bundle at this URL changes then this could impact applications if the Brooklyn server is restarted
+or fails over to a standby node.
+
+
+To reference a catalog item in another blueprint, simply use its id and optionally its version number.
+For example:
+
+{% highlight yaml %}
+services:
+- type: org.example.MySQL:1.0
+{% endhighlight %}
+
+
+### Adding to the Catalog
+
+To add a catalog item to the catalog, post the YAML file to Brooklyn's REST API by using the `curl` command as
+follows (substituting your own usename:password, URL and file path):
+
+{% highlight bash %}
+curl -u admin:password http://127.0.0.1:8081/v1/catalog --data-binary @/path/to/mysql-catalog.yaml
+{% endhighlight %}
+
+
+
+### Deleting from the Catalog
+
+You can delete a versioned item from the catalog using the REST API. For example, to delete
+the item with id `org.example.MySQL` and version `1.0`:
+
+{% highlight bash %}
+curl -u admin:password -X DELETE http://127.0.0.1:8081/v1/catalog/entities/MySQL/1.0
+{% endhighlight %}
+
+**Note** Catalog items should not be deleted if there are running apps which were created using the same item. During
+rebinding the catalog item is used to reconstruct the entity.
+
+
+### Versioning
+
+Version numbers follow the OSGi convention. This can have a major, minor, micro and qualifier part.
+For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+
+If you attempt to deploy the same version of a catalog item a second time, you will receive an
+error stating `Updating existing catalog entries is forbidden`.
+To update the blueprint, you will need to change the version number in your yaml file and then
+POST the new YAML file.
--- End diff --
and "post" / "POST" -- have fixed both
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---