Install and Configure the Fabric8 Launcher Tool

Red Hat OpenShift Application Runtimes 1

For Use with Red Hat OpenShift Application Runtimes

Red Hat Customer Content Services

Abstract

This guide provides instructions for installing the Fabric8 Launcher tool on a Minishift or CDK.

Preface

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:

Chapter 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.

Chapter 2. Installing Minishift

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

Procedure

  1. Follow the instructions for installing Minishift:

    Note

    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)

    Warning

    You must have the oc binary installed and it must match the version of Minishift that you are using.

Chapter 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.

Note

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.

Important

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

Prerequisites

Procedure

  1. Start Minishift with the default virtual machine driver:

    Note

    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:
        https://192.168.42.152:8443

    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.

    Note

    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

Chapter 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.

Procedure

  1. Using a web browser, navigate to https://github.com/settings/tokens.
  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.

    Important

    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.

Chapter 5. Installing Fabric8 Launcher Tool

Install an instance of the Fabric8 Launcher tool, which allows 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. The following procedure works with clusters running on OpenShift 3.11.

Prerequisites

  • Admin access to an OpenShift cluster.

Procedure

  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 credentials:

    $ oc login OPENSHIFT_CLUSTER_URL
  3. Create a project to host the operator:

    $ oc new-project launcher-operator
  4. Create a personal GitHub access token. Ensure that you set the following scope when creating the token:

    • repo
    • admin:repo_hook
    • delete_repo
  5. Create a new secret using your newly created personal GitHub access token:

    $ oc create secret generic launcher-secrets --from-literal=github-token=GITHUB_TOKEN
  6. Download and extract the ZIP file containing the operator and navigate to the directory containing the extracted resources.

    $ cd launcher-operator
  7. Process 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 Launcher operator
    • a service account for the Launcher operator
    • access role definitions for the launcher operator
    • access role bindings for the Launcher operator
  8. Install the following custom resource in order to initiate the deployment of the Fabric8 Launcher tool.

    $ oc create -f example/launcher_cr.yaml
  9. Monitor the status of the Fabric8 Launcher tool until it completes start up.

    $ oc get pods -w
    NAME                           READY     STATUS              RESTARTS   AGE
    configmapcontroller-1-deploy   1/1       Running             0          46s
    configmapcontroller-1-aaaaa    0/1       ContainerCreating   0          44s
    launcher-backend-1-deploy      1/1       Running             0          46s
    ...
    launcher-backend-2-aaaaa       0/1       Running             0         5s
    launcher-frontend-2-aaaaa      0/1       Running             0         6s
  10. Obtain the route of your Fabric8 Launcher tool.

    $ oc get routes
    NAME       HOST/PORT                                         PATH      SERVICES            PORT      TERMINATION   WILDCARD
    launcher   launcher.launcher.LOCAL_OPENSHIFT_HOSTNAME                launcher-frontend   <all>                   None
  11. Navigate to the route URL to start using Fabric8 Launcher.

Additional Resources

Appendix A. Using a Nexus repository server on a Minishift or CDK

While developing your cloud-native applications with Java and Maven, you may be required to build them repeatedly. You can deploy a Nexus Repository server alongside the Fabric8 Launcher tool on your Minishift or CDK and use it to fetch artifacts from the Maven Central repository and cache them locally. This reduces the network load when building your application, and helps accelerate the build and rolling updates.

Prerequisites

  • Your Minishift or CDK configured to use at least 4096 MiB of RAM and use the required oc CLI tool version.

    minishift delete # Delete the previous instance of Minishift or CDK
    minishift config set memory 4096
    minishift start
    Warning

    The procedure described below works with Minishift. It has not been tested for use with CDK.

  • The Fabric8 Launcher tool deployed to your Minishift or CDK.
  • An example application deployed to your Minishift or CDK.

Procedure

  1. Log in to your Minishift or CDK instance.

    oc login https://OPENSHIFT_CLUSTER_URL -u developer -p developer

    You can reuse the Docker daemon instance used by Minishift or CDK to download the latest versions of the Nexus Docker container image.

    eval $(minishift docker-env)
    docker pull openshift/jenkins-2-centos7
    docker pull openshiftio/launchpad-jenkins-slave
    docker pull sonatype/nexus
  2. Create a new project to contain the Nexus server. You can also use the New Project button on the Web console to do this.

    oc new-project NEXUS_PROJECT_NAME
  3. Deploy the Nexus container image.

    oc new-app sonatype/nexus
  4. Expose the service route URL of the Nexus server.

    oc expose svc/nexus
  5. Attach a persistent volume claim with a minimum size of 10 GiB to the pod running your Nexus application.

    oc volumes dc/nexus --add --name 'nexus-volume-1' --type 'pvc' --mount-path '/sonatype-work/' --claim-name 'nexus-pv' --claim-size '10Gi' --overwrite
  6. Navigate to the project containing your example application.

    oc project MY_PROJECT_NAME
  7. Define and start a new build.

    Pass in a parameter to set the value of the MAVEN_MIRROR_URL to match the service URL of your Nexus application:

    Note

    Ensure that the YAML template of the builder image you are using for your application has the MAVEN_MIRROR_URL environment variable defined. If it does not, see the Nexus documentation for instructions on configuring your build manually before proceeding.

    $ oc new-build MY_APP_NAME:latest~SCM_REPOSITORY_URL \
    -e MAVEN_MIRROR_URL='http://nexus.NEXUS_PROJECT_NAME:8081/nexus/content/groups/public'

    Nexus comes pre-configured for the Maven Central repository, but you may need other repositories for your application. To access images provided by Red Hat, add the Red Hat JBoss Middleware Early Access Maven Repository to your Nexus instance.

  8. Ensure that your new build is using Nexus to retrieve artifacts. Do one of the following:

    • Navigate to http://nexus-NEXUS_PROJECT_NAME.LOCAL_OPENSHIFT_HOSTNAME/nexus/content/groups/public to view the list of artifacts stored in your local repository.
    • Check the log output of the build:

      $ oc logs build/MY_APP_NAME-1 --follow

    If your build uses Nexus to retrieve artifacts, the build log output should reference the path http://nexus.NEXUS_PROJECT_NAME:8081/.

Appendix B. Glossary

B.1. Product and project names

developers.redhat.com/launch
developers.redhat.com/launch is a standalone 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 developers.redhat.com/launch is based.
Minishift or CDK
An OpenShift cluster running on your machine using Minishift.

B.2. Terms specific to Fabric8 Launcher

Example

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.
Runtime
A platform that executes an example application. For example, Thorntail or Eclipse Vert.x.

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.