HOWTO Create a Booster Catalog (Generic)

Booster Catalog

A Booster Catalog is a repository that contains an index pointing to a set of known example applications, called Boosters, conforming to the minimal set of requirements necessary to be served by the Fabric8 Launcher.

Catalog Structure

The repository is simply a set of booster.yaml files describing each of the Booster applications. You can put those files in the root of the repository or in any directory structure you like.

Booster Descriptor

For each Booster, create a YAML file named booster.yaml (it can have other names, but it should at least end with booster.yaml). In it should be the following information:

Name	Description
name	The name of the Booster
description	(Optional) A longer description for the Booster
ignore	(Optional) Set this to "true" to have the Booster be ignored
source/git/url	The Git repository location URL
source/git/ref	The Git reference (tag/branch/SHA1)
metadata	A user-defined section where you are free to put any information relevant to your particular use-case

Booster Environments

One of the things you will encounter when developing new Boosters or while updating existing ones is that you want to be able to specify different values in a Booster's descriptor depending on the environment the Booster is being used in. For example you might want to use the very latest version of a Booster in development but a very specific (tested and passing all QA requirements) in production. For this we introduced "environments".

An environment is a special section of a Booster's descriptor .yaml file that will only be applied when its name matches that set by the server environment it's running on. The data inside an environment section is applied as an "overlay" on top of the root of the document, so values in it can override the default values specified in the root document. An example of a Booster descriptor with environments is this:

source:
  git:
    url: https://github.com/openshiftio-vertx-boosters/vertx-http-booster
    ref: master
metadata:
  version:
    name: 3.5.0.Final (Community)
environment:
  staging:
    source:
      git:
        ref: v19
  production:
    source:
      git:
        ref: v17
    metadata:
      version:
        name: 3.4.2.Final (Community)

What you see here is that the root document contains these values:

source:
  git:
    url: https://github.com/openshiftio-vertx-boosters/vertx-http-booster
    ref: master
metadata:
  version:
    name: 3.5.0.Final (Community)

And that's exactly what will be used if the current environment doesn't match any of the ones defined in the descriptor. But the descriptor also defines two environments:

environment:
  staging:
    ...
  production:
    ...

So what will happen if the current environment is set to "production", for example, is that the values inside that section:

environment:
  production:
    source:
      git:
        ref: v17
    metadata:
      version:
        name: 3.4.2.Final (Community)

will be applied on top of the root document, resulting in the following resulting Booster descriptor:

source:
  git:
    url: https://github.com/openshiftio-vertx-boosters/vertx-http-booster
    ref: v17
metadata:
  version:
    name: 3.4.2.Final (Community)

As you can see the source/git/ref value has been changed from master to v17 while the metadata/version/name has changed too.

Common Values

Often separate Boosters will share the same information. For example both the community and officially supported versions of a Booster will most likely have the same name and description. To avoid duplication you can put those items in a common.yaml file instead. When the Launcher encounters a common.yaml file in the catalog all Boosters in the same folder and in all sub folders will be based on the information found in that file. The file can contain the exact same information as a booster.yaml file. Any information in the booster.yaml files will merge with or overwrite the information found in the common.yaml file. Application of common.yaml files is recursive, so common.yaml files in sub folders will overwrite values found in common.yaml files in parent folders.

Example

A small example of what a repository could look like:

With health-check/spring-boot/common.yaml containing:

name: Spring Boot Health Check Example
description: A description...

and health-check/spring-boot/community/booster.yaml containing:

source:
  git:
    url: https://github.com/snowdrop/spring-boot-health-check-booster
    ref: master
metadata:
  version:
    name: 1.5.8.RELEASE (Community)

Those two combined will result in a Booster descriptor with their combined contents:

name: Spring Boot Health Check Example
description: A description...
source:
  git:
    url: https://github.com/snowdrop/spring-boot-health-check-booster
    ref: master
metadata:
  version:
    name: 1.5.8.RELEASE (Community)