Red Hat OpenShift Application Runtimes 0.1

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application on a Single-node OpenShift Cluster For Use with Red Hat OpenShift Application Runtimes Last Updated: 2017-09-29

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application on a Single-node OpenShift Cluster For Use with Red Hat OpenShift Application Runtimes

Legal Notice Copyright 2017 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. Abstract This guide provides instructions for installing the developers.redhat.com/launch appliaction on a Single-node OpenShift Cluster.

Table of Contents Table of Contents. PREFACE............................................................................................................ 3.. CHAPTER.......... 1... PREREQUISITE:................. INSTALL......... A.. SINGLE-NODE............... OPENSHIFT............. CLUSTER........................................ 4. 1.1. INSTALLING MINISHIFT 4 1.2. INSTALLING RED HAT CONTAINER DEVELOPMENT KIT 5 CHAPTER 2. STARTING AND CONFIGURING THE SINGLE-NODE OPENSHIFT CLUSTER FOR THE. DEVELOPERS.REDHAT.COM/LAUNCH....................................... APPLICATION..................................................................... 7.. CHAPTER.......... 3... CREATING............ A.. GITHUB......... PERSONAL............ ACCESS......... TOKEN.................................................... 9.. CHAPTER.......... 4.... CREATING........... DEVELOPERS.REDHAT.COM/LAUNCH....................................... APPLICATION............................................ 10.. 4.1. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION USING AUTOMATED SCRIPT 10 Procedure 10 4.2. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION MANUALLY 12 Procedure 12. CHAPTER.......... 5.. NEXT....... STEPS........................................................................................ 16.. APPENDIX A. USING A NEXUS REPOSITORY SERVER WITH THE DEVELOPERS.REDHAT.COM/LAUNCH. APPLICATION.............. ON.... A.. SINGLE-NODE............... OPENSHIFT............. CLUSTER........................................................... 17.. A.1. PREREQUISITES FOR DEPLOYING NEXUS ON SINGLE-NODE OPENSHIFT CLUSTER. 17 A.2. CONFIGURING YOUR SINGLE-NODE OPENSHIFT CLUSTER TO USE NEXUS. 17 A.3. SETTING UP THE NEXUS APPLICATION 18. APPENDIX........... B.... GLOSSARY............................................................................................ 20... B.1. PRODUCT AND PROJECT NAMES 20 B.2. TERMS SPECIFIC TO DEVELOPERS.REDHAT.COM/LAUNCH 20 1

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o 2

PREFACE PREFACE This guide walks you through the process of installing the developers.redhat.com/launch application to run on a local cloud as provisioned by a Single-node OpenShift Cluster. This includes Minishift, an all-in-one VM that includes a community version of OpenShift Origin, or Red Hat Container Development Kit, a VM that includes OpenShift Container Platform. 3

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o CHAPTER 1. PREREQUISITE: INSTALL A SINGLE-NODE OPENSHIFT CLUSTER In order to use the developers.redhat.com/launch application on a local cloud, you must have a Singlenode OpenShift Cluster installed and configured. You can use either Minishift 1.5.0 or Red Hat Container Development Kit 3.0.0. 1.1. INSTALLING MINISHIFT The installation steps for Minishift are available in the OpenShift documentation and vary by platform. 1. Verify you have Minishift installed and configured. $ minishift version minishift v1.5.0+ae62cf2 2. Determine the command to add the correct version of the oc binary to your path and run the command. WARNING The below command may return Cannot find OpenShift client binary. if you have never started Minishift. To resolve this issue, you need to allow Minishift to start up at least once (minishift start). Once Minishift has completed its initial startup, you need to stop it (minishift stop) before proceeding. Example Result of oc-env $ minishift oc-env export PATH="/Users/john/.minishift/cache/oc/v1.5.1:$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 you are using. 3. Verify the oc CLI tools is on your path. 4

CHAPTER 1. PREREQUISITE: INSTALL A SINGLE-NODE OPENSHIFT CLUSTER $ oc version oc v1.5.1+7b451fc kubernetes v1.5.2+43a9be4 features: Basic-Auth GSSAPI Kerberos SPNEGO 1.2. INSTALLING RED HAT CONTAINER DEVELOPMENT KIT The installation steps for Red Hat Container Development Kit are available in Red Hat Container Development Kit Installation Guide and vary by platform. 1. Verify you have Red Hat Container Development Kit and the oc CLI tools installed and configured. $ minishift version Minishift version: 1.0.0+4f8cb6d CDK Version: 3.0.0 2. Determine the command to add the correct version of the oc binary to your path and run the command. WARNING The below command may return Cannot find OpenShift client binary. if you have never started Minishift. To resolve this issue, you need to allow Minishift to start up at least once (minishift start). Once Minishift has completed its initial startup, you need to stop it (minishift stop) before proceeding. Example Result of oc-env $ 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 use the oc binary installed with Red Hat Container Development Kit. 3. Verify the oc CLI tools is on your path. 5

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o $ oc version oc v3.5.5.8 kubernetes v1.5.2+43a9be4 features: Basic-Auth 6

URING THE SINGLE-NODE OPENSHIFT CLUSTER FOR THE DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION CHAPTER 2. STARTING AND CONFIGURING THE SINGLE- NODE OPENSHIFT CLUSTER FOR THE DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION NOTE Starting your Single-node OpenShift Cluster may trigger a download of large virtual machines or Linux container images. This may take a while. Subsequent startups should be shorter as long as the virtual machines and Linux container images remained cached. 1. Start your Single-node OpenShift Cluster. $ minishift start --memory=4096 Starting local OpenShift cluster using 'kvm' hypervisor...... OpenShift server started. The server is accessible via web console at: https://192.168.42.152:8443 You are logged in as: User: developer Password: <any value> To login as administrator: oc login -u system:admin NOTE Your Single-node OpenShift Cluster, by default, will select a virtual machine driver. Depending upon your system setup, you may need manually specify an alternative virtual machine driver using the --vm-driver flag, for example -- vm-driver=virtualbox would use VirtualBox. Virtual machine software, such as VirtualBox 5.x, is installed separately. On macos, the xhyve driver may be unreliable and the VirtualBox is a reliable alternative. If your system works without specifying the virtual machine driver, we recommend you use the default configuration. Depending on your operating system, virtual machine driver, and the number of boosters you run, you may need to increase the amount memory you give you to your Single-node OpenShift Cluster. You now have OpenShift running in a single-node cluster on your local machine. The log information provided by your Single-node OpenShift Cluster provides the address you need to use to access the web console as well as the credentials to log in. In the above example, the console is located at https://192.168.42.152:8443, the username is developer and the password is developer. 2. Open the web console using a web browser and authenticate. 7

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o IMPORTANT Since a Single-node OpenShift Cluster is for development purposes, it uses HTTPS for the web console and only provides a self-signed certificate. You may need to allow your browser to bypass SSL security policies as it tries to protect you from using HTTPS without a certificate signed by a certificate authority. The below screenshot shows the warning message in the Chrome browser. At this time, Safari on macos does not work with a Single-node OpenShift Cluster. This a known issue. Other browsers, such as Chrome, on macos do work with a Single-node OpenShift Cluster. 3. Delete the preconfigured project. The default installation provides a single pre-configured project, which you can delete. Click the three-dot menu icon next to the project name, select Delete Project from the drop-down menu, and complete the confirmation to delete it. 8

CHAPTER 3. CREATING A GITHUB PERSONAL ACCESS TOKEN CHAPTER 3. CREATING A GITHUB PERSONAL ACCESS TOKEN IMPORTANT You must have a GitHub account to set up a personal access token. If you do not have one, you must create a GitHub account before continuing. The developers.redhat.com/launch application adds generated starter applications called Boosters to your GitHub namespace. This requires the developers.redhat.com/launch application to have access to your GitHub account, which is granted using a GitHub personal access token. To create a GitHub personal access token: 1. Using a web browser, navigate to https://github.com/settings/tokens. 2. Select Generate new token. 3. Add a token description, for example developers.redhat.com/launch on Minishift. 4. Select the following parent scopes and all their children: repo 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 developers.redhat.com/launch application on your Single-node OpenShift Cluster. IMPORTANT This hex code only appears once and cannot be recreated. If you lose this hex code you will need to create a new personal access token. 9

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o CHAPTER 4. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION This chapter describes multiple ways of creating the developers.redhat.com/launch application. 4.1. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION USING AUTOMATED SCRIPT You can install the developers.redhat.com/launch application to your Single-node OpenShift Cluster using an automated script. The script will: Create a project in your Single-node OpenShift Cluster. Deploy the developers.redhat.com/launch application to that project using the latest template. Configure the developers.redhat.com/launch application with your GitHub username and personal access token. IMPORTANT If you are running your Single-node OpenShift Cluster on Windows, you must use the manual method for installing the developers.redhat.com/launch application. Procedure Using Script to Create developers.redhat.com/launch Application 1. Download the script. 2. Add execute permission for the script. $ chmod +x deploy_launchpad_mission.sh 3. Run the script. There are several options: Run the script with username and password. $./deploy_launchpad_mission.sh -p PROJECT_NAME -i developer:developer -g GITHUB_USERNAME:GITHUB_PERSONAL_ACCESS_TOKEN Run the script with your Single-node OpenShift Cluster access token. $./deploy_launchpad_mission.sh -p PROJECT_NAME -i OPENSHIFT_TOKEN -g GITHUB_USERNAME:GITHUB_PERSONAL_ACCESS_TOKEN Run the script and specify the version of the developers.redhat.com/launch application template to use. $./deploy_launchpad_mission.sh -p PROJECT_NAME -i developer:developer -g GITHUB_USERNAME:GITHUB_PERSONAL_ACCESS_TOKEN -v v11 10

CHAPTER 4. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION 4. Once the script completes, return to your Single-node OpenShift Cluster web console and click on your developers.redhat.com/launch application project. This is your project s overview page and you can see its current status. The grey circles reference that the docker images for these services are being pulled down from the network. This is a one time step that may take some time. Eventually the circles will turn a light blue to note that they are starting, then a deeper blue to indicate when they are running. When all services are running, you are ready to use the developers.redhat.com/launch application. 5. Click the link at the top of all services, which should end in nip.io. A new browser tab will open with the developers.redhat.com/launch application. You are now running on your local cloud the same service we will be hosting over at https://developers.redhat.com/launch. See the Getting Started Guide for more details on using the developers.redhat.com/launch application to launch mission booster applications. 11

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o 4.2. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION MANUALLY Create a local customized instance of the developers.redhat.com/launch application, which allows you to test the functionality or make modifications to the application using a web interface. Procedure Creating developers.redhat.com/launch Application 1. Open your local OpenShift web console and log in. NOTE The IP address and credentials to log in are in the terminal window where you executed minishift start. 2. Click New Project to create a new OpenShift project to house the developers.redhat.com/launch application. 3. Name the project and optionally provide a description. This example uses my-launcher for the project s name. 12

CHAPTER 4. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION 4. Click Create to complete the project creation. 5. Click Import YAML/JSON to add services to your new project from a template. 6. Copy the contents of the current developers.redhat.com/launch template from the GitHub repository and paste it into the text box provided. NOTE We are working on removing this step entirely, but for now it is required. The full details and a current status are available on GitHub. 7. Click Create, ensure that only the Process the template option is selected, and click Continue. 8. Fill out the following fields. 13

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o Your GitHub username. Your GitHub Mission Control access token is your personal access token for GitHub. The Target OpenShift Console URL is the OpenShift Console URL from your Single-node OpenShift Cluster. This should be the same base URL you are currently using to complete the form, for example https://192.168.42.152:8443. OpenShift username and password from your Single-node OpenShift Cluster, for example developer for the username and password. KeyCloak URL and KeyCloak Realm MUST be cleared out. WARNING You must clear these fields out for the developers.redhat.com/launch application on your Single-node OpenShift Cluster to be configured correctly. Do not modify Catalog Git Repository and Catalog Git Reference unless you are developing against a specific catalog repository. 9. Before proceeding to the next steps, confirm all the fields are correct. Also confirm that KeyCloak URL and KeyCloak Realm have been cleared out. 10. Click Create to complete the setup. You will see a screen confirming that the application has been created. Click Continue to overview. 11. On the overview page, wait and confirm that the four services for the developers.redhat.com/launch application are starting up. 14

CHAPTER 4. CREATING DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION The grey circles reference that the docker images for these services are being pulled down from the network. This is a one time step that may take some time. Eventually the circles will turn a light blue to note that they are starting, then a deeper blue to indicate when they are running. 12. When all services are running, you are ready to use the developers.redhat.com/launch application. Click the link at the top of all services which typically ends in the nip.io suffix to open the developers.redhat.com/launch application in a new browser tab. You are now running on your local cloud the same service we will be hosting over at developers.redhat.com/launch. 15

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o CHAPTER 5. NEXT STEPS Start using your developers.redhat.com/launch application to launch booster applications. Take a look at the Getting Started Guide for a walk-through of running a booster. Read the runtime guides for an overview of the runtimes and their boosters. Spring Boot Tomcat Runtime Guide Eclipse Vert.x Runtime Guide WildFly Swarm Runtime Guide 16

RVER WITH THE DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION ON A SINGLE-NODE OPENSHIFT CLUSTER APPENDIX A. USING A NEXUS REPOSITORY SERVER WITH THE DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION ON A SINGLE-NODE OPENSHIFT CLUSTER 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 developers.redhat.com/launch application on your Single-node OpenShift Cluster and use it to fetch artifacts from the Maven Central Repository and cache them locally. This helps you speed up your builds and rolling updates and alleviates network load during build time. A.1. PREREQUISITES FOR DEPLOYING NEXUS ON SINGLE-NODE OPENSHIFT CLUSTER. Set up your Single-node OpenShift Cluster. For detailed steps on how to do this, follow the instructions in Install and Configure the developers.redhat.com/launch Application on a Single-node OpenShift Cluster. Configure your Single-node OpenShift Cluster to use at least 4096 MiB of RAM and use the required oc CLI tool version. minishift delete # Delete the previous instance of Single-node OpenShift Cluster minishift config set memory 4096 minishift config set openshift-version v3.6.0 minishift start WARNING The procedure described below works with Minishift version 1.5.0. It has not been tested for use with CDK. You must use oc version 3.6.0 or later. Deploy the developers.redhat.com/launch application to your Single-node OpenShift Cluster. Deploy a Booster application to your Single-node OpenShift Cluster. A.2. CONFIGURING YOUR SINGLE-NODE OPENSHIFT CLUSTER TO USE NEXUS. 1. Log in to your Single-node OpenShift Cluster instance. oc login https://local_openshift_url:port -u developer -p developer 2. You can reuse the Docker daemon instance used by Single-node OpenShift Cluster to download the latest versions of the Nexus Docker container image. eval $(minishift docker-env) docker pull openshift/jenkins-2-centos7 17

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o docker pull openshiftio/launchpad-jenkins-slave docker pull sonatype/nexus A.3. SETTING UP THE NEXUS APPLICATION 1. 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 2. Deploy the Nexus container image. oc new-app sonatype/nexus 3. Expose the service route URL of the Nexus server. oc expose svc/nexus 4. Attach a 1 GiB persistent storage volume to the Nexus application. oc volumes dc/nexus --add --name 'nexus-volume-1' --type 'pvc' -- mount-path '/sonatype-work/' --claim-name 'nexus-pv' --claim-size '1Gi' --overwrite 5. Find the external address of the Nexus instance: oc get routes NAME HOST/PORT PATH SERVICES PORT TERMINATION nexus nexus-nexus_project_name.local_openshift_hostname nexus 8080:8080 NOTE 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 jboss-ga Maven repository to your Nexus instance. 6. Navigate to the project containing your Booster application. oc project MY_PROJECT_NAME 7. Assign the admin role to your Jenkins application and the edit permissions to your OpenShift account. Skip this step if you have already assigned these permissions. oc policy add-role-to-user edit system:serviceaccount:my_project_name:default oc policy add-role-to-user admin system:serviceaccount:my_project_name:jenkins 18

RVER WITH THE DEVELOPERS.REDHAT.COM/LAUNCH APPLICATION ON A SINGLE-NODE OPENSHIFT CLUSTER 8. Obtain the Jenkins server URL and use it to access the Jenkins instance from your browser. oc get routes jenkins NAME HOST/PORT PATH SERVICES PORT TERMINATION jenkins jenkins-my_app_name- MY_PROJECT_NAME.LOCAL_OPENSHIFT_HOSTNAME jenkins <all> edge/redirect 9. Navigate to jenkins-my_app_name- MY_PROJECT_NAME.LOCAL_OPENSHIFT_HOSTNAME/configure, and log in using your OpenShift credentials to access the Jenkins configuration page. 10. Go to the section titled Kubernetes Pod Template, click on Add Evironmental Variable, and select Global Environmental Variable option from the drop-down menu. 11. Define a new environment variable: Name: MAVEN_MIRROR_URL Value: nexus- NEXUS_PROJECT_NAME.LOCAL_OPENSHIFT_HOSTNAME/nexus/content/groups/pub lic/ NOTE The actual value of the MAVEN_MIRROR_URL environmental variable corresponds to the service route of the pod running the Nexus server instance on your Single-node OpenShift Cluster. To obtain this route, navigate to the project that contains your Nexus instance and execute the command oc get routes nexus. 12. Click Apply to confirm the configuration changes. 13. Redeploy the Jenkins server instance with the latest configuration changes. oc rollout latest dc/jenkins WARNING KNOWN ISSUE: Redeploying your instance of Jenkins server causes other ongoing builds to hang. 14. Navigate to the project that contains your Booster and use the Web console to go to Builds > Pipelines and click Start Pipeline to rebuild your Booster application. 19

Red Hat OpenShift Application Runtimes 0.1 Install and Configure the developers.redhat.com/launch Application o APPENDIX B. GLOSSARY B.1. PRODUCT AND PROJECT NAMES developers.redhat.com/launch The web application you launch boosters with. Single-node OpenShift Cluster An OpenShift cluster running on your machine using Minishift. B.2. TERMS SPECIFIC TO DEVELOPERS.REDHAT.COM/LAUNCH Booster An language-specific implementation of a particular mission on a particular runtime. Boosters are listed in a booster catalog. For example, a booster is a web service with a REST API implemented using the WildFly Swarm runtime. Booster Catalog A Git repository that contains information about boosters. Mission An application specification, for example a web service with a REST API. Missions generally do not specify which language or platform they should run on; the description only contains the intended functionality. Runtime A platform that executes boosters. For example, WildFly Swarm or Eclipse Vert.x. 20