Jump-start your hackathon efforts with IBM Bluemix DevOps Services


Note: Changes in MongoLab DB support at Bluemix will likely cause this tutorial to not work exactly as written. An update to the tutorial is in progress and should be available soon. The author is waiting until the restriction requiring a compose.io account is lifted. In the mean time, creating an account at MongoLab may allow you to continue using this article.
Note also that this tutorial was written using a previous version of the IBM Bluemix® interface. Given the rapid evolution of technology, some steps and illustrations may have changed.

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 Bluemix 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. Bluemix 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 Bluemix DevOps Services and to automatically deploy it after every change to the Bluemix PaaS.

Run the appGet the code

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 50 contributors.

What you'll need to kickstart your hackathon efforts

For starters:

  • An IBM ID registered at 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 Bluemix 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 Bluemix DevOps Services to work with this article as your starting point, that only gets you version 3.0.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 Bluemix 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 Bluemix DevOps Services 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 your 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 Bluemix DevOps Services Project

  1. Go to Bluemix DevOps Services, log in, and click Create Project. I called mine bluemix-hackathon in the example below—use whatever name suits your project.
  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. The defaults in the initial configuration are likely correct. We’ll configure the actual deployment steps 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 Bluemix 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 will create a sub-directory with your project at this location. For example, I use “MyDevProjects” to organize my development work and Git clone will create a bluemix-hackathon directory under that as part of the cloning process. Make your new project directory your current working directory.

    Git clone pulls in the two files created by default when your project was created at Bluemix 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’s hackathon-starter-master folder to your new directory. You should get a conflict on the README.md file. Keep the one from Bluemix 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 or you extracted the parent directory. In this case, delete what you extracted and be sure to target the correct location with the ZIP file contents; 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 Hacakthon Starter at Bluemix, we'll need the name of our MongoDB service before we can successfully deploy, 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 (we'll actually use the MongoLab service because its 3rd party status means it is more likely to remain available than the experimental 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 URI 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 documentation.

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 works in 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 getBluemixDbUri = function() { 
 var dbUri = ""; 
 if (process.env.VCAP_SERVICES) { 
 var env = JSON.parse(process.env.VCAP_SERVICES); 
 var mongoVersion = 'mongolab'; 
 if (env[mongoVersion]) { 
 dbUri = env[mongoVersion][0].credentials.uri;  
 if (dbUri === "") return null; 
 else return dbUri; 

Don't forget to add the check for getBluemixDbUri() || 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 "bluemix-jumpstart," 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 (and must be unique across Bluemix): http://bluemix-jumpstart.mybluemix.net. Replace bluemix-jumpstart in both places (name: and host:) and the service name hackathon-starter-db with your service name.

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

You may have noticed that the name in the manifest.yml, bluemix-jumpstart, is different than the one used for the Bluemix DevOps Services project, bluemix-hackathon. This is because bluemix-hackathon was already in use at Bluemix (and the project name at Bluemix must be unique across the Bluemix service). My first deployment of this project actually failed because I didn’t realize there was a name conflict. But no worries, we just change the name in this file and carry on.

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 Bluemix DevOps Services. Use these commands from your command window where your project is (you’ll see a flurry of activity in the window and you will be prompted for your Bluemix credentials for the push):
    git add . 
    git commit -m "initial commit"
    git push
  2. Now go back to Bluemix DevOps Services and drop in on your Edit Code page for a quick peek:
  3. Click BUILD & DEPLOY. We have to create the steps for our build and deploy pipeline (fortunately it’s just one simple step).
  4. Click the ADD STAGE link. You don’t need to change anything on the Input tab, though I did change the name to "Deploy" (because we don’t need any other steps to get up and running).
  5. On the Jobs tab, click Add Job and choose Deploy as the type. You can change the name if you want and the default values should be fine. Save your changes.
  6. Optional: Before you run your build, a quick #protip: If you have followed closely and typed carefully, all will likely be fine. But if there’s an issue, the run-time logs, at this time, are not captured by Bluemix (just the deployment bits). If something goes wrong, you’ll have little help working out what it is without the missing logs. So before you start the deployment, go back to your command window and login to Cloud Foundry (this will require installing Cloud Foundry command line tools which you can do by following these instructions).

    You may be prompted for more than your email and password, depending on what else you have going on. At the moment, Bluemix doesn’t know anything about your app (so if you type cf logs <app-name> to tail your logs, it will just complain that there is no such project). But after you start your pipeline job above, you should be able to start tailing your logs shortly thereafter to catch any possible execution errors. For more information about using logging effectively with Bluemix applications, see "Node.js debugging starts with better logging" by Patrick Mueller.
  7. Click the Run button to start your first deployment!

    If you choose to tail your logs while the deployment is going, you may get a failure or two until Bluemix notices that the deployment has started. Here’s an example of log statements displayed as I clicked around the working app. You’ll likely want to keep a command window tailing your logs (or use a log preservation service) as you develop your application.
  8. After a few moments, the panel should update to look like this:
  9. Click the link see your new project in action.

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 Bluemix DevOps Services online editor and Git interface.

  1. Head back to Bluemix 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 navbar.jade. Replace "Project name" with "Jumpstart with Bluemix DevOps Services" (highlighted line). Save.
  3. Click on the Git icon on the left to go to the Git status page. Here, you'll see your Working Directory Changes. Select both files (or Select All), add a comment, then click the Commit 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. When we pushed our changes from our workstation, they went to our Git master. Our web-based session works on its own copy, not the master. So before we push our committed changes, we should sync our web workspace with the master. In my experience, clicking Sync will fix everything at this point, bringing your workspace up to date and pushing your pending changes.
  5. Click on BUILD & DEPLOY, and you'll see that a new deployment has been automatically kicked off (because it saw your master branch get updated).
  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.


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


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

Downloadable resources


Sign in or register to add and subscribe to comments.

Zone=Cloud computing
ArticleTitle=Jump-start your hackathon efforts with IBM Bluemix DevOps Services