OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Getting Started for Developers: Web Console

Overview

This getting started experience walks you through the simplest way to get a sample project up and running on OpenShift. There are a few different ways to launch images within a project, but this topic focuses on the quickest and easiest method.

If this is the first part of the documentation you have read, and you are unfamiliar with the core concepts of OpenShift version 3, you might want to start by reading about what’s new. This version of OpenShift is significantly different from version 2.

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

Before You Begin

Before you can get started using OpenShift Enterprise:

  • You must be able to access a running instance of OpenShift Enterprise. If you do not have access, then contact your cluster administrator.

  • Your instance must be pre-configured by a cluster administrator with the InstantApp templates and builder images. If they are not available, direct your cluster administrator to the First Steps topic.

  • You must have an account on GitHub, have Git set up, and set up authentication to GitHub from Git.

  • You must have the OpenShift CLI downloaded and installed.

Browser Requirements

Review the browser versions and operating systems that can be used to access the web console.

Tutorial Video

The following video walks you through the rest of this topic: Click here to watch

Forking the Sample Repository

  1. Visit the Node.js example page while you are logged in to GitHub.

  2. Fork the repository.

    You are redirected to your new fork.

  3. Copy the clone URL for your fork.

  4. Clone the repository to your local machine.

Creating a Project

To create an application, you must first create a new project, then select an InstantApp template. From there, OpenShift begins the build process and creates a new deployment.

  1. Visit the OpenShift web console in your browser. The web console uses a self-signed certificate, so if prompted, continue past a browser warning.

  2. Log in using the username and password recommended to you by your administrator.

  3. To create a new project, click New Project.

  4. Type a unique name, display name, and description for the new project.

  5. Click Create.

    The web console’s welcome screen loads.

Creating an Application

  1. To create a new application, click Add to Project.

    The Add to Project page loads, and gives you the option to create from a publicly accessible git repository, or from a template.

  2. Click the nodejs-mongodb-example template.

    The template configuration page loads, displaying pre-configured parameters.

  3. Click Edit Parameters, then update the source repository URL to your forked repository: https://github.com/<your_github_username>/nodejs-ex.git

  4. Type a secret in the GITHUB_WEBHOOK_SECRET field. This webhook secures the trigger that causes your application to automatically rebuild whenever you push a code change to your forked repository.

  5. Click Create.

    After creation, these settings can only be modified from the CLI by using the oc command.

Your application is then created, which might take some time. In the case of this template, MongoDB is created first, then the Node.js application is built using the OpenShift source-to-image (S2I) builder.

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.

When the Node.js pod is running, the build is complete.

Viewing the Running Application

If your DNS is correctly configured, then your new application can be accessed using a web browser. If you cannot access your application, then speak with your system administrator.

To view your new application:

  1. In the web console, view the overview page to determine the web address for the application. For example: http://nodejs-mongodb-example.openshiftapps.com

  2. Visit the web address for your new application.

Configuring Automated Builds

You forked the source code for this application from the OpenShift GitHub repository. Therefore, you can use a webhook to automatically trigger a rebuild of your application whenever you push code changes to your forked repository.

To set up a webhook for your application:

  1. From the Web Console, navigate to the project containing your application.

  2. Click the Browse tab, then click Builds.

  3. Click Copy to copy your GitHub webhook.

  4. Navigate to your forked repository on GitHub, then click Settings.

  5. Click Webhooks & Services.

  6. Click Add webhook.

  7. Paste your webhook URL into the Payload URL field.

  8. In the Secret field, type the secret you chose when creating your application.

  9. Click Add webhook to save.

GitHub now attempts to ping the OpenShift 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. Hover your mouse over the check mark to see the status of the last delivery.

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

Writing a Code Change

To work locally and then push changes to your application:

  1. On your local machine, use a text editor to change 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: on line 219, change the title from Welcome to your Node.js application on OpenShift to This is my awesome Node.js application on OpenShift, then save your changes.

  3. Commit the changes in git, and push the change to your fork.

    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 all you need to do is push code updates, and OpenShift handles the rest.

Manually Rebuilding Images

You may find it useful to manually rebuild an image if your webhook is not working, or if a build fails and you do not want to change the code before restarting the build. To manually rebuild the image based on your latest committed change to your forked repository:

  1. Click the Browse tab, then click Builds.

  2. Find your build, then click Rebuild.