ScholarShift is a project that was started to help students ages 11-14 learn how to basic application development works with OpenShift Online. The class covers topics such as:

• An introduction to Cloud Native Application Development (OpenShift)

• The importance and basics of source control (GitHub)

• How to write a Hello World Program (Apache on OpenShift)

• How to deploy a game (Pac Man) on OpenShift

Instructor Requirements

Here are some of the prerequisites in order to make the class successful.

OpenShift Online Pro

As an instructor, you will need to purchase a subscription OpenShift Online. The cost (as of this writing) is $50 per month.

Email Addresses for Students

Students who will participate in the class need a working email address. It is recommended you gather the email addresses of the student prior to class. These email addresses will be used to create accounts at GitHub and you will use the email addresses to add the students as collaborators to an OpenShift Online project. Alternatively, you can create student email address accounts and assign them to students.

Configuring OpenShift Online

You will need to log into OpenShift Online and add the students.

Browse to OpenShift Online’s Management Page and log in using your credentials. Then click on Manage Subscription and then click on Manage next to Collaborators. Enter the usernames of the students you want to be collaborators until complete.

Next, you’ll need to create a project for each student and give them permission to manage things within that project.

# for number in 1 2 3 4 5 6 7 8; do \
oc new-project student${number}nbca --description="A project, just for student${number}NBCA" --display-name="student${number}NBCA" ; \
oc policy add-role-to-user admin student${number}nbca ; \
done

You can also delete all of them by doing this - warning, it will delete the project and everything inside them!!!

# for number in 1 2 3 4 5 6 7 8; do \
oc delete project student${number}nbca ; \
done

Editors

It is recommended that you have each student in the class install the Atom text editor.

GitHub Configuration

Each student will need to create a GitHub account. If you created your students email addresses for them it is possible for you to create GitHub accounts for them prior to the class. This is what I did, so I am not documenting how to do it for the students at this point.

Git Client

Each student will need to have access to a git client. I recommend just installing the Command Line Client for your operating system.

Student Guide

Welcome to ScholarShift! In this class you’ll learn the basics of how to write applications that run ON THE CLOUD!

Hopefully, your instructor has helped you complete all the prerequisites of having a git client installed, having access to github and openshift. Also, your instructor should have taken you through the basics of software applications, OpenShift Online, and GitHub so you have some idea about how software development works. Don’t worry, you don’t need to be an expert - that’s the whole point of this class -for you to learn by doing!

Deploying Your First Application

Let’s get started by writing and launching our first application on the cloud, a simple website. The website will run on the apache webserver. Apache is a very popular web server that millions of websites run on. W3techs website estimates that 47% of websites run on apache! That’s a whole lot of pages being served by Apache!

The first thing you’ll need to do to get started is create a project in GitHub. GitHub is a website that hosts source control repositories. You can think of source control management or version control kind of like a library - where everyone can write in books to build stories together. To write your book, you’ll need to create a repository in GitHub (think of that like your book).

Creating a Project (Repository) on GitHub

1. Browse to GitHub and click the sign in button.

2. Log in using your email address and password. This should have been given to you by the instructor.

3. Select Create a Project

4. You’ll notice GitHub is asking you to create a new repository and it requires some information

5. Repository Name: website

6. Description: my first website

7. Make sure Public is selected

8. You do not need to initialize the repository with a README at this time

9. Select Create to create your first project (repository)

10. Congratulations! You’ve created your first repository! You’ll see that GitHub gives you several options on what to do next. We’ll cover this in the next section.

Populating Your Repository

Earlier, we compared GitHub to a library and a repository to a book. So far, all you’ve done is write the title of your book (you named it website). While this is really nice, a book without any pages or a story is a bit boring. Now we will look at adding some pages to your book. To do this, we’ll use the git client. How you install the git client will vary based on your operating system. You should follow the instructions here if you haven’t already installed the client. Once it’s installed you will need to open a terminal window on your computer and make sure you can run the git client.

1. To check if git is functioning you can run it with a command line option of version to see if it prints out the version.

# git --version
git version 2.14.2

If this works, then you are probably good to start using your git client. If not, you will need to fix this before moving on.

1. Now, create a new directory using the mkdir command.

# mkdir website

1. Now, change directories to be inside the directory you created using the cd command.

# cd website

1. From here, we can begin writing the code for your first application. We will keep it really simple at first and just have your website say something really simple.

# echo "This is <YOURNAME>'s website'" >> index.html

By using the echo command and redirecting (>>)the output to a file, the file index.html will now contain the text "This is <YOURNAME>'s webiste" Of course, you should substitute your name where it says <YOURNAME>.

1. Now that we have a file on our local machine, we need to upload it to GitHub. You can think of that like taking the book you’ve been writing, making a copy, and sending it to the library. This way, everyone can see your work and build upon all your hard work. The first step is to initialize the directory you are working in to be a git repository.

# git init

1. Next we need to tell git that we want to add the index.html file to our local project (on your computer).

# git add index.html

1. With git (our source control), when you want a change to be logged it’s called "committing". You can use the command git commit to commit your code.

# git commit -m "first commit"

The -m switch can be used with git commit to add a comment to your commit. It’s always a good idea to explain what it is you are doing when you commit something because it helps other people understand what you were doing.

1. Next you need to tell git on your local computer where it should send the changes you’ve been making. We will add the project you created on GitHub as that location using the git remote add command. Be sure to change the text "<CHANGEME>" in the example below to your student number.

# git remote add origin https://github.com/student<CHANGEME>NBCA/website.git

1. Finally, you will push the changes you’ve made to your local git repository to the remote git repository hosted by GitHub using the git push command.

# git push -u origin master

Congratulations, you’ve just performed your first commit! You can now consider yourself a DEVELOPER! :)

Running an Application from your Code

All that code writing and source control is fun, but what’s the point if you don’t run your application. Going back to our book and library analogy - you have created a book (repository), brought it home with you and written some pages (code), and returned it to the library (committed and pushed). Now, you want to publish it so that lots of people can read it. Well, in order to do that, you’ll need a publishing company to take your copy and run it. You can think of OpenShift as the publishing company, bookstore, and every library in the entire world all wrapped into one. So, let’s get started getting your "book" out to the world.

First, you’ll need to log into the OpenShift Online console. Browse to the OpenShift Management Console

Then enter your username and password that the instructor provided to you.

You should have landed at the Active Subscriptions screen. From here, click Open Web Console.

You should now see the OpenShift Service Catalog. This catalog can be used to launch various applications on OpenShift. For our first application, you’ll select Apache HTTP Server (httpd).

The information page for launching Apache is displayed. You can read the information about it and then click next.

The next screen is the configuration page. Set the following values substituting your student number for <CHANGEME>: . Project Name = website-project<CHANGEME> . Project Display Name = my website . Project Description = learning to launch my first application . Version = 2.4 . Application Name = website-application . Git Repository = https://github.com/student<CHANGEME>NBCA/website.git

Now you can click next and OpenShift will begin deploying your first application, a website running on Apache!

Customizing Your Website

So, you built your first website. Great, but it’s a little boring isn’t it? I mean, just some simple text telling people that it’s your website isn’t so exciting. Let’s take some time to customize it a bit. Webpages are often written in Hyper-Text Markup Language or HTML, for short.

HTML is fairly simple to write. Let’s start by editing the index.html file and changing it to be written in HTML.

First, open your favorite text editor. In this class we use Atom. It’s free and you can install it from their website.

In Atom, you’ll need to browse to your project folder by clicking File and then Open Folder.

Then browse to the folder that you created called website earlier and open it.

You should then be able to click on index.html on the left hand pane of the Atom text editor and see the text you entered in the previous lab you completed. This is exactly what we want to change!

One of the nice things with the Atom text editor is that it allows you to preview your HTML markup. This is really handy because as you write your HTML you can see what it will look like before going through all the trouble of checking it into GitHub and deploying it on OpenShift. When developing software, the faster you can get feedback the more efficient you will be!

To enable preview click on Packages then Markdown Preview and Toggle Preview. This will open a new pane to the right that shows a live preview of what you write.

Let’s test it out and make a simple change. The HTML for having a horizontal line show up on your page <HR> (it stands for Horizontal Rule in case you were curious). Type the following into your index.html in the Atom text editor and see if your preview shows you a line.

<HTML>
This is my new and improved website, now with infinitely more horizontal line!
<HR>
</HTML>

Now, your preview should look something like this.

OK, now this is where you get to have fun. For the remainder of the time your instructor has given you for this section of the course you can further customize your site. You can use the htmldog site to learn more about HTML and get ideas for what to build.

Remember, once you are done make sure you commit your changes to github, push them, and then start a new build in OpenShift so that your live website is updated. The preview in the Atom editor is nice, but only you can see it, and you want to share your beautiful work of art for the world to see!

Here is how you commit your changes again.

# git commit -m "I made new changes and want to commit them" .

Here is how you push your changes again.

# git push

And here is how you trigger a build in OpenShift’s console. On the left hand menu select builds and builds. You will see a screen that has a highlight number on it (for example, #1). Click the number and then click on actions and rebuild.

What this does is it tells OpenShift to rebuild the image using your latest source code. This will also trigger a redeployment of that latest image, resulting in your site being updated.

Getting More Complicated: Deploying a Game

Ok, so you’ve customized your website and learned a little HTML. Good for you! I bet you are tired now …​ how about we relax a little? You know what I always find relaxing is a game of Pac Man. Too bad we don’t have our Nintendo GameBoy at school, right?

Well, how about if we deploy PacMan for ourselves?!

The good news, you won’t have to write the PacMan application yourself. That’s already been done for you. You can find the source code for PacMan here.

This PacMan application is an example of a 2-tier application. The application itself is written in a programming language called javascript. Javascript can be run on a client device, such as in an internet browser (Firefox, Chrome, Safari). However, javascript can also run on what is called server-side. In this case, our "server-side" will be Openshift. We will run our javascript code on an application server called Node.js - it’s one of the most popular run-times for server-side javascript.

But where do we store the data for our Pac Man application? After all, if we can’t save our high scores the game isn’t nearly as fun! For storing our data, we will use MongoDB - a popular Document oriented database.

We will need to deploy a NodeJS application and a MongoDB application at the same time. Let’s get started on how we do this with OpenShift.

Before you begin, you’ll need to download the OpenShift Command Line tools and install them on your system.

Go to the Command-line section of the OpenShift console by clicking on the question mark in the top right corner and selecting Command Line Tools.

Then, follow the instructions for downloading and installing the tools for your operating system of choice.

Great! Now, you have installed the tools and we can get started deploying our Pac Man application.

Now, you’ll need to deploy pacman.

Within the OpenShift web console you’ve been using go to the catalog and select the Node.js+MongoDB catalog item.

Click next on the screen that comes up and then on the configuration screen enter the following values in.

1. Project Name = "pacman"

2. Git Repository URL = https://github.com/jameslabocki/pacman.git

3. MongoDB Username = "admin"

4. MongoDB Password = "secret"

5. Database Name = "pacman"

The click create to and go back to the overview page.

You should see that a build is pending and then the build log should start updating. What is happening is that OpenShift is taking the source code for Pac Man and building an image of that application with the NodeJS runtime. You also see that a MongoDB application was deployed. OpenShift will connect these two applications together using the information you provided, the database name, username, and password. It will take a minute or two for this to complete.

After some time, you might have noticed that Pac Man still isn’t running and your deployment named nodejs-mongo-persistent continues to re-deploy over and over again. Something must be wrong, let’s look!

Click on View Events and look at what is happening. So, what is happening?

You should see that readiness and liveness checks are failing. These are checks that OpenShift does to make sure your application is working properly. Unfortunately, they must be checking too quickly or checking the wrong path and Pac Man is taking longer to start or doesn’t have that path. When it doesn’t respond fast enough or at all, OpenShift is restarting the deployment.

Fortunately we can change the deployment configuration to get rid of the problem.

You’ll need to do the following to edit the checks.

First, edit the deployment controller by selecting Applications and Deployments in the OpenShift Console.

Then select configuration. When you are in the configuraiton screen select Actions and then Edit Health Checks.

Now, let’s modify the path, initial delay, and timeout for both the liveness and readiness check. Set them to the following:

1. Readiness Probe Path = "/"

2. Readiness Probe Initial Delay = "90"

3. Readiness Probe Timeout = "10"

4. Liveness Probe Path = "/"

5. Liveness Probe Initial Delay = "90"

6. Liveness Probe Timeout = "10"

Then click save. You should see a new deployment begin.

Now, you should be able to go back to the overview page, and click on the external route to see if Pac Man is indeed running!

Congratulations! If you made it this far, enjoy a game of Pac Man!