1. Documentation

Developers: Web Console Walkthrough

Overview

This getting started experience walks you through the simplest way to get a sample project up and running on OpenShift Origin. 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 Origin version 3 (v3), you might want to start by reading about what’s new. This version of OpenShift Origin is significantly different from version 2 (v2).

OpenShift Origin 3 provides out of the box a set of languages and databases for developers with corresponding implementations and tutorials that allow you to kickstart your application development. Language support centers around the Quickstart templates, which in turn leverage builder images.

Language Implementations and Tutorials

Ruby

Rails

Python

Django

Node.js

Node.js

PHP

CakePHP

Perl

Dancer

Java

Other images provided by OpenShift Origin include:

To help illustrate constructing such applications, 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).

This topic discusses both Quickstart and Instant App templates and applications. Quickstarts provide a starting point for application development, but they rely on your development to create a useful application. In contrast, Instant Apps like Jenkins are instantly usable.

Before You Begin

Before you can get started:

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

Web Console Getting Started Experience

Forking the Sample Repository

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

    This topic follows the Ruby example, but you can follow along using any of the language examples provided in the OpenShift Origin GitHub project.

  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 Origin begins the build process and creates a new deployment.

  1. Visit the OpenShift Origin 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

The Select Image or Template page gives you the option to create from a publicly accessible git repository, or from a template:

  1. If creating a new project did not automatically redirect you to the Select Image or Template page, you might need to click Add to Project.

  2. Click Browse, then select ruby from the drop-down list.

  3. Click the ruby:latest builder image.

  4. Type a name for your application, and specify the Git Repository URL, which is https://github.com/<your_github_username>/ruby-ex.git.

  5. Optionally, click Show advanced routing, build, and deployment options, though by default this example application automatically creates a route, webhook trigger, and build change triggers.

  6. Click Create.

    After creation, some of these settings can be modified from the web console by clicking Browse, Builds, select your build, then click Actions, and either Edit or Edit YAML.

Creating your application might take some time. 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 Ruby pod is being created, its status is shown as pending. The Ruby pod then starts up and displays its newly-assigned IP address. When the Ruby 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, under SERVICE: RUBY-EX you should see something similar to: ruby-ex-my-test.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 Origin 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 your build name, then click the Configuration tab.

  4. Click Copy next to GitHub webhook URL to copy your webhook payload URL.

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

  6. Click Webhooks & Services.

  7. Click Add webhook.

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

  9. Click Add webhook to save.

GitHub now attempts to send a ping payload to your OpenShift Origin server to ensure that communication is successful. If you see see a green check mark appear next to your webhook URL, then it is correctly configured. 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 ruby-ex/config.ru

  2. Make a code change that will be visible from within your application. For example: on line 229, change the title from Welcome to your Ruby application on OpenShift to This is my Awesome OpenShift Application, then save your changes.

  3. Commit the change 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. Once the rebuild is successful, view your updated application using the route that was created earlier.

Now going forward, all you need to do is push code updates and OpenShift Origin 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 Start Build.