This document describes the creation of a Vert.x quickstart application using CodeReady Toolchain provided codebases. These codebases lay the foundation and provide the source code and specifications for you to create a new application.

Creating a new space and a new Vert.x quickstart application

After creating an account, you must create a Space to add or create a project.

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.

2. 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 project 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 downward 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.

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

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

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

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

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

Now that you have created a project, you can edit the code and stage the changes.

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

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

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

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