Getting Started

OpenShift Enterprise 3.1

Getting Started with OpenShift 3.1

Red Hat OpenShift Documentation Team

Abstract

Whether you are a developer or a platform administrator, you can get started with OpenShift using the topics in this book. Administrators can use the installation utility and an interactive CLI tool, to quickly install and configure a new OpenShift instance across multiple hosts. Developers can use the OpenShift CLI or the web console to log in to an existing OpenShift instance and start creating applications.

Chapter 1. Overview

To get started with OpenShift, find the appropriate topic based on your role:

I am a…​Links to relevant topics

Platform administrator

Quick Install

Developer

Create a project using the web console

Chapter 2. Developers

2.1. Getting Started for Developers: Web Console

2.1.1. Overview

This getting started experience walks you through the simplest way to get a sample project up and running on OpenShift Enterprise. 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.

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

Note

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.

2.1.2. Before You Begin

Before you can get started:

2.1.3. Browser Requirements

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

2.1.4. Tutorial Video

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

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

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

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

    Note

    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.

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

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

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

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

Chapter 3. Getting Started for Administrators

See the quick installation method to use an interactive CLI tool that allows you to install and configure a new trial OpenShift Enterprise instance across multiple hosts.

Chapter 4. Revision History: Getting Started

4.1. Mon Apr 18 2016

Affected TopicDescription of Change

Getting Started for Developers: Web Console

Added a Browser Requirements section, which points to the full browser requirements.

4.2. Thu Nov 19 2015

OpenShift Enterprise 3.1 release.

Legal Notice

Copyright © 2018 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.