This document guides you through your first experiences with Red Hat CodeReady Toolchain for OpenShift. It provides instructions on creating and importing codebases to launch cloud based applications, set up continuous integration and deployment pipelines, analyze and customize the application in a hosted, web-based IDE, and deploy them on OpenShift Online.

Learn about CodeReady Toolchain

1. Introduction

Red Hat CodeReady Toolchain for OpenShift is a collaborative, open-source, web-based application life cycle management (ALM) solution. It provides an integrated DevOps tool-chain to plan, create, and deploy hybrid cloud services.

This guide walks you through the initial set up of CodeReady Toolchain and highlights some of its key features and components. Use this guide to set up an application in the cloud, customize it, and then deploy a new version of it in under an hour.

2. Getting help and giving feedback

CodeReady Toolchain follows a continuous delivery model. Updates and changes to the system are delivered continuously, often multiple times in a day. Hearing directly from you about your experiences lets us improve the product and experience for you. Use the following options to get help, raise bugs, request for features, and provide feedback.

2.1. Asking questions about CodeReady Toolchain

The CodeReady Toolchain MatterMost chat channel is the best way to ask questions or get immediate help for CodeReady Toolchain at any time. We encourage users to ask their question or discuss the problem they face in the channel for a fast resolution.

If you don’t already have a MatterMost account:

  1. Navigate to the CodeReady Toolchain MatterMost chat channel and click Create one now.

  2. Add your details and click Create Account to register.

  3. In your email inbox, click the Verify Email link.

  4. Sign in when prompted and when asked, select the Developers team. You are redirected to the appropriate channel.

    Main view
  5. Ask a specific person your question or start with @here to tag everyone present in the channel.

In the future, navigate to the CodeReady Toolchain MatterMost channel for any questions on CodeReady Toolchain.

If you prefer to use IRC, the CodeReady Toolchain team is also available in the #openshiftio channel on Freenode.

2.2. Send us feedback about Red Hat CodeReady Toolchain for OpenShift

To give the CodeReady Toolchain team feedback, create an issue and send us a description of the problem with the necessary details and screenshots if necessary. You can also search for related issues at this link.

When the issue is logged, the CodeReady Toolchain team adds appropriate tags and labels to address it at the earliest.

If you prefer email, send your feedback to the CodeReady Toolchain mailing list.

2.3. Send us feedback about the documentation

The documentation team welcomes all feedback or requests for information that is helpful to you but is not covered.

  • Is there anything we can do to improve the documentation?

  • Was a part of the documentation not useful for you?

  • Is there anything we did not document that you want to do with CodeReady Toolchain?

Create an issue to send us your feedback.

3. Before you start

3.1. Before you begin using CodeReady Toolchain

Before you use CodeReady Toolchain, keep the following information in mind:

  • When you sign up to use CodeReady Toolchain, you get an OpenShift Online account with enough resources to run a basic application in the stage and run environments, set pipelines, and develop the codebase in the integrated Eclipse Che workspace.

  • Your OpenShift Online Starter account includes two pods and therefore can accommodate two workspaces in CodeReady Toolchain.

  • Ensure that you use CodeReady Toolchain with an OpenShift Online Starter account, not an OpenShift Online Pro account.

3.2. Prerequisites

Browser Requirements:

Currently, you can use only Google Chrome for CodeReady Toolchain.

General Requirements:

  1. Ensure that you have a GitHub account.

  2. Register to join the CodeReady Toolchain developer preview.

3.3. Logging into CodeReady Toolchain and connecting to OpenShift Online

When you sign up for CodeReady Toolchain, you receive a welcome email. After you receive this email, use the following steps to set up CodeReady Toolchain:

  1. In your browser, navigate to CodeReady Toolchain login page.

  2. Click LOG IN at the top of the page.

  3. Enter your Red Hat Developer (or other listed services) credentials. Your CodeReady Toolchain account is automatically connected to your OpenShift Online account.

You are now ready to use your CodeReady Toolchain account.

3.4. Opting in to beta features

This guide covers the Production and Beta features of CodeReady Toolchain.

In the CodeReady Toolchain home screen, use the following steps to opt in or out of features:

  1. Navigate to your Settings view:

    1. Click your name on the top right corner of the screen.

    2. Select Settings from the displayed options.

  2. In the User Settings page, click the Features Opt-in option.

  3. Select the Beta Features option from the list to see the CodeReady Toolchain features covered in this guide. The Production-Only Features option is recommended for users who only want the stable CodeReady Toolchain features.

    Opt in features

    The change is applied to your profile and you receive a confirmation message.

Start using CodeReady Toolchain

4. Introduction to the home screen

After logging in, this is what your CodeReady Toolchain Account home looks like:

CodeReady Toolchain home screen
(1) Navigate between spaces

The upper-left corner of CodeReady Toolchain displays your username. Click the drop-down to view the spaces you are associated with and to navigate between them. A space is the first thing you create when using CodeReady Toolchain. See about spaces to learn about spaces.

(2) Profile and Settings

The upper-right corner of CodeReady Toolchain displays your name. Click the drop-down to view Settings and Profile options. Use these options to change your profile and setting preferences. Use the Chat with us option to discuss any issues you face with CodeReady Toolchain on the MatterMost channel.

(3) Recent Spaces

The Recent Spaces area of the home screen displays all the spaces you have created. When you first use CodeReady Toolchain this space is empty and you can click Create a Space to quickly create a new space.

(4) Recent Workspaces

The Recent Workspaces area displays all created workspaces. See about workspaces to learn more about workspaces and what you can do with them.

(5) My Work Items

The My Work Items section displays work items used to track your planned and current tasks for each space. See about work items to learn more about work items and how to use them.

5. Hello World for Developers

5.1. Creating a new space

In CodeReady Toolchain, the first step for any new project is to create a new space with a unique name. You can then create or import codebases within the space, add collaborators, and plan your work using work items and iterations.

Procedure

Create a new space as follows:

  1. In the CodeReady Toolchain home page, click Create a space in the Recent Spaces section. If your account has an existing space, click + to create an additional space.

  2. In the Create a New Space dialog box, type myspace as the unique name for your space and click Ok.

    Create new space

You have now created your first space.

5.2. About application codebases

After creating a space, you can use CodeReady Toolchain to create a new application codebase or import an existing codebase from GitHub and set up pipelines to build the code. These codebases are a generic representation of a project’s code.

When you create a new application using the quickstart wizard, CodeReady Toolchain creates a new code repository for your codebase and stores it in GitHub. CodeReady Toolchain also maintains additional metadata for version control of your project code.

5.3. Creating a new application

When you create a new space, the Create an Application wizard to add or import codebases displays. If you closed the wizard earlier, click Add to space in your space dashboard to see the wizard again. Use this wizard to create a new quickstart application as follows:

Start creating apps
  1. In the Name your application field, type helloworldvertx.

  2. Select the Create a new codebase radio button and click Continue.

  3. Select the mission and runtime for your new project:

    1. In the Choose a mission section, select the REST API Level 0 option.

    2. In the Choose a runtime section, select Eclipse Vert.x.

    3. Click the blue down-arrow button to continue.

      Choose mission and runtime
  4. In the Select Pipeline section, select the first option, then click the blue arrow to continue to the next step.

    Select a pipeline
  5. In the Authorize Git Provider section, your credentials are auto-populated if you have already connected your GitHub account to CodeReady Toolchain. If your GitHub account is not connected with CodeReady Toolchain, click Login & Authorize Account. If your browser session is already logged in to a GitHub account, CodeReady Toolchain uses it to connect your GitHub account with CodeReady Toolchain. If not, you are prompted to sign in to your GitHub account. After your GitHub account is connected, click the blue arrow to continue.

    Authorize GitHub
  6. The next screen displays a summary of your application options. Scroll down in your browser to view the Application Information section. For this example, do not edit these options. If desired, you can change the Application Name, Version, and Group ID for your new application at this step.

    Application information
  7. Click Set Up Application to create the new application.

  8. The progress screen displays a confirmation message when your application is ready.

    Once your application is ready, you can do one of the following:

    • Return to the dashboard to see the details of the application deployed on stage, a detailed stack analysis report, and the codebase you added.

    • View your continuous integration pipelines

    • Edit your application codebase in Che web IDE.

      Application ready

      For this example, click View Pipeline to see your application. Your new Vert.X application is now created in your space and deployed to the staging environment.

CodeReady Toolchain has now hosted the project source code in the specified organization of the linked GitHub account. It has also hosted the pipeline for the project in OpenShift Online.

5.4. About pipelines and the stage and run environments

When you create a codebase, a pipeline build is initiated. Pipelines are automated, continuous integration and deployment processes, powered by Jenkins, which define how your application is deployed.

The free OpenShift Online Starter subscription, included with your CodeReady Toolchain subscription, provides two environments named Stage and Run to deploy your applications.

Initially, the build pipeline deploys the application to Stage, which is accessible to stakeholders for review through a public URL provided by OpenShift Online. If approved and promoted, the pipeline deploys it to the Run environment. This simulates the workflow of pushing an application to a staging environment and reviewing it, before promoting it to production.

The Run environment is similar to a production environment but is another staging area. The reason Run is not named Production is that the OpenShift Online Starter subscription does not support running production applications.

5.5. Reviewing your staged application

When you create a new codebase, the selected pipeline pushes version 1.0.1 of your new application into the Stage environment, and then awaits your approval to deploy into the Run environment.

Stage and Run are individual OpenShift projects. Stage is a production staging area to review and test changes before they are finalized and then staged on Run.

To review your application on Stage:

  1. If you are not already in the Pipelines page, at the top of the page, click Create, and then click Pipelines to see the build pipelines for your new application. When you create a new codebase, the selected pipeline is triggered. In the Build Release stage of the pipeline, the build server is set, the build is started, and then released. Next, the pipeline build pushes the application to stage and it displays at the Approve stage. This process takes a few minutes.

    Pipeline First Run
    If your pipeline build does not start for more than ten minutes, you can manually start a pipeline build using the instructions at pipeline_build_failure.
  2. Click the icon (rollout icon) next to Rollout to Stage in the displayed pipeline. OpenShift Online provides this public URL to access the staged quickstart application.

    A new browser tab displays the HTTP Booster application running on Stage. The Vert.x HTTP booster quickstart produces a simple API behind a REST endpoint over HTTP with a minimalist user interface.

    Staged Application
    If the application does not load, see application_not_available for troubleshooting information.
  3. To test the application, enter a name in the Name field and click Invoke. The Result field displays the JSON result returning from the API.

    Test the Application

5.6. Approving your application

If the quickstart application in the Stage environment runs as expected, approve your application and promote it to the Run environment:

  1. Return to the CodeReady Toolchain tab which displays the Pipeline view and click Input Required at the Approve stage of the pipeline.

  2. Click Promote to promote the application from the Stage environment to the Run environment. This process requires a few minutes.

    Promote application
  3. Optionally, as your application is promoted to Run, click helloworldvertx or Build #1 to view the detailed progress of the pipeline or build in your OpenShift Online console, respectively.

  4. When the Pipeline view in CodeReady Toolchain indicates that the application is available in the Run environment, click the icon (rollout icon) next to Rollout to Run to view the application in a new tab.

    Rollout to Run

5.7. Viewing the build pipeline logs

Optionally, while you wait for the pipeline build, you can view the build details in the Jenkins log. For experienced users, these logs are useful when troubleshooting problems with builds if required.

  1. In the Pipeline page, click View Log for the build pipeline in progress.

  2. When prompted, log into Jenkins with your OpenShift Online account. If the page does not display, wait for a few minutes for the Jenkins instance to initialize and try again. Once you are logged in, the page displays the logs for your pipeline build.

    Pipeline Build Logs in Jenkins
    Do not click the Proceed or Abort options at the end of the logs.

You can now examine the log output to troubleshoot build problems if needed.

5.8. Viewing your application deployment details

You can see a detailed view of your application pods in the stage and run environments, resources consumed in the two environments, and the overall resources used by the application in the Deployments view as follows:

  1. At the top of the page, click Create and then click Deployments to see the deployment details.

  2. In Applications, expand helloworldvertx to see the application pods and the resources consumed in the stage and run environments respectively. The Resource Usage at the bottom of the screen displays the overall resources used by your applications in CodeReady Toolchain.

    Deployments page
  3. To see further deployment details in your OpenShift Online console, in either the Stage or Run environments, click the options (kabob) icon and then click View OpenShift Console.

  4. If prompted, click LOGIN WITH RED HAT to log in to your OpenShift Online account. When logged in, the OpenShift Online console displays an overview of your application.

  5. In the left pane, click Applications > Deployments to view details about the application deployment in the appropriate environment.

    OpenShift Online Deployments

Similarly, select username-run project to see details of the deployed application in the run environment.

5.9. Viewing your codebase in GitHub

After reviewing your pipeline build running in CodeReady Toolchain and OpenShift Online, view your application codebase in GitHub as follows:

  1. Return to the Pipeline view in CodeReady Toolchain, the Source Repository provides the link to the codebase of your application. Right click the link and open it in a new tab to see your codebase in GitHub.

  2. In the repository, click the Jenkinsfile to view details on staging and rolling out of the pipelines.

    Project Code in GitHub

Use the codebase link to review code commits and details in your GitHub repository.

5.10. Viewing your OpenShift Online projects

To view all the OpenShift Online projects that support your application, navigate to My Projects in the OpenShift Online Console.

OpenShift Online Projects

This page displays the following projects and namespaces that are created in OpenShift Online:

  • The username project is where your pipelines run. Your OpenShift Online user name is the name of your project.

  • The username-che project represents your Che Host and workspaces.

  • The username-jenkins project represents your Jenkins Master for your Jenkins Slaves. Click this project, and then click Monitoring in the left pane to access your Jenkins console.

  • The username-run project is identical to the username-stage project and is an environment for experimenting with your OpenShift pods and monitoring the memory usage for your application.

  • The username-stage project is for your personal use. Use this project to see the pods that are created when pipelines are triggered in CodeReady Toolchain. For maintenance, select this project and power down individual pods as required.

5.11. About workspaces

CodeReady Toolchain provides hosted instances of Eclipse Che within your browser to edit, test, and debug your project code. One of the key features of Eclipse Che is Che workspaces, which provide a fully configured runtime environment for running your code. As a result, CodeReady Toolchain provides a lightweight, next generation IDE, and a containerized development and testing environment.

When you use the quickstart to create an application in CodeReady Toolchain, the development and testing environment in the workspace is automatically configured with the necessary runtime components. Now you can use the Che workspaces as your personal development machine to modify your application codebase.

5.12. Creating a Che workspace

To edit your application codebase, create a new Che workspace:

  1. Click Create from the top of the CodeReady Toolchain page. The default view for this tab is Codebases.

  2. In the WORKSPACES column, click Create workspace for your project. The workspace gets created.

  3. Click Open next to the workspace to see your Che workspace in a new browser tab.

    If a new tab does not appear, see enable_popups for troubleshooting information.

    As the workspace loads the codebase for your application, the Workspace Status window at the bottom of the Che workspace tab displays the progress:

    Workspace loading
    If the Workspace Status shows Stopped, click Start in the Workspace is not running pane at the top, to restart your workspace.

    When loaded and ready to use, the new Che workspace tab displays the following confirmation message:

    Workspace Running success message

5.13. Running your project in the Che workspace

After your Che workspace loads, you can see your project code listed in the file explorer panel, in the upper-left side of the screen.

  1. Click the run option from the Run button (tri run). Maven then downloads the required dependencies, compiles the application, and starts the verticle (Vert.x uses this name for deployed code). For Vert.x projects, this also sets up the server and hot deploy options. The hot deploy option automatically updates the application when you make a change.

    If the Run command macro is not defined, it displays the Create run command option instead of Run:

    Create run command

    See create_run_command_macro for instructions on setting up a run command.

  2. A run terminal appears at the bottom pane of the Che workspace. When the mvn build command finishes executing, the run view displays the following message:

    [INFO] INFO: Succeeded in deploying verticle
  3. Click the blue preview URL at the top of the run view to see your application running in Che.

    Run project link
  4. In the application, enter a name in the Name field and click Invoke to test the application.

    Testing the application

    This is the same version of the application that the pipeline deployed to Stage and you subsequently promoted to Run. The URL for this build of the application is different from the URLs used by OpenShift Online for Stage and Run. This is your private sandbox hosted within Che. You can still share this URL with others and interactively debug the application while they run it in their browser.

5.14. Changing the quickstart code

To change your project code and preview the results:

  1. In your Che workstation view, navigate to: src > main > Java > io.openshift.booster > HttpApplication.java.

    Project Directory
  2. Double click the HttpApplication.java file to open it and find the following line:

      static final String template = "Hello, %s!";
  3. Change the greeting message and then save your changes.

      static final String template = "Hello from Che, %s !"

    If you already ran the application earlier as instructed in Running your project in the Che workspace, your changes are instantly implemented. Maven uses the Vert.X hot deploy feature to automatically update the application when you make a change.

  4. Return to the browser tab running the application, add a name in the Name field, and click Invoke to test the application. The displayed message shows the amended text template.

    Testing the Application

You have now learned how the workspace automatically saves and applies your changes.

5.15. Committing and pushing changes to GitHub

After making the required changes to your code, commit and push the modifications to your project GitHub repository.

Before committing your changes, ensure that your project pipeline build is promoted and at the Rollout to Run stage.
  1. In your Che workspace, click Git from the menu bar options and select Commit from the displayed options.

  2. In the Commit to repository dialog box:

    1. If they are not already, select all the changed and new files to add them to the commit.

    2. Add a commit message describing your changes.

    3. Select the Push committed changes to check box.

    4. Click Commit.

When the commit succeeds, the following message displays:

Pushed to origin

You have now committed your code changes to GitHub.

5.16. Reviewing and publishing your changes

When you commit and push a change to GitHub, a pipeline build is automatically triggered in CodeReady Toolchain.

To review the build and publish your changes:

  1. Return to the CodeReady Toolchain browser tab.

  2. Click Create and then Pipelines to view the build pipelines. Wait for the build pipeline to progress to the Approve stage.

  3. In the Create tab, click Deployments to see the following information:

    Versions of the Application
    • Different versions of your application are now deployed to Stage and Run. Version 1.0.2 of the application, which includes your committed change to the code, is deployed to Stage because you have not yet promoted it to Run. The older version, 1.0.1 , is deployed to Run because you approved it the last time the pipeline build executed.

    • The green check marks indicate that both builds are operational.

    • The 1 pod indicates that each of the application builds scale to one pod in OpenShift Online. The number of pods indicates the number of running instances of the application.

    • The version numbers link to individual running applications. You can use these separate staging areas to share different versions of your application before promoting a change. Click the version numbers to view the details for that deployment.

  4. Click Pipelines to return to the pipelines view and click Input Required at the Approve stage of the pipeline.

  5. Click Promote to promote version 1.0.2 of the application to Run.

    Your changes are now available on both Stage and Run. If you return to the Deployments tab, you can see that version 1.0.2 is deployed to both Stage and Run.

You have now created your first quickstart project in CodeReady Toolchain, made changes to your project code, committed the changes to GitHub, and published the new version of your project.

6. Analyzing your application

6.1. Analyzing your application stack dependencies

As you edit your application code, your Che workspace is automatically analyzing dependencies for the changes.

  1. Return to your Che workspace browser tab.

  2. In the file explorer panel, double-click the pom.xml file.

  3. In the file editor, go to line 111 and add a line break.

  4. Add the following XML code to the file after the line break:

    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-core</artifactId>
      <version>1.1.0</version>
    </dependency>
  5. An error icon (red cross) appears next to the added lines of code. Move the mouse pointer over the icon to view the error message and a recommendation for improving the dependency.

    Error Icon

    The error indicates that the dependency analyzer has identified a high Common Vulnerabilities and Exposures (CVE) score associated with the current version, 1.1.0. It also recommends using an alternate, secure version, 1.1.2, instead to fix the issue.

  6. In the code, update the version to 1.2.1. The error icon disappears after this change.

  7. Commit these changes to add this dependency to your stack.

You have now learned how CodeReady Toolchain analytics automatically analyze dependencies in your code, identify security vulnerabilities, and recommend fixes.

6.2. Using stack reports to analyze your application

CodeReady Toolchain includes a stack report feature that analyzes and reports information about a project’s application stack and dependency libraries. Stack reports recommend alternate and additional components to improve your application and help you make informed choices about the code and libraries used in your project.

CodeReady Toolchain generates a stack report for your project when the pipeline build starts the Build Release stage. To view the stack report for your quickstart application:

  1. Return to your space dashboard in the CodeReady Toolchain browser tab. The Stack Report Recommendations panel in the dashboard shows a summary of the stack report.

    Stack Reports
  2. Click View complete stack report to view the detailed stack report. The detailed stack report provides information about Security Issues, Licenses, Insights, and Dependency Details for your stack.

    Detailed Stack Report
  3. Click each of the cards to view the following detailed information:

    • Security Issues lists dependencies with known security vulnerabilities and the relevant Common Vulnerabilities and Exposures (CVE) information.

    • Licenses lists dependencies with license conflicts and unknown licenses and suggests alternate dependencies to resolve the conflicts.

    • Insights identifies dependencies that do not work well with the stack and recommends alternate dependencies for them. In addition, it recommends companion dependencies to enhance your stack. For this example, the stack report recommends companion dependencies that augment your development stack.

    • Dependency Details lists all the dependencies in your stack, flags security, usage, and license issues for them, and suggests replacements for dependencies with issues.

      For further information about the stack report, see interpreting your stack report.

  4. In the Companion Dependency Details section, click Create work item to add an auto-populated work item to the planner.

    You have now learned how the stack report provides detailed information about your stack and its dependencies, and how it suggests alternate and additional dependencies you can add to your stack to improve your application and make it more secure.

7. Planning development work

CodeReady Toolchain planner uses the Agile development methodology to track tasks as work items assigned to collaborators.

Use the Agile development process to plan and execute your project using iterative cycles as follows:

Prerequisite:
Procedure
  1. In the dashboard of your space, select the Plan tab at the top of the page. The default Backlog view displays the Work Items for your space.

  2. In the Add Work Item pane, select Task from the work item type drop-down list, type the title Optimize CodeReady Toolchain resource usage, and click Add and Open to see the detailed view for the work item.

    Quick Add task
  3. In the detailed view of the work item:

    1. Change the state of the work item from New to Open.

    2. Assign it to yourself.

    3. Close the detailed view to go back to the list view.

      Modify WI

    See modifying work items for detailed information.

  4. In the left panel, click the (+) icon adjacent to Iterations to see the Create Iteration window

  5. In the Name field type Test Iteration and force activate it.

    Create Iteration
  6. Click the work item to see its preview and use it to associate the task to the Test Iteration.

You can now use the Test Iteration in the left panel to track the work item and ensure its completion within the iteration.

8. Using advanced Che features

8.1. Using the code assistant

  1. Return to the Che workspace browser tab. If you closed your earlier workspace tab, use the following instructions:

    1. In CodeReady Toolchain, click the Create tab. The default Codebases view lists your project workspace:

      Existing Workspace
    2. Click Open to view the existing workspace in a new tab. If the new tab does not load, ensure your browser is not blocking pop-up windows.

  2. When the workspace loads, expand the following directory path in the top left panel: src > main > Java > io.openshift.booster.

  3. Double click HttpApplication.java to edit this file.

  4. In the text editor, add a line break at line 9 after the import section.

  5. Type the following in the new line:

    import io.
  6. Press Ctrl+Space to view the autocomplete options for this line. Select any one of the options.

    Code Autocomplete Options
  7. Move the mouse pointer over the red X error icon next to the line number to view the error, which warns you that import is not used.

  8. Delete the added line to clear the error.

You have now learned how the Che workspace uses Code Assistant to make recommendations and identify errors.

To view additional IDE features, click Assistant at the top of the page.

Assistant Menu

8.2. Using the terminal tab

Your Che workspace displays a terminal tab at the bottom of the screen. You can use this terminal to run commands in your private Linux container (your workspace) as follows:

  1. In your Che workspace, if your application is not running, Click the run option (tri run). The following message appears in the terminal tab when the run process completes:

    [INFO] INFO: Succeeded in deploying verticle
  2. Click terminal next to the run tab to view your workspace terminal.

  3. Type the following in the terminal and press Enter to run the commands.

    cat /etc/os-release
    top

    The terminal tab displays the following information about your Linux container:

    Terminal Top Command
  4. Experiment further with the following commands in your terminal tab:

    1. Press Ctrl+c to stop the top command.

    2. Enter the following:

      curl localhost:8080
    3. Enter the following:

      curl localhost:8080/api/greeting
  5. After experimenting with the terminal commands, use the stop icon at the top of the page to stop the application.

    Stop Bar

8.3. Debugging using your Che workspace

After creating your CodeReady Toolchain project, you can debug your application code in the Che workspace. The following is a tutorial using the quickstart project you have already created.

To debug your project code:

  1. Return to your project Che workspace browser tab.

  2. If the HttpApplication.java file is not already loaded, double-click it in your file explorer view (src > main > Java > io.openshift.booster) to view the contents.

  3. In your HttpApplication.java file, add a line break after line 34, then type router. and press Ctrl+Space to see the context-aware assistance.

  4. Scroll down in the displayed list and double-click the get():Route method. This is the Vert.x Router method that maps to the HTTP verb GET. You now have the syntax for the get method.

    Project Directory
  5. Edit the new line to include the goodbye endpoint. The following is an example of the completed new line:

    router.get("/api/goodbye").handler(this::goodbye);
    The completed line shows a red x indicating an error because the referenced goodbye endpoint is not available in the code. This endpoint is added in the next step.
  6. Add a new line after line 74 and then add the following method for the goodbye endpoint:

    private void goodbye(RoutingContext rc) {
      String name = rc.request().getParam("name");
      if (name == null) {
        name = "World";
      }
      JsonObject response = new JsonObject()
        .put("content", "Goodbye " + name);
    
        rc.response()
          .putHeader(CONTENT_TYPE, "application/json; charset=utf-8")
            .end(response.encodePrettily());
    }
  7. Use Ctrl+s (or Cmd+s for macOS) to save your changes.

  8. If your application is already deployed, skip this step. To deploy the application, click the run option (tri run). The following message displays when the run process completes:

    INFO: Succeeded in deploying verticle
  9. In the Terminal tab at the bottom of the page, test the new endpoint by typing the following command:

    curl localhost:8080/api/goodbye

    The following result appears if the changes were successful:

    Terminal Test Result
  10. To stop the application, click the stop button in the EXEC bar on the top of the workspace page.

    EXEC Bar

    When the application stops, the square icon becomes a circular arrow (run stopped).

8.4. Setting up the debugger

To debug your project code, set up the Che workspace Debugger feature:

  1. In your workspace, click the debug option in the debug button.

    Debugger Button
  2. In the new debug tab in the Processes pane at the bottom of the screen, look for the following lines when the debugging starts and wait for the process to complete:

    [INFO] The application will wait for a debugger to attach on debugPort 5005
    
    [INFO] Launching Vert.x Application
    
    [INFO] Listening for transport dt_socket at address: 5005
  3. From the menu bar, click Run and select Edit Debug Configurations.

    Edit Debug Configuration
  4. In the Debug Configurations dialog box:

    1. In the left pane, click + for the JAVA item in the dialog box to add a Remote Java port.

    2. In the right pane, change the Port value to 5005.

    3. Click Save and then Close.

  5. To create a new breakpoint for your method:

    1. In the HttpApplication.java file, go to the following line of code at line 77:

          if (name == null) {
    2. Click the line number (77 in the margin) for this line of code:

  6. Click the debug icon (debug icon) at the bottom left corner of the workspace to verify that the breakpoint is added.

The Breakpoints pane at the bottom left corner of the screen lists all added breakpoints named after the file they are added in and then the line number. For example, your new breakpoint is listed as the following:

HttpApplication.java:77

The Debugger is now set up for your project.

8.5. Running the debug command

Now that you have set up the Debugger for your project, you can use the debug command as follows:

  1. In your workspace tab, in the top menu bar options, click Run  Debug  Remote Java. A success message displays when the remote debugger connects.

    Successful Connection to Remote Debugger
    If your remote debugger connection fails, restart your browser and try again.
  2. In the top menu bar options, click Run  Terminal to view the terminal tab.

  3. Run the following command in the terminal to start debugging:

    curl localhost:8080/api/goodbye
  4. Click the debug icon (debug icon) at the bottom left corner of the workspace. The Variables panel on the bottom right side of the screen lists your debugger variables.

You can explore the debugger features by using the Resume, Step Into, Step Over, and Step Out options during the debugging process. When finished, close the workspace tab and return to the CodeReady Toolchain tab.

9. Optimizing your memory usage

After creating your first quickstart project, you can edit the project code to optimize your memory usage as follows:

  1. Review the resource usage details for your project.

  2. Reduce your quickstart project’s memory usage and commit the changes.

  3. Compare the change in your OpenShift Online memory quota usage.

9.1. Reviewing detailed resource information in OpenShift Online

The memory allowances for each OpenShift pod is 512 MiB. As a result, each application consumes nearly 1 GiB of memory for the Stage and Run environments.

To check your resource information details in OpenShift:

  1. In a new browser tab, navigate to the OpenShift Online console at console.starter-us-east-2.openshift.com.

  2. From the list of projects at the right side of the page, click username-run to see the resources used for the Run environment or username-stage to see the resources for the Stage environment.

    Select the Run Project

    See Viewing projects in OpenShift Online for details about the listed projects.

  3. Click Applications and then select Pods in the displayed submenu.

    Application Pods
  4. The Pods page lists your Hello World project pod. Click the project name to see the resource information for the project.

    Hello World Project Pod
  5. The Details page lists the Status of the pod and the container resource information:

    Resources

    Use this page to review the memory usage for your CodeReady Toolchain project. Note this information and leave this tab open to compare the resource information after optimizing your memory usage.

Save the details to compare after following the steps in Reducing project memory usage.

9.2. Reducing project memory usage

Optimizing memory usage is important when using the Free Tier of OpenShift Online because this tier provides limited memory. Also, each additional project in CodeReady Toolchain requires an additional share of your OpenShift Online resources.

You can optimize your new quickstart to use less memory as follows:

  1. Return to your CodeReady Toolchain workspace tab. If you need to reopen the workspace:

    1. In your CodeReady Toolchain browser tab, click Create and then Codebases.

    2. Ensure that the workspace is selected in the drop-down list and click Open to run your workspace.

      Reopen workspace
  2. In the workspace file explorer panel, double-click your project and navigate to src > main > fabric8.

    Fabric8 folder
  3. Right-click the fabric8 folder and select New  File.

  4. Name the new file deployment.yml and click OK. The new file displays in the editor.

  5. Copy the contents of the following file to your new YAML file: deployment.yaml.

    Spaces are meaningful in YAML files. Ensure that you copy the correct spacing into your YAML file from the link.
  6. Use Ctrl+s (or Cmd+s for macOS) to save your changes.

9.3. Committing and pushing changes to GitHub

After making the required changes to your code, commit and push the modifications to your project GitHub repository.

Before committing your changes, ensure that your project pipeline build is promoted and at the Rollout to Run stage.
  1. In your Che workspace, click Git from the menu bar options and select Commit from the displayed options.

  2. In the Commit to repository dialog box:

    1. If they are not already, select all the changed and new files to add them to the commit.

    2. Add a commit message describing your changes.

    3. Select the Push committed changes to check box.

    4. Click Commit.

When the commit succeeds, the following message displays:

Pushed to origin

You have now committed your code changes to GitHub.

9.4. Viewing your detailed OpenShift Online quota usage

After committing your changes, view the resource details for your project again in OpenShift Online. Use the following instructions to see these details:

  1. Click Create and then Pipelines to view the new pipeline build. Committing and pushing your new YAML file triggers a new pipeline build for your CodeReady Toolchain project. Allow several minutes for the pipeline build to roll out to Stage.

  2. After the pipeline build is ready, return to the OpenShift Online console browser tab to review the optimized memory usage for your Hello World project:

    Optimizing Hello World Memory Usage
  3. Promote the application to the Run environment.

    You can now compare these details to the details in Reviewing detailed resource information in OpenShift Online to see the resource usage improvements.

  4. You have now completed the task, Optimize CodeReady Toolchain resource usage, in the Test Iteration. Navigate to the Plan tab and ensure that you change the state of the work item to Closed.

10. Importing an existing codebase from GitHub

This section contains instructions for adding an existing project to CodeReady Toolchain.

10.1. Forking an example repository

In addition to creating applications using quickstarts, you can import an existing project into CodeReady Toolchain as follows:

  • You can fork any one of the sample repositories in GitHub. For this tutorial, fork and use the vertx-eventbus repository.

Sample repositories available in Github:

If needed, you can import multiple projects into CodeReady Toolchain simultaneously, but this can result in a 12-15 minute delay. Import one project at a time to avoid delays.

The OpenShift Online Free Tier provides two pods, and each project requires one pod.

10.2. Creating a new space

In CodeReady Toolchain, the first step for any new project is to create a new space with a unique name. You can then create or import codebases within the space, add collaborators, and plan your work using work items and iterations.

Procedure

Create a new space as follows:

  1. In the CodeReady Toolchain home page, click Create a space in the Recent Spaces section. If your account has an existing space, click + to create an additional space.

  2. In the Create a New Space dialog box, type mynewspace as the unique name for your space and click Ok.

    Create new space

You have now created your first space.

10.3. Importing your codebase

After creating a space, use the Create an Application wizard to import an existing codebase to create a new application. If you closed the wizard earlier, click Add to space in the upper-right corner of your space dashboard.

  1. In the Name your application field, type a unique name for your new application.

  2. Select the Import an existing codebase radio button and then click Continue to import an existing project codebase into CodeReady Toolchain.

  3. In the Authorize Git Provider step:

    1. Click the Location drop-down to select the location of your codebase. The default option is your personal GitHub account name.

    2. In the Repository field, click Select Repository to select the repository from which you want to import the codebase.

    3. Click the blue arrow at the bottom of the screen to continue.

  4. In the Select pipeline step, select an option for your pipeline build, then click the blue arrow to continue to the next step. We recommend using the first option for most use cases because it provides an end to end pipeline that is suitable for most projects.

  5. The Confirm Application Summary & Import step displays a summary for your imported code. Review the information and click Import Application to confirm. The progress screen displays when the code is successfully imported.

  6. Click View New Application to continue when all the steps have a green check mark next to them.

You have now imported the code from your existing repository to CodeReady Toolchain.

10.4. Creating a Che workspace

To edit your application codebase, create a new Che workspace:

  1. Click Create from the top of the CodeReady Toolchain page. The default view for this tab is Codebases.

  2. In the WORKSPACES column, click Create workspace for your project. The workspace gets created.

  3. Click Open next to the workspace to see your Che workspace in a new browser tab.

    If a new tab does not appear, see enable_popups for troubleshooting information.

    As the workspace loads the codebase for your application, the Workspace Status window at the bottom of the Che workspace tab displays the progress:

    Workspace loading
    If the Workspace Status shows Stopped, click Start in the Workspace is not running pane at the top, to restart your workspace.

    When loaded and ready to use, the new Che workspace tab displays the following confirmation message:

    Workspace Running success message

10.5. Running your project in the Che workspace

After your Che workspace loads, you can see your project code listed in the file explorer panel, in the upper-left side of the screen.

  1. Click the run option from the Run button (tri run). Maven then downloads the required dependencies, compiles the application, and starts the verticle (Vert.x uses this name for deployed code). For Vert.x projects, this also sets up the server and hot deploy options. The hot deploy option automatically updates the application when you make a change.

    If the Run command macro is not defined, it displays the Create run command option instead of Run:

    Create run command

    See create_run_command_macro for instructions on setting up a run command.

  2. A run terminal appears at the bottom pane of the Che workspace. When the mvn build command finishes executing, the run view displays the following message:

    [INFO] INFO: Succeeded in deploying verticle
  3. Click the blue preview URL at the top of the run view to see your application running in Che.

    Run project link
  4. In the application, enter a name in the Name field and click Invoke to test the application.

    Testing the application

    This is the same version of the application that the pipeline deployed to Stage and you subsequently promoted to Run. The URL for this build of the application is different from the URLs used by OpenShift Online for Stage and Run. This is your private sandbox hosted within Che. You can still share this URL with others and interactively debug the application while they run it in their browser.

10.6. Changing the project code

The example project code includes a new route for eventbus and its supporting method. The project sets up eventbus to only allow outbound communications for the my-feed channel. Messages arriving in the my-feed channel are pushed to the browser using the SockJS bridge. This project includes a vertx-eventbus.js file along with the index.html file and also includes tweaks to the index.html file.

Change the code of your project and preview the results as follows:

  1. In the file directory view, double-click the following directories to expand them: src > main > Java> io.openshift.booster > HttpApplication.java.

    Folder View
  2. Double click the HttpApplication.java file to open it and find the following line:

      protected static final String template = "Aloha, %s!";
  3. Add exclamation marks to the string. The line should now be:

      protected static final String template = "Aloha !!!, %s!";
  4. Save the changes (Ctrl+s or Cmd+s for macOS).

    If you already ran the application earlier as instructed in Running your project in the Che workspace, your changes are instantly implemented. Maven uses the Vert.X hot deploy feature to automatically update the application when you make a change.

  5. Return to the browser tab running the application, type a name in the text box and click Invoke to test the application.

    Test Application

You have now changed your application code and tested the change.

10.7. Committing and pushing changes to GitHub

After making the required changes to your code, commit and push the modifications to your project GitHub repository.

Before committing your changes, ensure that your project pipeline build is promoted and at the Rollout to Run stage.
  1. In your Che workspace, click Git from the menu bar options and select Commit from the displayed options.

  2. In the Commit to repository dialog box:

    1. If they are not already, select all the changed and new files to add them to the commit.

    2. Add a commit message describing your changes.

    3. Select the Push committed changes to check box.

    4. Click Commit.

When the commit succeeds, the following message displays:

Pushed to origin

You have now committed your code changes to GitHub.

10.8. Reviewing and publishing your changes

When you commit and push a change to GitHub, a pipeline build is automatically triggered in CodeReady Toolchain.

To review the build and publish your changes:

  1. Return to the CodeReady Toolchain browser tab.

  2. Click Create and then Pipelines to view the build pipelines. Wait for the build pipeline to progress to the Approve stage.

  3. In the Create tab, click Deployments to see the following information:

    Versions of the Application
    • Different versions of your application are now deployed to Stage and Run. Version 1.0.2 of the application, which includes your committed change to the code, is deployed to Stage because you have not yet promoted it to Run. The older version, 1.0.1 , is deployed to Run because you approved it the last time the pipeline build executed.

    • The green check marks indicate that both builds are operational.

    • The 1 pod indicates that each of the application builds scale to one pod in OpenShift Online. The number of pods indicates the number of running instances of the application.

    • The version numbers link to individual running applications. You can use these separate staging areas to share different versions of your application before promoting a change. Click the version numbers to view the details for that deployment.

  4. Click Pipelines to return to the pipelines view and click Input Required at the Approve stage of the pipeline.

  5. Click Promote to promote version 1.0.2 of the application to Run.

    Your changes are now available on both Stage and Run. If you return to the Deployments tab, you can see that version 1.0.2 is deployed to both Stage and Run.

You have now imported an existing project into CodeReady Toolchain, made changes to your project code, committed the changes to GitHub, and published the new version of your project.

11. Next steps

If you followed the instructions in this document, you have now learned about CodeReady Toolchain and its features. You are now able to:

You can now try using what you have learned about CodeReady Toolchain with your own projects. See the CodeReady Toolchain User Guide for comprehensive information about CodeReady Toolchain and its features. If you have any questions or suggestions for improvement with CodeReady Toolchain or this document, let us know using one of the methods listed in Getting help and giving feedback.

12. Troubleshooting

The following section lists the common issues you may face when using CodeReady Toolchain and the workarounds to resolve them. For further information also see the Frequently asked questions.

12.1. Login issues

When logging in to CodeReady Toolchain, an error about an account already existing with your email address can display.

Login error

If you encounter this issue, the workaround is to log in using your username instead of your email address.

12.2. Enable popups

If a new tab does not appear, your browser is blocking the pop-up window that displays the new workspace. To resolve this, allow pop-up windows from https://openshift.io. In Chromium-based browsers, do the following:

  1. Click the blocked pop-up window icon in the URL field of your browser.

  2. Select the Always allow pop-ups from https://openshift.io option, and click Done.

    Blocked Pop Up
  3. Now, click Open again to load the workspace.

12.3. Application not available error

When you click Rollout to Stage or Rollout to Run, a new browser tab displays your application.

If the new tab displays a Application is not available error message (see screen capture), the application is not yet ready.

Application Does Not Exist Error

To fix this issue, wait several minutes and then refresh the page. The application then loads as expected.

12.4. Pipeline build failure

Occasionally, a pipeline build can fail due to a network connectivity issue with Maven. This displays a red line and cross in the Pipeline Build information as seen in the following screen capture:

Pipeline build failure

If you click View Log for the failed build, the build log includes error information such as the following:

[INFO] --- fabric8-maven-plugin:3.5.38:resource (fmp) @ test4 ---
Mar 22, 2018 2:54:10 PM org.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec execute
INFO: I/O exception (java.net.SocketException) caught when processing request to {s}->https://repo1.maven.org:443: Connection reset
Mar 22, 2018 2:54:10 PM org.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec execute
INFO: Retrying request to {s}->https://repo1.maven.org:443
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 50.518 s
[INFO] Finished at: 2018-03-22T14:54:12+00:00
[INFO] Final Memory: 22M/29M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.fabric8:fabric8-maven-plugin:3.5.38:resource (fmp) on project test4: Execution fmp of goal io.fabric8:fabric8-maven-plugin:3.5.38:resource failed: Plugin io.fabric8:fabric8-maven-plugin:3.5.38 or one of its dependencies could not be resolved: Could not transfer artifact io.fabric8:kubernetes-model:jar:2.0.4 from/to central (https://repo1.maven.org/maven2): GET request of: io/fabric8/kubernetes-model/2.0.4/kubernetes-model-2.0.4.jar from central failed: Connection reset -> [Help 1]

To resolve this issue, restart the pipeline build as follows:

  1. Click the additional options icon (kabob white) at the right side of the build.

  2. From the displayed options, select Start Pipeline.

    Manually start pipeline

The pipeline restarts and successfully completes.

12.5. Create run command macro

If your Che workspace does not already include a run command macro, clicking the Run icon displays a Create run command option:

Create run command

To create the run command:

  1. Click Create run command.

  2. Add the following information for the new command:

    1. In the Name field, type run to name the new command shortcut.

    2. In the command box, type the following command:

      scl enable rh-maven33 'mvn compile vertx:run -f ${current.project.path}'
    3. Toggle the Applicable option to YES to enable this macro for your project.

      Add details create run
  3. Click RUN on the right side of the screen to run your new macro.

    Run macros
  4. In the Terminal view at the bottom of the workspace, the command runs. When successfully complete, the command displays the following message:

    [INFO] INFO: Succeeded in deploying verticle
  5. Click SAVE to save your new macro.

    Save macro
  6. In any order, click the filesystem icon and the X icon for the run tab to close the macros options:

    Filesystem icon

You have now set up your run macro. If you click the run option at the top of your screen, it displays the new macro (tri run).

12.6. CodeReady Toolchain Frozen on Chrome

When using CodeReady Toolchain with Chrome, if the browser window freezes at any point, press Shift+Ctrl+r for a hard refresh. This reloads CodeReady Toolchain and resolves the problem.