1. Documentation
    2. history bug_report picture_as_pdf
×

Basic Walkthrough

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.

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.

Get Oriented with the Web Console

Visit the Web Console topic to learn about its components.

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:

    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.

    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.

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.

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: