Creating a new application usingCodeReady Toolchain codebases

Red Hat Developers Documentation Team

2018-12-20 14:15:48 UTC

Table of ContentsCreating a new space and a new Vert.x quickstart application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2

1. Creating a new space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

2. Creating a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

3. Reviewing your staged application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

4. Approving your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

5. Viewing the build pipeline logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

6. Viewing your application deployment details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

7. Viewing your codebase in GitHub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

8. Viewing your OpenShift Online projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

9. Creating a Che workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

10. Running your project in the Che workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

11. Changing the quickstart code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18

12. Committing and pushing changes to GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

13. Reviewing and publishing your changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21

This document describes the creation of a Vert.x quickstart application usingCodeReady Toolchain provided codebases. These codebases lay the foundationand provide the source code and specifications for you to create a newapplication.

Creating a new space and a newVert.x quickstart applicationAfter creating an account, you must create a Space to add or create a project.

Chapter 1. Creating a new spaceIn CodeReady Toolchain, the first step for any new project is to create a new space with a uniquename. You can then create or import codebases within the space, add collaborators, and plan yourwork 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. Ifyour 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 andclick [ Ok ].

You have now created your first space.

Chapter 2. Creating a new applicationWhen you create a new space, the Create an Application wizard to add or import codebasesdisplays. If you closed the wizard earlier, click [ Add to space ] in your space dashboard to see thewizard again. Use this wizard to create a new quickstart application as follows:

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:

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

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

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

4. In the Select Pipeline section, select the first option, then click the blue arrow to continue to thenext step.

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

6. The next screen displays a summary of your application options. Scroll down in your browser toview the Application Information section. For this example, do not edit these options. Ifdesired, you can change the Application Name, Version, and Group ID for your newapplication at this step.

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 detailedstack analysis report, and the codebase you added.

◦ View your continuous integration pipelines

◦ Edit your application codebase in Che web IDE.

For this example, click [ View Pipeline ] to see your application. Your new Vert.X applicationis 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 thelinked GitHub account. It has also hosted the pipeline for the project in OpenShift Online.

Chapter 3. Reviewing your stagedapplicationWhen you create a new codebase, the selected pipeline pushes version 1.0.1 of your newapplication into the Stage environment, and then awaits your approval to deploy into the Runenvironment.

Stage and Run are individual OpenShift projects. Stage is a production staging area to review andtest 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 clickPipelines 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 isset, the build is started, and then released. Next, the pipeline build pushes the application tostage and it displays at the Approve stage. This process takes a few minutes.

If your pipeline build does not start for more than ten minutes, you canmanually start a pipeline build using the instructions atpipeline_build_failure.

2. Click the icon ( ) next to Rollout to Stage in the displayed pipeline. OpenShift Online providesthis public URL to access the staged quickstart application.

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

If the application does not load, see application_not_available fortroubleshooting information.

3. To test the application, enter a name in the Name field and click [ Invoke ]. The Result fielddisplays the JSON result returning from the API.

Chapter 4. Approving your applicationIf the quickstart application in the Stage environment runs as expected, approve your applicationand promote it to the Run environment:

1. Return to the CodeReady Toolchain tab which displays the Pipeline view and click [ InputRequired ] at the Approve stage of the pipeline.

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

3. Optionally, as your application is promoted to Run, click helloworldvertx or Build #1 to viewthe 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 inthe Run environment, click the icon ( ) next to Rollout to Run to view the application in anew tab.

Chapter 5. Viewing the build pipeline logsOptionally, 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 ifrequired.

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 notdisplay, wait for a few minutes for the Jenkins instance to initialize and try again. Once you arelogged in, the page displays the logs for your pipeline build.

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.

Chapter 6. Viewing your applicationdeployment detailsYou can see a detailed view of your application pods in the stage and run environments, resourcesconsumed in the two environments, and the overall resources used by the application in theDeployments 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 resourcesconsumed in the stage and run environments respectively. The Resource Usage at the bottomof the screen displays the overall resources used by your applications in CodeReady Toolchain.

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

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

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

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

Chapter 7. Viewing your codebase in GitHubAfter reviewing your pipeline build running in CodeReady Toolchain and OpenShift Online, viewyour application codebase in GitHub as follows:

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

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

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

Chapter 8. Viewing your OpenShift OnlineprojectsTo view all the OpenShift Online projects that support your application, navigate to My Projects inthe OpenShift Online Console.

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 thename 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. Clickthis 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 environmentfor experimenting with your OpenShift pods and monitoring the memory usage for yourapplication.

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

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

Chapter 9. Creating a Che workspaceTo 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 isCodebases.

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

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

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

If the Workspace Status shows Stopped, click [ Start ] in the Workspace isnot running pane at the top, to restart your workspace.

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

Chapter 10. Running your project in the CheworkspaceAfter your Che workspace loads, you can see your project code listed in the file explorer panel, inthe upper-left side of the screen.

1.

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

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

See create_run_command_macro for instructions on setting up a runcommand.

2. A run terminal appears at the bottom pane of the Che workspace. When the mvn buildcommand 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.

4. In the application, enter a name in the Name field and click [ Invoke ] to test the application.

This is the same version of the application that the pipeline deployed to Stage and yousubsequently promoted to Run. The URL for this build of the application is different from theURLs used by OpenShift Online for Stage and Run. This is your private sandbox hosted withinChe. You can still share this URL with others and interactively debug the application while they

run it in their browser.

Chapter 11. Changing the quickstart codeTo change your project code and preview the results:

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

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 Cheworkspace, your changes are instantly implemented. Maven uses the Vert.X hot deploy featureto 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.

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

Chapter 12. Committing and pushingchanges to GitHubAfter making the required changes to your code, commit and push the modifications to your projectGitHub repository.

Before committing your changes, ensure that your project pipeline build ispromoted and at the Rollout to Run stage.

1. In your Che workspace, click Git from the menu bar options and select Commit from thedisplayed options.

2. In the Commit to repository dialog box:

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

b. Add a commit message describing your changes.

c. Select the Push committed changes to check box.

d. Click [ Commit ].

When the commit succeeds, the following message displays:

You have now committed your code changes to GitHub.

Chapter 13. Reviewing and publishing yourchangesWhen you commit and push a change to GitHub, a pipeline build is automatically triggered inCodeReady 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 toprogress to the Approve stage.

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

◦ Different versions of your application are now deployed to Stage and Run. Version 1.0.2 ofthe application, which includes your committed change to the code, is deployed to Stagebecause you have not yet promoted it to Run. The older version, 1.0.1 , is deployed to Runbecause 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 separatestaging 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 Approvestage 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.