A while back a friend and fellow IBMer @ProfAvery turned me on to Sahat Yalkabov's hackathon-starter project on GitHub. At the time I was just trying to learn some more about node.js and the project provided some solid examples for using various APIs and over time with contributions from many folks has become what I expect would be a solid base, at least for a hackathon effort and possibly for more serious, long-term development. And as I have watched it develop I've been pleased to see how Sahat has stuck to his guns about keeping it reasonably simple and approachable -- he has politely turned down a variety of contributions that may have added some value, but would have also moved the project away from its purpose.

As IBM Bluemix™ and its DevOps Services started to develop, I realized it would be a great match for hackathon-starter. While it's easy to stand up hackathon-starter in many environments (including Bluemix -- more on that in a moment), DevOps Services integration makes it simple to collaborate and provide a continuous delivery pipeline automatically deploying each delivery to Bluemix. With a shared Git remote at DevOps Services, you could easily work together on a hackathon from distributed locations.

I think that's the best way to stand up hackathon-starter: using Bluemix and DevOps Services together for a collaborative, continuous delivery environment so I wrote a developerWorks piece about it, complete with screen shots, some sample code bits and a short video.

Another way that also works -- but without the DevOps Services integration -- is to just use the Cloud Foundry command line to push it to Bluemix, configuring the required database service and a process environment variable to connect to it. While I consider this approach less capable from a teaming perspective, it can certainly work if you just want to stand up the example and poke at it yourself. I'll do it two ways: the first feels like the easiest to me and takes you to the Bluemix web interface where you can explore other things about your project; the second is a completely command line approach (#protip: reading through the first will provide some useful context for the second one).

For both approaches, the basic steps are very similar:

1. Obviously, you'll need an IBM ID registered at Bluemix.
2. Get the Cloud Foundry command line interface if you don't already have it (using cf v6 here).
3. Make directory on your system for the project files.
4. Get a ZIP of the hackathon-starter files and extract the profie files to your new project directory.
5. Use cf push to create your application at Bluemix (it won't really work yet since it requires a database service we have not yet configured, but we need the app to exist so that we can register the service to the app).
6. Configure a MongoDB database service for the application.
7. Create a process environment variable to hold the DB URL for the database instance so that we can connect to it (in config/secrets.js, you can see that hackathon-starter will query the environment variable MONGODB for the connection information).
8. Restart the application and get hacking!

Note: On June 23, 2014, the IBM BlueMix service dropped the ng.bluemix.net domain in favor of mybluemix.net. While I have fixed the text, some of the screen captures still show the previous name. Please be aware of the difference while working through the material.

The first four steps are pretty basic stuff and I won't explain those further. Step 5 is the same for both, so let's do that first.

Since you've installed the Cloud Foundry client, it should be on your path. Make your current working directory the one with hackathon-starter's package.json file. From your command line window, execute cf push your-app-name -m 512m. Obviously, replace your-app-name with whatever you like.

You'll see a lot of activity in your command line window as Cloud Foundry processes the package.json file and pushes your application to the cloud. It should start something like this:

and end something like this:

But if you believe it and go to your application URL, you'll see this (because there is no MongoDB service configured for the application yet):

There are two paths for fixing that, let's start with the cuter one.

hackathon-starter and Bluemix

Log into the Bluemix web application, go to the Catalog and create a MongoDB service. Where it says Add to:, insert your-app-name, same as how you named it for the cf push command earlier. You can leave the name as the generated default or change it to something that is more meaningful to you:

You will be prompted to restart, but don't do it yet - there's no point until we complete the next step.

Click on your application from the Dahsboard page and then on the Runtime section. Scroll down to the Environment Variables section. Under the VCAP_SERVICES section you'll see some JSON that describes your MongoDB service. Copy out the text of the "url" attribute towards the bottom of the section -- be sure to get it all. It should look something like this: mongodb://68638358-a3c6-42a1-bae9-645b607d55e8:46fb97e6-5ce7-4146-9a5d-d623c64ff1fe@192.155.243.23:10123/db

Now switch to the USER-DEFINED Environment Variables section -- it is likely empty. Using the string you just copied from the VCAP_SERVICES MongoDB url, create a new environment variable called MONGODB and set that string as its value.

Your application will automatically restart after you save the change and after a moment, if you visit the Route shown at the top of your application's overview (your-app-name.mybluemix.net, you should see hackathon-starter. Note that configuring the database this way is a touch fragile as if you needed to make any changes to the MongoDB URL (you dropped and recreated the service, you wanted to use a different service that works with the MongoDB wire protocol, etc., you'd need to come fixup this environment variable to match.

Command line only, please

We can configure a service for our application from the Cloud Foundry command line as well as interrogating the environment variables to get the values we need to set our new user-defined variable. For the command line purists in the audience, I'll step through those parts next.

I'll leave most of the investigation to you, but here are some basic commands that will help. Use cf marketplace to see a list of available services, cf services to see a list of your services, cf create-service (add -h to see help for this, including an example) and cf -h or cf command -h for help at any time.

1. To create your MongoDB service from the command line, use (the last part is a name you choose): cf create-service mongodb 100 your-service-name

2. Bind your new service to your application: cf bind-service your-app-name your-service-name

3. Use cf files your-app-name logs/env.log to see the content of the VCAP_SERVICES environment variable.

4. Copy out the url attribute value in its entirety.

5. Create a new environment variable for your application with: cf set-env your-app-name MONGODB your-url-value

It will look something like this:

cf set-env bm-hackstart MONGODB mongodb://68638358-a3c6-42a1-bae9-645b607d55e8:46fb97e6-5ce7-4146-9a5d-d623c64ff1fe@192.155.243.23:10123/db

6. To see the currently configured user-defined environment variables for your app (to verify it worked), use: cf env your-app-name

7. As the TIP in the cf set-env command output suggests, use cf push (see full command example earlier) to make sure the changes take effect. Using just cf restart your-app-name might work, too.

Go visit your app at your-app-name.mybluemix.net -- it should be running and ready to go.