Red Hat Training

A Red Hat training course is available for OpenShift Online

Chapter 4. Basic Walkthrough

4.1. Overview

This guide demonstrates how to get a simple project up and running on OpenShift Online.

The following sections guide you through creating a project that contains a sample Node.js application that will serve a welcome page and the current hit count (stored in a database) using the OpenShift Online web console. This involves creating two pods:

  • one to host the Node.js application
  • one to host the MongoDB database

The tutorial assumes that you have:

  • an OpenShift Online account.
  • a GitHub account.
  • Git installed locally.

4.2. Setup

In this section, you will fork the OpenShift Node.js sample application on GitHub and clone the repository to your local machine so that you can deploy and edit the app.

  1. On GitHub, navigate to the openshift/nodejs-ex repository. In the top-right corner of the page, click Fork:

    Fork the project

  2. Next, execute the following commands on your local machine to clone the sample application and change to the new directory: 

    $ git clone https://github.com/<your_github_username>/nodejs-ex
$ cd nodejs-ex

That’s it! Now, you have a fork of the original openshift/nodejs-ex example application Git repository and a copy on your local machine.

4.3. Get Oriented with the Web Console

Visit the Web Console topic to learn about its components.

4.4. Creating a New Application

In this section, you will deploy your first application to OpenShift Online using the web console.

  1. Navigate to the welcome page of the OpenShift Online web console and click Create Project to create your first project:

    Note

    OpenShift Online Starter only allows you to create a single project at this time. If you already have a project, you must delete it in order to continue.

    To delete your existing project, click the trash can icon next to the project name on the welcome page:

    Delete projects

  2. Replace my-project with a unique name for your project, such as <your_github_username>-example. You can leave the display name and description blank.

    New projects

  3. Click on the JavaScript option:

    Browse the catalog

  4. Select the nodejs-mongodb-example Quickstart template:

    Select Quickstart templates

  5. On the next screen, replace the user name in the Git Repository URL parameter with your GitHub user name. Use the default values provided for all other parameters:

    Change Git URL

  6. Finally, scroll to the bottom of the page and click Create to deploy your application.

    Note

    You can follow along on the Overview page of the web console to see the new resources being created, and watch the progress of the build and deployment. While the MongoDB pod is being created, its status is shown as pending. The MongoDB pod then starts up and displays its newly-assigned IP address.

4.5. Configuring Automated Builds

In this section, you will configure a GitHub webhook to automatically trigger a rebuild of your application whenever you push code changes to your forked repository. This involves adding the Github webhook URL from your application into your Github repository. You obtain this webhook from these locations:

  • At the bottom of Next Steps page shown after creating your app, you will see a section titled Making code changes. Copy the payload URL from the bottom of the page and follow the link to the GitHub project webhook settings page provided:

    Copy webhook

  • In the OpenShift Online web console:

    1. Navigate to the project containing your application.
    2. Click the Browse tab, then click Builds, then click the name of the build for your Node.js application.
    3. From the Configuration tab, click copy next to GitHub webhook URL to copy your GitHub webhook.

Next, add the webhook to the Github repository:

  1. In GitHub, click Add webhook in the GitHub Webhook settings for your project. Paste the payload URL into the Payload URL field. Ensure Content type field is set to application/json instead of the default application/x-www-form-urlencoded. Then, click Add webhook to finish adding the webhook to your project:

    Add webhook

  2. GitHub now attempts to ping the OpenShift Online server to ensure that communication is successful. If it is correctly configured, you will see a green check mark next to your new webhook URL in GitHub. Hover your mouse over the check mark to see the status of the last delivery:

    Successful delivery

The next time you push a code change to your forked repository, your application will automatically rebuild.

4.6. Viewing Your Running Application

In this section, you will view your running application using a web browser.

In the web console, view the Overview page for your project to determine the web address for your application. Click the web address displayed underneath the NODEJS-MONGODB-EXAMPLE service to open your application in a new browser tab:

Running Node.js app
Note

You can find all routes configured for your project at any time in the web console:

  1. From the web console, navigate to the project containing your application.
  2. Click the Browse tab, then click Routes.
  3. Click the host name to open your application in a browser new tab.

4.7. Pushing a Code Change

In this section, you will learn how to push a local code change to the application.

  1. On your local machine, use a text editor to open the sample application’s source for the file nodejs-ex/views/index.html.

  2. Make a code change that will be visible from within your application. For example, change the title on line 219:

    Make a code change

  3. Commit the changes in Git, and push the change to your GitHub repository: 

    $ git add views/index.html
$ git commit -m “Updates heading on welcome page”
$ git push origin master
  4. If your webhook is correctly configured, your application will immediately rebuild itself based on your changes. View your application using a web browser to see your changes.

Now going forward, all you need to do is push code updates and OpenShift Online handles the rest.

4.8. Scaling the Application

Important

OpenShift Online Starter users are unable to scale applications. Only OpenShift Online Pro users have this ability.

In this section, you will add additional instances of your Node.js service so that your application can handle additional traffic volume.

  1. In the web console, view the Overview page for your project. Click the up arrow under the NODEJS-MONGODB-EXAMPLE service to add an additional replica of your Node.js application:

    Scaling an app

The nodejs-mongodb-example Quickstart is configured to use 512 MiB of memory per pod. Your OpenShift Online Pro quota will allow up to 3 replicas of the nodejs-mongodb-example pod in addition to the MongoDB database (for a total of 2 GiB).

You can check your quota usage at any time in the web console:

  1. From the web console, navigate to the project containing your application.
  2. Click the Settings tab and scroll to the section titled Quota compute-resources to view usage:
Quota

4.9. Next Up: Beyond the Basics

Next, we’ll go beyond the basics using the OpenShift Online CLI to compose this same application using individual images.