Step by Step guide to getting Cobalt Calibur running on OpenShift

Multithreaded JavaScript has been published with O'Reilly!
DEPRECATED: This post may no longer be relevant or contain industry best-practices.
Visit the original version of this article on mongodb.com.

In this article I explain how to get Cobalt Calibur running on Red Hat's OpenShift cloud platform. This article was republished on the 10gen website.

So, you're interested in getting the HTML5 Game Cobalt Calibur hosted for free? Look no further, Red Hat's OpenShift can do that for you. Follow this guide and you'll be up and running in no time. Cobalt Calibur is a multiplayer browser-based game which uses a bunch of HTML5 features to run on the frontend, and requires a Node.js and MongoDB server on the backend. Luckily OpenShift will satisfy these requirements for you.

game-screenshot
game-screenshot

The first thing you'll want to do is create an OpenShift account. It's quite easy and painless, I promise. Once you're done getting it setup, be sure to click any email validation links and then log in to the website.

create-new-account
create-new-account

Once you've got your account setup, you're going to want to create an SSH key for your computer (if you haven't done so previously). To create your SSH key, you will want to open up a Terminal emulator and run some commands. These commands should work fine for both OS X and Linux computers. If you've already got an SSH key (which you should if you're a GitHub user), you can skip these steps.

If you're on a Mac, you'll want to go to your list of applications and run Terminal. You can get to this app quickly by pressing Cmd+Space, typing in Terminal, and pressing enter.

spotlight-screenshot
spotlight-screenshot

Below is what your terminal window will end up looking like. You'll want to type the command ssh-keygen -t rsa, and press enter. You will then be prompted a few questions; just leave everything blank and keep hitting enter.

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/USERNAME/.ssh/id_rsa): <press enter>
Created directory '/home/USERNAME/.ssh'.
Enter passphrase (empty for no passphrase): <press enter>
Enter same passphrase again: <press enter>
Your identification has been saved in /home/USERNAME/.ssh/id_rsa.
Your public key has been saved in /home/USERNAME/.ssh/id_rsa.pub.

Congrats, you've now got an SSH public/private key. This is a file which can be used to prove to a remote computer that you are who you say you are. We need to give a copy of this file to OpenShift so that you can use git to push changes to your code to them.

To get a copy of your key file, you'll want to copy the text from ~/.ssh/idrsa.pub. You can run the command cat ~/.ssh/idrsa.pub which will display the contents of that file to your screen. Select the text and copy the output into your clipboard (everything from ssh-rsa to the username@hostname part):

$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2BLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLA
HBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAH
BLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHB
LAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBL
AHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLA
HBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAH
BLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHB
LAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAHBLAH== USERNAME@HOSTNAME

Once you've copied that text, on the OpenShift website, click My Account | Add a new key to visit the Add a Public Key page, and paste the contents of the output into the big text box. In the small text box above it you can name your key (such as Living Room Desktop or Developer MacBook). You'll want to use a descriptive name, because if your key is ever compromised, you'll want to know which one to disable.

add-a-public-key
add-a-public-key

Now, click the Create button. OpenShift is now aware of your SSH public key, and you can interact with the git server they provide without problems. Feel free to repeat this process from other machines you plan on working from.

If you get an error when you save the key, you might not have copied the whole thing. If so, you might need to open it in an editor. On a Mac try Open ~/.ssh/idrsa.pub, and on Linux, you might try gedit ~/.ssh/idrsa.pub.

Now it is time to create our OpenShift application. To do this, visit the Create Application page from the main OpenShift navigation. On this page, you will see a big list of all the types of applications supported by OpenShift. Scroll down until you see the Node.js option and select that.

nodejs-application-type
nodejs-application-type

On the next screen you will be prompted for some very basic information. Specifically, you will be asked to name your application. Since we are uploading the Cobalt Calibur engine, it makes sense to name it something like cobaltcalibur.

You will also be prompted to create a "namespace" for your account. This is basically a way to associate all of your app URLs with your account. This is so that multiple people can have the same apps named "cobaltcalibur" without stepping on each others toes. I already entered a namespace name before, so I didn't need to this time.

name-your-application
name-your-application

After you click Create Application, OpenShift will work it's cloud magic behind the scenes. During this time it is probably creating some DNS entries, copying some skeleton files, creating a git repository, the works. After the process is done, you will be taken to a new screen:

application-created-successfully
application-created-successfully

If you like, you can click the blue link to see the skeleton application OpenShift has created for you. It will be a pretty boring, static page which is displayed by a very simple Node.js app.

What you will want to do though is copy the commands in green and paste them into your terminal. This will pull the skeleton code from your applications git repository and make a local copy. There are some (probably) important files in here that we will want to keep.

first-checkout
first-checkout

If you see the same listing of files, then congratulations, you've checked out your application from OpenShift.

Now that you've got your application created and checked out, we want to add MongoDB support to the application. OpenShift calls these Cartridges.

To add MongoDB, first browse to the All Applications page, and then click the title of the application you created:

application-listing
application-listing

On this screen you can see the information for accessing your git repository again, but more importantly, there is a big Add Cartridge button.

application-info
application-info

Click that big blue button, and the next screen will prompt you for the type of cartridge to be added. Click the MongoDB option:

button-add-mongodb-cartridge
button-add-mongodb-cartridge

Once you do this, it will prompt you to make sure you want to add MongoDB. Click the Add Cartridge button again, and after some processing happens in the background it will be added to your application. You will want to copy all of the information you are provided with on this screen, notably the user, password, database, and connection URL which contains the IP address and port number for the database. We'll give this information to the Cobalt Calibur game later on.

mongodb-settings
mongodb-settings

Now that we've got the MongoDB cartridge added to our application, we want to actually start the MongoDB server. To do this, you will first need to install the rhc command line utility. You'll want to follow steps 1 and 2 on that page, you can ignore the other steps. The rhc utility gives you more control over your OpenShift applications that the website does, and is needed to start up the MongoDB server. Run the command rhc app cartridge start -a APPNAME -c mongodb-2.0 and this will start the server for you:

start-mongodb-server
start-mongodb-server

You are now ready to download the Cobalt Calibur source code, configure it to work with your OpenShift account, and upload it to the server. To do this, browse to the Cobalt Calibur GitHub page and simply download the ZIP file.

download-zip
download-zip

Extract it to the same folder that the Node.js application was checked out into. This will overwrite the index.html page, the server.js file, and the node_modules/ folder; that is all fine.

file-structure
file-structure

Now, it's time to update the server.js file so that it is able to connect to your MongoDB daemon, as well as bind to the proper ip address and port number that OpenShift requires. You can open up server.js in whatever your favorite editor is. Here is what the old code looks like:

// Web Server Configuration
var server_port = 80; // most OS's will require sudo to listen on 80
var server_address = '127.0.0.1';

// MongoDB Configuration
var mongo_host = '127.0.0.1';
var mongo_port = 27017;
var mongo_req_auth = false; // Does your MongoDB require authentication?
var mongo_user = 'admin';
var mongo_pass = 'password';
var mongo_collection = 'terraformia';

And here is what you will want to change it to:

// Web Server Configuration
var server_port = process.env.OPENSHIFT_INTERNAL_PORT; // most OS's will require sudo to listen on 80
var server_address = process.env.OPENSHIFT_INTERNAL_IP;

// MongoDB Configuration
var mongo_host = 'MONGO IP ADDRESS';
var mongo_port = 27017;
var mongo_req_auth = true; // Does your MongoDB require authentication?
var mongo_user = 'admin';
var mongo_pass = 'MONGO PASSWORD';
var mongo_collection = 'MONGO DATABASE NAME';

Notice how OpenShift provides some environment variables for the web server port and ip address. It might also provide these same variables for the mongo connection, but I didn't see this information.

The application is now configured properly. You'll want to now add your files to git, commit the files into git, and push your changes to the server.

git add -A .
git commit -m "Adding Cobalt Calibur files"
git push

You'll see a bunch of messages from all of the git hooks performing various actions, this is probably a good thing.

Now, if you browse to the URL for your game instance and refresh the page, it should load for you. If not, you might need to run the following command (I needed to for some reason):

rhc app restart -a game

Congratulations, you've now got your own personal instance of Cobalt Calibur running on OpenShift for free!

There is one big bug with OpenShift though, they don't support websockets yet. My guess is that the different apps are hosted in a shared environment, and each application gets one port number to the outside world. Websockets require a bunch of random high ports for different clients, so this doesn't really work with the shared host environment. Luckily, socket.io will fallback to using long-polling AJAX. The game doesn't always run perfectly under these conditions, e.g. the monsters or corruption might no load. OpenShift is planning on adding this feature sooner or later, you can vote on it in the mean time.

Thomas Hunter II Avatar

Thomas has contributed to dozens of enterprise Node.js services and has worked for a company dedicated to securing Node.js. He has spoken at several conferences on Node.js and JavaScript and is an O'Reilly published author.