Getting Started

OpenShift Container Platform 3.5

Getting Started with OpenShift Container Platform 3.5

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 Container Platform, find the appropriate topic based on your role:

I am a…	Links to relevant topics
Platform administrator	Quick Install
Developer	Step through a basic walkthrough using the web console and create your first project and application.

Chapter 2. Developers: Web Console Walkthrough

2.1. Overview

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

OpenShift Container Platform 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 Container Platform include:

In addition, JBoss Middleware has put together a broad range of OpenShift Container Platform templates as well as images as part of their xPaaS services.

The technologies available with the xPaaS services in particular include:

Java EE 6 Application Server provided by JBoss EAP 6
Integration and Messaging Services provided by JBoss Fuse and JBoss A-MQ
Data Grid Service provided by JBoss Data Grid
Real Time Decision Service provided by JBoss BRMS
Java Web Server 3.0 provided by Tomcat 7 and Tomcat 8

With each of these offerings, a series of combinations are provided:

HTTP only vs. HTTP and HTTPS
No database required, or the use of either MongoDB, PostgreSQL, or MySQL
If desired, integration with A-MQ

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.2. Before You Begin

Before you can get started:

You must be able to access a running instance of OpenShift Container Platform. If you do not have access, contact your cluster administrator.
Your instance must be pre-configured by a cluster administrator with the Instant App templates and builder images. If they are not available, direct your cluster administrator to the Loading the Default Image Streams and Templates topic.
You must have the OpenShift Container Platform CLI downloaded and installed.

2.3. Browser Requirements

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

2.4. Tutorial Video

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

2.5. Forking the Sample Repository

Visit the Ruby example page while you are logged in to GitHub.
Note
This topic follows the Ruby example, but you can follow along using any of the language examples provided in the OpenShift Container Platform GitHub project.
Fork the repository.
You are redirected to your new fork.
Copy the clone URL for your fork.
Clone the repository to your local machine.

2.6. Creating a Project

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

Visit the OpenShift Container Platform web console in your browser. The web console uses a self-signed certificate, so if prompted, continue past a browser warning.
Log in using the username and password recommended to you by your administrator.
To create a new project, click New Project.
Type a unique name, display name, and description for the new project.
Click Create.
The web console’s welcome screen loads.

2.7. 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:

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.
Click Browse, then select ruby from the drop-down list.
Click the ruby:latest builder image.
Type a name for your application, and specify the Git Repository URL, which is https://github.com/<your_github_username>/ruby-ex.git.
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.
Click Create.
Note
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.

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.

2.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:

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.
Visit the web address for your new application.

2.9. Configuring Automated Builds

You forked the source code for this application from the OpenShift Container Platform 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:

From the Web Console, navigate to the project containing your application.
Click the Browse tab, then click Builds.
Click your build name, then click the Configuration tab.
Click next to GitHub webhook URL to copy your webhook payload URL.
Navigate to your forked repository on GitHub, then click Settings.
Click Webhooks & Services.
Click Add webhook.
Paste your webhook URL into the Payload URL field.
Click Add webhook to save.

GitHub now attempts to send a ping payload to your OpenShift Container Platform 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.

2.10. Writing a Code Change

To work locally and then push changes to your application:

On your local machine, use a text editor to change the sample application’s source for the file ruby-ex/config.ru
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.
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 Container Platform handles the rest.

2.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:

Click the Browse tab, then click Builds.
Find your build, then click Start Build.

Chapter 3. Developers: Basic Walkthrough Using the CLI

3.1. Overview

Language	Implementations and Tutorials
Ruby	Rails
Python	Django
Node.js	Node.js
PHP	CakePHP
Perl	Dancer
Java

Other images provided by OpenShift Container Platform include:

In addition, JBoss Middleware has put together a broad range of OpenShift Container Platform templates as well as images as part of their xPaaS services.

The technologies available with the xPaaS services in particular include:

Java EE 6 Application Server provided by JBoss EAP 6
Integration and Messaging Services provided by JBoss Fuse and JBoss A-MQ
Data Grid Service provided by JBoss Data Grid
Real Time Decision Service provided by JBoss BRMS
Java Web Server 3.0 provided by Tomcat 7 and Tomcat 8

With each of these offerings, a series of combinations are provided:

HTTP only vs. HTTP and HTTPS
No database required, or the use of either MongoDB, PostgreSQL, or MySQL
If desired, integration with A-MQ

Note

3.2. Before You Begin

Before you can get started:

You must be able to access a running instance of OpenShift Container Platform. If you do not have access, contact your cluster administrator.
Your instance must be pre-configured by a cluster administrator with the Instant App templates and builder images. If they are not available, direct your cluster administrator to the Loading the Default Image Streams and Templates topic.
You must have the OpenShift Container Platform CLI downloaded and installed.

3.3. Tutorial Video

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

3.4. Forking the Sample Repository

Visit the Ruby example page while you are logged in to GitHub.
Note
This topic follows the Ruby example, but you can follow along using any of the language examples provided in the OpenShift Container Platform GitHub project.
Fork the repository.
You are redirected to your new fork.
Copy the clone URL for your fork.
Clone the repository to your local machine.

3.5. Creating a Project

To create an application, you must create a new project and specify the location of the source. From there, OpenShift Container Platform begins the build process and creates a new deployment.

Log into OpenShift Container Platform from the CLI:

With username and password:

$ oc login -u=<username> -p=<password> --server=<your-openshift-server> --insecure-skip-tls-verify

With oauth token:

$ oc login <https://api.your-openshift-server.com> --token=<tokenID>

To create a new project:

$ oc new-project <projectname> --description="<description>" --display-name="<display_name>"

After creating the new project, you will be automatically switched to the new project namespace.

3.6. Creating an Application

To create a new application from the code in your forked repository:

Create the application by specifying the source of the code:
```
$ oc new-app openshift/ruby-20-centos7~https://github.com/<your_github_username>/ruby-ex
```
OpenShift Container Platform finds the matching builder image (which in this case is ruby-20-centos7) and then creates resources for the application (image stream, build configuration, deployment configuration, service). It also schedules the build.
Track the progress of the build:
```
$ oc logs -f bc/ruby-ex
```
Once the build is complete and the resulting image has successfully pushed to your registry, check the status of your application:
```
$ oc status
```
Or you can view the build from the web console.

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. You can also use the oc get pods command to check when the pod is up and running, or the oc get builds command to see build statistics.

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.

The oc status command tells you what IP address the service is running; the default port it deploys to is 8080.

3.7. Create a Route

An OpenShift Container Platform route exposes a service at a host name, so that external clients can reach it by name. To create a route to your new application:

Expose a service for ruby-ex:
```
$ oc expose service ruby-ex
```
View your new route:
```
$ oc get route
```
Copy the route location, which will be something like ruby-ex-my-test.example.openshiftapps.com.

3.8. View the Running Application

To view your new application, paste the route location that you copied (in the previous section) into the address bar of your web browser and hit enter.

The example ruby-ex application is a simple welcome screen, and contains details on how to deploy code changes, manage your application, and other development resources.

Next, configure automated builds via a GitHub webhook trigger, so that code changes in your forked repository cause your application to rebuild.

3.9. Configuring Automated Builds

To set up a webhook for your application:

View the triggers section of the BuildConfig to verify that a GitHub webhook trigger exists:
```
$ oc edit bc/ruby-ex
```
You should see something similar to this:
```
triggers
- github:
    secret: Q1tGY0i9f1ZFihQbX07S
    type: GitHub
```
The secret ensures that only you and your repository can trigger the build.
Run the following command to display the webhook URLs associated with your BuildConfig:
```
$ oc describe bc ruby-ex
```
Copy the GitHub webhook payload URL output by the above command.
Navigate to your forked repository on GitHub, then click Settings.
Click Webhooks & Services.
Click Add webhook.
Paste your webhook URL into the Payload URL field.
Click Add webhook to save.

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

3.10. Writing a Code Change

To work locally and then push changes to your application:

On your local machine, use a text editor to change the sample application’s source for the file ruby-ex/config.ru
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.
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 Container Platform handles the rest.

3.10.1. Manually Rebuilding Images

$ oc start-build ruby-ex

3.11. Troubleshooting

Changing Projects

Although the oc new-project command automatically sets your current project to the one you’ve just created, you can always change projects by running:

$ oc project <project-name>

To view a list of projects:

$ oc get projects

Manually Triggering Builds

If the build does not start automatically, start a build and stream the logs:

$ oc start-build ruby-ex --follow

Alternatively, do not include --follow in the above command, and instead issue the following command after triggering the build, where n is the number of the build to track:

$ oc logs -f build/ruby-ex-n

Chapter 4. Administrators: Setting Up a Cluster

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

Chapter 5. Revision History: Getting Started

5.1. Mon Sep 18 2017

Affected Topic	Description of Change
Administrators: Setting Up a Cluster	Changed the `tag` command to mark a new image as being desired for deployment.

5.2. Wed Jan 18 2017

OpenShift Container Platform 3.4 initial release.

Legal Notice

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, 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.