HOWTO Add Runtime Versions to Boosters

Introduction

Up to now all Boosters were subdivided according to "Missions" and “Runtimes”. But recently we’ve acquired to option to have the user choose between different versions of a Runtime. An example might be to choose between a community version of WildFly and it’s productized version.

The changes in the UI of the wizard aren’t very big. If the Booster supports various Runtime versions an extra drop down field will appear letting the user choose between the available options. Like this:

If the Booster doesn’t support Runtime versions everything will just work as before. (So if you don’t want Runtime versions for your Booster or you are not ready yet to make those changes then you don’t have to do anything)

Currently all Boosters must be registered in a "Booster Catalog", which is a folder tree with .yaml files. The following is an example of what that looks like right now:

The first folder level are the "Missions", while the second folder level is the “Runtimes” and in those second level folders are the .yaml files that define where the actual Boosters can be found. An example .yaml file might look like this:

source:
  git:
    url: https://github.com/snowdrop/spring-boot-circuit-breaker-booster
    ref: master

Where source/git/url is the name of the repository in Github where the Booster lives and source/git/ref is the branch or hash (commit reference) that should be used to check out the code. So far everything is the same.

Declaring versions

If you want to add runtime versions for a Booster then an additional folder level is needed to specify the version that are available for the given Mission / Runtime combination. An example might look like this:

Again, it’s not necessary to add runtime versions, if you don’t need them just do not add the third folder level. So in the above example the "crud / spring-boot" and “crud / vert.x” Boosters don’t have any runtime versions, but the “crud / wildfly-swarm” does. In this example it has two versions: “community” and “redhat”. The versions aren’t limited to these names nor are they limited to just two options, you can add any number of versions with any name you like.

Using the same repository / branch

When your Runtime versions all use the same code base (there’s just one repository with a single branch being used) then you can use Maven profiles to perform different kinds of builds. If you’d define a profile for each version your users can specify the one the want to build/run by specifying the relevant version on the command line, eg:

mvn clean install -Ptheruntimeversion

But things get a little more interesting when you make sure that the different profile ids match up with the version ids you defined in the catalog. What the launcher does in that case is add a default activation to the relevant profile that matches the version the user selected in the wizard UI of the launcher. For example if the user launched their project selecting the "product" runtime version the section in their copy of the booster’s pom.xml file might look somewhat like this:

<profiles>
    <profile>
        <id>community</id>
         …
    </profile>
    <profile>
        <id>product</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
         …
    </profile>
     … 
 </profiles>

The launcher automatically added an "true" tag to the profile’s section (creating that section if it doesn’t already exist).

NB: If for some reason you can’t or don’t want to use the version id to select the required Maven profile then you can use a special property, that can be added to a booster’s `metadata` section in the Booster Catalog, called `buildProfile`. Imagine for example a .yaml file for a productized Spring Boot circuit breaker booster: source: git: url: https://github.com/snowdrop/product-spring-boot-circuit-breaker-booster ref: master metadata: buildProfile: whatever It might have a version id of “product” so in that case the launcher would normally look for a profile with the same “product” id to activate. But using this option the launcher will now look for a profile with the id “whatever” instead.

Using separate repositories / branches

If on the other hand you want to maintain your Runtime versions in different branches of the same repository, or even in different repositories then you can do so as well by simply adjusting the information in each .yaml file in the catalog. For example the "crud / wildfly-swarm / community" version .yaml file might look like this:

source:
  git:
    url: https://github.com/openshiftio/wfswarm-rest-http-crud
    ref: community-version

While the "crud / wildfly-swarm / product" version .yaml file might look like this:

source:
  git:
    url: https://github.com/openshiftio/wfswarm-rest-http-crud
    ref: product-version

NB: The process of selecting profiles as described above still happen, even in this case of having separate repositories / branches. If that’s undesirable just make sure the names between versions and profiles don’t match up.

NB2: if much or even all of the code in your booster is the same between Versions you might want to consider using the build profiles described above.

Human-readable names

Like Missions and Runtimes, Versions also have an "id", which like the others is the name of the folder in the catalog. So in the above example that would be “community” and “redhat”. But, the same as for Missions and Runtimes, that is not the name we want to appear in the wizard.

For the Missions and the Runtimes we have the "metadata.json" file to define the mapping between their “id” (the folder name) and the name meant for human consumption. But unfortunately we can’t use the same file for Versions because they are not fixed, they can be different for each Booster.

For Versions the mapping is defined in the Booster’s descriptor itself. So, following the examples above, the contents of the “crud/wildfly-swarm/community/booster.yaml” file might look like this:

name: HTTP CRUD - Wildfly Swarm Product
description: My very own booster
source:
  git:
    url: https://github.com/openshiftio/wfswarm-rest-http-crud
    ref: community-version
metadata:
   version:
     name: Community Runtime

With the metadata/version being properly defined in all the Booster's versions the “Runtime Version” dropdown in the Launcher would now look something like this:

    Community Runtime
    Productized Runtime

Instead of the following without it:

    community
    redhat