This guide walks you through the process of installing the Fabric8 Launcher tool on an OpenShift cluster. To test the launcher tool locally on your machine you can use:

1. How the Fabric8 Launcher tool works

The Fabric8 Launcher tool runs on OpenShift and lets you create functional example applications. The Fabric8 Launcher tool walks you through:

  • choosing the example application you want to generate,

  • choosing the runtime you want to use, and

  • choosing how you want to build and execute the example application.

The Fabric8 Launcher tool uses your choices to generate a custom project, called an example application, and either launches it directly to the same OpenShift instance, or provides a downloadable ZIP version of the project.

2. Installing Minishift

To test the Fabric8 Launcher tool on your local machine, you can use either Minishift or Red Hat Container Development Kit.

  1. Follow the instructions for installing Minishift:

    The steps for installing Minishift vary by platform.
  2. Verify you have the Minishift installed and configured:

    $ minishift version
  3. Start and stop Minishift:

    $ minishift start
    $ minishift stop
    Stopping local OpenShift cluster...
    Cluster stopped.
  4. Determine the command to add the correct version of the oc binary to your path and run the command:

    Example Result of oc-env on Red Hat Container Development Kit
    $ minishift oc-env
    export PATH="/Users/john/.minishift/cache/oc/v3.5.5.8:$PATH"
    # Run this command to configure your shell:
    # eval $(minishift oc-env)
    $ eval $(minishift oc-env)
    You must have the oc binary installed and it must match the version of Minishift that you are using.

3. Starting and configuring Minishift for the Fabric8 Launcher tool

This chapter contains instructions for starting the Minishift and configuring it to execute the Fabric8 Launcher tool.

Starting your Minishift can trigger a download of large virtual machines or Linux container images. This can take a long time. Subsequent startups are expected to be shorter if the virtual machines and Linux container images remain cached.

Because Minishift is intended for development purposes, it uses HTTPS for the web console and only provides a self-signed certificate. If your browser prevents you from accessing the page due to an SSL error, you must allow your browser to bypass SSL security policies for the Minishift URL to use it. The screenshot below shows the warning message in the Google Chrome browser.

SSL warning
  1. Start Minishift with the default virtual machine driver:

    Depending on your operating system, virtual machine driver, and the number of example applications you run, the memory allocated Minishift or CDK can be insufficient. In this case, increase the memory allocation.
    $ minishift start --memory=4096
    OpenShift server started.
    The server is accessible via web console at:

    Alternatively, specify a virtual machine driver other than the default using the --vm-driver flag:

    $ minishift start --memory=4096 --vm-driver=virtualbox

    Depending on your system configuration, it is possible that you must manually specify an alternative virtual machine driver. You must have virtual machine software, such as VirtualBox, installed before you specify it.

    On macOS, the default virtual machine driver, xhyve, can be unreliable. If you experience issues, specifying VirtualBox is a reliable alternative.
  2. Open the Minishift Web console.

    $ minishift console

    Alternatively, use the URL provided in the log information.

  3. Log in using the developer username and an arbitrary password.

  4. Optionally, delete the preconfigured project:

    1. Next to the project name, click the three-dot menu icon.

    2. Select Delete Project.

      OpenShift Console Home

4. Creating a GitHub personal access token

To install the Fabric8 Launcher tool on a Minishift or CDK, you must provide the Fabric8 Launcher tool with a GitHub personal access token. This enables the Fabric8 Launcher tool to create example applications and save them as Git repositories in your GitHub namespace.

  1. Using a web browser, navigate to

  2. Select Generate new token.

  3. Add a token description, for example Fabric8 Launcher tool on a Minishift or CDK.

  4. Select the check boxes of the following parent scopes and all their children:

    • public_repo

    • read:org

    • admin:repo_hook

  5. Click Generate token.

  6. Save the hex code of the personal access token. You need this to complete the installation of the Fabric8 Launcher tool on your Minishift or CDK.

    This hex code is displayed only once and cannot be retrieved after you leave the page. If you lose the code, you will need to create a new personal access token to install the Fabric8 Launcher tool on a Minishift or CDK again.

5. Installing Fabric8 Launcher Tool

Install an instance of the Fabric8 Launcher tool, which enables you to test the functionality or make modifications to the service using a web interface.

5.1. Installing the Fabric8 Launcher tool using an operator

Set up an operator to install the Fabric8 Launcher tool on an OpenShift cluster. Configure OAuth2 authentication to enable multiple users to access the same instance of Fabric8 Launcher.

  • A GitHub account

  • Admin access to an OpenShift cluster

  • OpenShift cluster installed

  1. Assign the cluster-admin role to your user account on the OpenShift cluster.

    $ oc adm policy --as system:admin add-cluster-role-to-user cluster-admin USER_ACCOUNT_NAME
  2. Log in to your OpenShift cluster using your user account with cluster-admin credentials:

  3. Create a project to host the Launcher:

    $ oc new-project launcher-infra
  4. Register your Fabric8 Launcher instance with OAuth on GitHub. This enables multiple users to use the same instance by authenticating their GitHub user accounts against the the OAuth application that your Fabric8 Launcher instance is registered to.

    1. Log in to GitHub

    2. Create a new GitHub OAuth application.

      Use launcher as the application name.

    3. Use http://temporary as a temporary value for the Homepage URL and Authorization callback URL fields. You must replace these value with the Fabric8 Launcher frontend route URL when you obtain it.

    4. Click Register Application to confirm your settings to obtain the Client ID and Client Secret for your Fabric8 Launcher app.

    5. Create an OAuth secret for your Fabric8 Launcher instance using the Client ID and Client Secret.

      $ oc create secret generic launcher-oauth-github --from-literal=clientId=LAUNCHER_GITHUB_OAUTH_CLIENT_ID --from-literal=secret=LAUNCHER_GITHUB_OAUTH_CLIENT_SECRET
  5. Download and extract the ZIP file containing the operator and navigate to the directory containing the extracted resources.

    $ cd launcher-operator
  6. Create and deploy the application resources defined by the YAML templates in the /deploy subdirectory:

    $  oc create -R -f ./deploy

    Based on the templates, OpenShift automatically installs:

    • a custom resource definition for the Fabric8 Launcher app

    • a service account for the Launcher operator

    • a deployment of the Launcher operator

    • an access role definition for the Launcher operator

    • access role bindings for the Launcher operator

  7. OPTIONAL: Verify that the pod containing the deployment operator is running and that its state is indicated as READY.

    $  oc get pods -w
    NAME                                READY     STATUS       RESTARTS   AGE
    launcher-operator-fffff0000-abc12   1/1       Running      0          3m

    Press CTRL+Z to stop watching the pods.

  8. Edit the launcher_cr.yaml custom resource located in the example/ subdirectory. Use your OpenShift Console URL as the value of consoleUrl:

    kind: Launcher
      name: launcher
    # OpenShift Configuration
        apiUrl: https://openshift.default.svc.cluster.local
        consoleUrl: OPENSHIFT_WEB_CONSOLE_URL # Replace this value with the URL you use to access your OpenShift Web Console (for example: '').#
    # OAuth Configuration
        enabled: true
    # Omit the following items if you are not using a Keycloak server for authorization.
        keycloakUrl: KEYCLOAK_AUTH_URL # Replace this value with the URL of the Keycloak server instance that you use for authorization.#
        keycloakRealm: launcher
        keycloakClientId: launcher
        - id: GitHub
  9. Create the application components of the Fabric8 Launcher tool defined in the example/launcher_cr.yaml template to start the deployment.

    $ oc create -f example/launcher_cr.yaml
  10. Wait until the pod containing the Fabric8 Launcher application is in a READY state:

    $ oc get pods -w
    NAME                                READY     STATUS              RESTARTS   AGE
    launcher-application-1-aaaaa        1/1       Running             0           8s

    Press CTRL+Z to stop watching the pods.

  11. Obtain the frontend URL of your Fabric8 Launcher instance:

    $ oc get route launcher --template={{}}
  12. Create an OAuth client instance in your launcher-operator project. Ensure that you provide the OpenShift secret and frontend URL values that you obtained earlier:

    $ oc create -f <(echo '
      kind: OAuthClient
        name: launcher
      secret: #YOUR_LAUNCHER_OPENSHIFT_SECRET # Replace this with the secret you generated using your OAuth Client ID and Client Secret
        - "http://YOUR_LAUNCHER_FRONTEND_URL" # Replace this with the fronted route URL of your Fabric8 Launcher instance
      grantMethod: prompt
  13. Update the values of the Homepage URL and Authorization callback URL fields in your Fabric8 Launcher OAuth app configuration settings on GitHub to the value of your launcher frontend route URL.

  14. Navigate to the frontend route URL using a web browser to start using Fabric8 Launcher.

Additional Resources

Appendix A: Glossary

A.1. Product and project names is a stand-alone getting started experience offered by Red Hat for jumpstarting cloud-native application development on OpenShift. It provides a way of creating functional example applications as well as an easy way to build and deploy these example applications on OpenShift.

Fabric8 Launcher

The Fabric8 Launcher is the upstream project on which is based.

Minishift or CDK

An OpenShift cluster running on your machine using Minishift.

A.2. Terms specific to Fabric8 Launcher


An application specification, for example a web service with a REST API.

Examples generally do not specify which language or platform they should run on; the description only contains the intended functionality.

Example application

A language-specific implementation of a particular example on a particular runtime. Example applications are listed in an examples catalog.

For example, an example application is a web service with a REST API implemented using the Thorntail runtime.

Examples Catalog

A Git repository that contains information about example applications.


A platform that executes an example application. For example, Thorntail or Eclipse Vert.x.