Jump-start your hackathon efforts with DevOps Services and Bluemix

29 June 2014
PDF (1142 KB)
Share:

Jump-start your hackathon efforts with DevOps Services and Bluemix

08:08  |  Transcript
Millard Ellingsworth

Millard Ellingsworth

Software Developer

@millard3

Sign up for IBM Bluemix
This cloud platform is stocked with free services, runtimes, and infrastructure to help you quickly build and deploy your next mobile or web application.

A hackathon is typically a brief, intense period of collaborative development generally around a particular cause or topic. The idea is to get something done quickly and, of course, for the thing you do to totally rock the judges. Given the short time period, it can be challenging to build in basic features like Facebook authentication, or sending emails or texts, while still making significant progress on your main goal.

IBM DevOps Services provides a collaborative on-the-web development environment and continuous delivery pipeline, while Bluemix provides the cloud hosting you need to run it, making this a perfect pair for hackathon success.

The Hackathon Starter Project, by Sahat Yalkabov et. al., hosted at GitHub, provides a great collection of capabilities to use as the base for your hackathon efforts. DevOps Services provides a collaborative on-the-web development environment and continuous delivery pipeline, while Bluemix provides the cloud hosting you need to run it, making this a perfect pair for hackathon success. I explain how to stand up your own copy of Hackathon Starter from a fresh version of the source using DevOps Services and to automatically deploy it after every change to the Bluemix PaaS.

If you are curious about hackathons, read Tim Falls' blog WHY is a Hackathon? on SendGrid. It presents a thoughtful description of why hackathons exist and the value they create. If you'd like to give hackathoning a try, check out Appsembler's 10 tips for hackathon success and Michelle Sun's Survival Guide to Your First Hackathon.

Hackathon Starter provides a Node.js web application boilerplate using the Express framework and MongoDB NoSQL database. It features various types of authentication, including local authentication (users set up their own credentials) and OAuth authentication using Twitter, Facebook, Google, LinkedIn, and others. The default UI uses Bootstrap 3 and is reasonably responsive to various screen sizes. There's a contact form with email support, general user account management capabilities (including lost password support), and cross-site request forgery (CSRF) protection. There are also API examples for a variety of popular web sites, including Facebook, Foursquare, Tumbler, Twitter, Stripe, and others.

The Hackathon Starter README.md at GitHub is detailed and well-written. It includes instructions on how to get your own API keys for the many different services available, good high-level documentation on the project structure, and details on how to perform certain actions necessary for your hackathon success, like adding a new page/route. There is also a list of suggested references and an amazing amount of working code, making it an awesome learning tool and reference even if you don't plan to engage in a hackathon. Sahat has worked to keep the project simple and easy to understand while still welcoming the contributions of over 30 contributors.

What you'll need to kickstart your hackathon efforts

 

For starters:

  • An IBM ID registered at DevOps Services and Bluemix. If you don't have and IBM ID, you can create one at either of these sites.
  • A Git client. I use the command line in this article.
  • A ZIP file of the Hackathon Starter Project. There's a button to download a ZIP file of the source at the top of the README.md on the GitHub page. Why not a clone of the Hackathon Starter? Because we want your copy at DevOps Services to be your master, and it will be simpler if we create our repository there and pour in the Hackathon Starter code. It also gives us a chance to make some necessary changes ahead of time.
  • A basic understanding of JavaScript, Node.js, MongoDB, Express, Jade, and Git would be helpful, but we'll be using someone else's code as a starting point to complete the steps in this article, so this is not required.

While you could just fork the copy I have set up at DevOps Services to work with this article as your starting point, that only gets you version 2.1. If you want to use the latest, you'll need to stand up your own copy, which I'll walk you through. I've done this a couple of different ways and am providing here what I think gives you the best starting point with the fewest and simplest steps: a DevOps Services project that automatically deploys to Bluemix every time one of your teammates pushes a new change to your source code repository. By the way, if you do fork the existing project, you need to edit the manifest.yml file and provide:

  • A different host: value (the host name becomes part of the route which must be unique across BlueMix)
  • The name of your own MongoDB service, replacing "hackathon-db-service"

Six steps to being hack-ready

 

Here's an overview of the steps:

  1. Make a project for your Hackathon Starter code. Configure it to use Git for your source code and to "Deploy to Bluemix" when we push changes. This gives us a Git URL for our master repository to use for pushing our local changes.
  2. Use Git clone to create a local copy of the project. Pour in the Hackathon Starter source.
  3. Visit Bluemix to create a MongoDB service to use for our datastore.
  4. Edit one file, secrets.js, to retrieve the database URL for our MongoDB service from Bluemix and add a manifest.yml file, which is required for auto-deployment.
  5. Push our changes to the cloud and watch the magic happen.
  6. Make some small changes from the cloud, synchronize them, and push to demonstrate auto-deployment.

So, six easy steps to success in the cloud to kickstart your hackathon efforts. Let's go!

Step 1. Make a DevOps Services Project

 
  1. Go to DevOps Services, log in, and click Create Project. I called mine hackathon-starter in the example below—use whatever name suits your project.

    READ:Hacking in the cloud with IBM Bluemix and DevOps Services

  2. Set the project to use a Git repository to hold your code. You'll be storing data for API keys you won't want people outside your team to see, so make it Private.
  3. Add features for scrum development. We won't use these in this article, but you'll want to be able to track tasks and defects as you work on the project.
  4. Select Deploy to Bluemix to set up for auto-deployment, which we'll configure later.
  5. After the project is created, you should invite the other members of your project. You can do this later, but only project members can see and work on the source code. All project members need IBM IDs and need to be registered at Bluemix and DevOps Services.

Step 2. Set up the code

 
  1. From your opening project page, you can find the Git URL for your project:
  2. Find an appropriate directory on your local machine to clone the project to. Git clone creates a sub-directory with whatever name you used earlier for your project. Make that your current working directory.

    This pulls in the two files created by default when your project was created at DevOps Services. It also configures that location as the remote we'll push changes to.

  3. Extract the contents of the Hackathon Starter ZIP file you downloaded earlier to your new directory. You should get a conflict on the README.md file. Keep the one from DevOps Services. It's smaller and you'll likely want your own for your project. If you don't get a conflict, you didn't extract it to the correct location. In this case, delete what you extracted and be sure to target the correct location, otherwise the new source either won't be part of your new Git repository, or your top-level directory will be different from that used in the examples below, creating conflicts with the steps provided.

Step 3. Create a MongoDB service at Bluemix

 

Hackathon Starter depends on MongoDB for database storage. When we do the code fixups we need to run at Bluemix, we'll need the name of our MongoDB service before we can successfully deploy. The service needs to exist anyway, so let's do that next.

Visit your Bluemix account and log in, then go to the Catalog and scroll down to the Data Management section for services. Choose to create a MongoDB service. You can take the default name or make one up. Make a note of it because we'll need it for the next step. Be sure you don't associate it with any existing apps. Our manifest.yml file will create the association when we deploy.

Step 4. Make a couple of small code changes

 

First, we'll make the code changes to connect to the MongoDB service. During deployment, your application is associated with the service. Connection information is created at that time and stored as part of your application's configuration. Because it is available in our run-time environment, we can interrogate it and extract the URL value from the credentials for creating our database connection. I provide the code to do this below and show you where to insert it. If you are curious about how this works, read about the VCAP_SERVICES environment variable in the Bluemix FAQ.

If you look at the code you unzipped, you'll see that the database connection information comes from /config/secrets.js. It is currently configured to check for a general environment variable, or you can use the standard localhost reference.

db: process.env.MONGODB|| 'mongodb://localhost:27017/test',

We're going to add a check for a configured Bluemix entry to the front of that. It returns null if there isn't one so that the existing code still worksin case you have team members working locally. Here's what the diff looks like:

Here is the new function so you can copy and paste it:

//fixup to retrieve MongDb creds from BlueMix if configured
var getBlueMixDbUrl = function() {
 var dbUrl = "";
 if (process.env.VCAP_SERVICES) {
 var env = JSON.parse(process.env.VCAP_SERVICES);
 if (env['mongodb-2.2']) {
 dbUrl = env['mongodb-2.2'][0].credentials.url; 
 }
 }
 if (dbUrl === "") return null;
 else return dbUrl;
};

Don't forget to add the check for getBlueMixDbUrl() || to the front of the expression on the db: line. Save that.

Add a new file named manifest.yml to the root directory of the project. Put the following code in it, replacing the names as needed. For example, my project is called "hackathon-starter," so you'll have to use something else, at least for the host attribute. The host attribute is used to create the route/url for the application: http://hackathon-starter.mybluemix.net. Replace hackathon-starter in both places (name: and host:) and the service name hackathon-starter-db with your service name.

applications:
- services:
  - hackathon-starter-db
  host: hackathon-starter
  disk: 1024M
  name: hackathon-starter
  command: node app.js
  path: .
  domain: mybluemix.net
  mem: 512M
  instances: 1

Step 5. Launch it!

 

Believe it or not, we're almost done. Just a few more steps:

  1. We need to add these changes to our local Git repository, commit them, and push them to the repository at DevOps Services. Use these commands from your command window:
    git add . 
    git commit -m "initial commit"
    git push
  2. Now go back to DevOps Services and drop in on your Edit Code page for a quick peek, then click on BUILD & DEPLOY.
  3. On the BUILD & DEPLOY page, toggle the type of deployment to SIMPLE. Your first deployment will start and show as pending in the Result column of the Recent Auto-Deployments table.
  4. The first deployment will take a bit longer because npm needs to resolve the various Node.js dependencies and do the initial builds as specified in the package.json file. Give it a few moments, then head over to Bluemix and check out your application's overview page. You can see that it is running, and that your MongoDB service was automatically associated via your manfiest.yml file.
  5. Click the link next to Routes: underneath the application name. This takes you to your new project.

Step 6. Tweak it in the cloud

 

That looks good! But it's totally generic. Let's change the project name to something else and replace the header on the opening HTML page. And just for fun, let's do it in the cloud using the DevOps Services online editor and Git interface.

  1. Head back to DevOps Services and go to your Edit Code page. Open the views folder and click on home.jade. Under block content, change the h1 line (highlighted) as shown, or with whatever text you like. Save it.
  2. Open the partials folder under views and click on navigation.jade. Replace Project name with Jumpstart with DevOps Services (highlighted line). Save.
  3. Click on the "disk" icon on the left (second from top) to go to the Git status page. Here you'll see your Unstaged changes. Select both then click the STAGE button.

    If you are ever curious what changes are about to be made, you can click the twistie on the left of any entry to show a diff of the file:

  4. Select both files, click COMMIT, add a comment and submit the changes.
  5. Even though we pushed the files to our Git repository, we are working in a local workspace when we're in the web client. Before we can push the changes we need to sync with the master repository. So, do a Fetch to synchronize before you push your changes or you'll get an error. Click on BUILD & DEPLOY, and you'll see that a new deployment has been automatically kicked off.
  6. After a moment or two, refresh your browser page displaying your starter application. As a bonus, if you resize the window, you'll notice that the application has responsive web design characteristics, hiding the menu options under a button when the screen is sized down significantly.

Happy hacking! If you use this for a hackathon at Bluemix, please add a comment to this article describing your project, along with a link if you plan to leave it up.

Conclusion

 

DevOps Services provides a flexible, easy-to-use environment for running your project, whether for a hackathon or otherwise, allowing you to work locally or on the web, automatically deploying the latest changes for users to see. There is much we didn't touch upon in this example. Planning, tracking, and dashboards make it possible for users to submit enhancement requests (or the occasional defect) easily, and for your project sponsors to see what is being worked on. There are even more flexible build and deployment options available. When you're done with your hackathon, come on back and look around.

Acknowledgements

 

Many thanks to John Kellerman, Michele Chilanti, Annie Cheng, and Erik Mats for their technical reviews and suggestions.

Add a comment

Note: HTML elements are not supported within comments.


1000 characters left

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing
ArticleID=972577
ArticleTitle=Jump-start your hackathon efforts with DevOps Services and Bluemix
publish-date=06292014