launcher-creator-backend

This is the engine to perform the actual code generation. It has command line tools that can generate code locally and a REST service that can either return a ZIP file or pass the generated code to the Launcher Backend for publishing on GitHub and OpenShift.

The fundamental design idea for this engine is the concept of Capabilities and Generators. Things are described in more detail below but basically it comes down to Generators creating the very simple and basic pieces of a project and Capabilites being like the director that groups and manages them to create a final composition. Generators just know to do one thing, while a Capability holds all the intelligence and knowledge on how to put them together to create something useful.

The process is simple: you start with an empty directory and apply capabilities to it using the commands described below.

Usage

For the first time you'll need Yarn to install all the dependencies. Run the following command in the root of a clone of this repository:

$ yarn install

To get a list of the capabilities you can apply to your project run:

$ yarn -s apply capabilities

To apply a specific capability you need its name and which properties to pass. Use the --help option to find out what properties are supported/required by the Capability, for example:

$ yarn -s apply database --help

To actually apply the Capability to the project pass all the required arguments and properties, for example:

$ yarn -s apply path/to/project "my-app" welcome

But for most capabilities need to specify a "runtime". You can get the list of runtimes by running:

$ yarn -s apply runtimes

Then you pick the one you want and you pass it on the command line, eg:

$ yarn -s apply path/to/project --runtime vertx "my-app" rest

Some capabilities can also take extra properties that change their default behaviour, eg:

$ yarn -s apply path/to/project --runtime vertx "my-app" database '{ "databaseType": "mysql" }'

After the application has been generated it can be deployed in the currently active project on OpenShift by going into the project folder and running:

$ ./gap deploy

Now the only thing that is left to do is push the project's code to OpenShift to be run. There are two ways of doing that, one is by first building the project yourself locally and pushing the resulting binary, like this (assuming a Maven project):

$ mvn clean install
$ ./gap push --binary

In most cases you can leave out the --binary flag because that's the default if a binary is available. In case you want to push the sources and have the project be built on OpenShift you can do the following:

$ ./gap push --source

This is also the default when no binary is available and you omit the --source flag.

Stages

Apply Stage - This is where the Generators, executed by the Capabilities, can make changes to the user's project and add their own Resources to the final list of OpenShift/K8s Resources that will be created in the user's OpenShift environment. In this stage a Generator can copy (template) files from the Generators to the user's project, generate files or change already existing files. This is done only once when the user applies the Capability to their project.
Deploy Stage - This is where the result from a previous Apply Stage is taken and installed in an OpenShift instance. Generators and Capabilities don't do anything in this stage (although this might be revisted in the future).

Folder structure

lib
- generators - All Generator modules are found in this folder.
- capabilities - All Capability modules are found in this folder.
- core - This folder contains core modules that provide support for the capabilites and the generators.
  - deploy - Module that can execute Capabilites, manages the deployment.json descriptor file, can generate a project's Resource file and can deploy it to OpenShift.
  - info - Module that deals with input validation mostly.
  - maven - Module with maven-specific utilities, like merging pom.xml files.
  - resources - Module that deals with OpenShift/K8s Resource lists.
  - utils - Miscelleaneous utility functions.

Generators

Generators are modules that make changes to a user's project. Each module generally only makes a very specific and limited set of changes, using the UNIX philosophy of "Do one thing and do it well".

For example a Generator "mySQL" might create the necessary OpenShift/K8s Resources to set up a database service on OpenShift. Another one might create the code to connect to a database from Node.js.

Try not to make a Generator do too much, think of who would be maintaining the module for example. If a Generator could generate the code for all the available languages it would soon become pretty complex and all the different people or teams that have the necessary expertise for their particular language would have to collaborate on that one module. Better to create one module for each language. If there are many common elements, for example they use a lot of the same supporting non-code files, consider splitting those out into a different module.

So make Generators simple, move the complexity to the Capabilities.

Capabilities

Capabilities are modules that bundle one or more generators to add a set of features to a user's project that together implement a useful and fleshed-out use-case. Generators do, while Capabilities manage.

For example, a "Database" Capability might call on a Generator that would create a mySQL database service, while using another to create the Secret that will store the database's connection information. Yet another Generator would create the Java code based on the Vert.x framework and copy that to the user's project. The choice of database (mySQL, PostgreSQL, etc) and code language and framework (Node.js, Vert.x, Spring Boot, etc) could be options that the user can pass to the Capability. In that aspect a Capability can be as complex as you want it to be.

Development

To make sure that any changes you make are properly propagated to all modules you might have to run the folowing command:

$ yarn install --force

For information on how to develop your own Generators and Capabilities see the Contributing page in the Wiki.

Deploy on OpenShift

$ oc new-app \
     quintesse/node-java-oc-odo~https://github.com/fabric8-launcher/launcher-creator-backend \
     --name launcher-creator-backend \
     -e LAUNCHER_BACKEND_URL=https://forge.api.prod-preview.openshift.io/api

Run Integration Tests

Simply run the integration test script like this:

$ yarn ittest

You can also run the integration tests for a subset of runtimes using the --runtimes parameter:

$ yarn ittest --runtimes=thorntail,nodejs