Using the Cloudant database service in an IBM Bluemix application

Share this post:

As a cloud solution architect, I am keen to understand the capabilities of the new IBM platform as a service (PaaS) offering, IBM Bluemix. In particular, I’ve come to realize that preserving a state in an inherently stateless architecture is key, so I decided to investigate how to use the IBM Cloudant database with an IBM Bluemix application. I found a great blog post by Mattias Mohlin entitled, “Build a simple word game app using Cloudant on Bluemix.” In this post I want to show you what I learned when I tried it out myself.

Mohlin says, “My goal is to walk you through the development of a small Bluemix application using an approach that is also applicable to development of large Bluemix applications.” So the tutorial involves developing on a PC and setting up Cloudant outside of Bluemix.

DevOps servicesHere’s my simplified version focusing purely on getting an application up and running using a Cloudant Bluemix service and staying in IBM DevOps Services as much as possible. DevOps Services is a unique capability that Bluemix adds to base Cloud Foundry using the software development lifecycle experience of IBM Rational to allow for development on the cloud for the cloud.

The first step is to make a copy of Mattias’s code, so go to the GuessTheWord DevOps Services project and click on Edit Code and then FORK.

I use the same project name, GuessTheWord. In DevOps Services it will be unique since it’s in my project space.

JazzHub project

Now I can start editing my copy of the project. I need to update the host in the manifest file; otherwise, the deployment will conflict with Mattias’s. So I change it to GuessTheWordGarforth, but you’ll need to change it to something else; otherwise, yours will clash with mine. Don’t forget to save the file with Ctrl+S, File→Save or at least by selecting a different file.

Guess the word 1

Next I need to set up the app and bind the database on Bluemix, so I click on DEPLOY. I know the app won’t run yet, but this will start to set things up.

At this point I can log onto Bluemix itself for the first time and locate the new GuessTheWord in the dashboard. The dashboard is another capability that Bluemix has added to Cloud Foundry; a graphical user interface (GUI) layer on top of the command line driven base product.

Guess the word 2

I click on it and select Add a service and then scroll down to the Cloudant NoSQL database (DB) and click on it.

Guess the word 3

I click CREATE and then allow Bluemix to restart the application. Unsurprisingly, the application still does not start because there is more coding to do. However, the Cloudant service is there so I can click on Show Credentials and see that the database has a user name, password, URL, and so on. Therefore, the registration on the Cloudant site is not necessary since this is all handled by Bluemix. This single sign-on capability is another key feature of Bluemix.

Guess the word 4

Guess the word 5

Clicking on Runtime on the left and then scrolling down to environment variables, I can see that these Cloudant credentials have been set up as VCAP_SERVICES environment variables for my app. So I just need to change the code to use these.

I switch back to DevOps Services and go to the server.js file to modify the code for accessing this database. I change line 27 from

Cloudant = env['user-provided'][0].credentials;
Cloudant = env['CloudantNoSQLDB'][0].credentials;

So we’re providing the high-level environment variable—not the name or the label. Unfortunately, there is an error in Mattias’s code. I don’t know whether the Bluemix Cloudant service has changed since he wrote it, but he builds the URL for the database by adding the user ID and password to it, but actually these are already in my environment variable URL, so I change line 30 from

var nano = require('nano')('https://' + Cloudant.username + ':' + Cloudant.password + '@' + Cloudant.url.substring(8));
to simply
var nano = require('nano')(Cloudant.url);

Now I save the file and click DEPLOY. When it’s finished a message pops up saying “See Manual Deployment Information in the root folder page.”

Guess the word 6

So I click on that and hopefully see a green traffic light in the middle.

Guess the word 7

If you click on the GuessTheWord hyperlink it should take you to the working game, which in my case is running at

Guess the word 8

However, there are still no scores displayed as there is no database table or entries.

I spent some time trying to do this next part in the code but eventually ran out of time and had to go through the Cloudant website. If anyone can show me how to do this part in code I’d really appreciate it.

So for now, go to the GuessTheWord app on Bluemix and click on the running Cloudant service.

Guess the word 9

From here you get to a LAUNCH button.

Guess the word 10

Pressing the LAUNCH button logs you on to the Cloudant site using single sign-on.

Guess the word 11

Create a new database named guess_the_word_hiscores. Then click the button to create a new secondary index. Store it in a document named top_scores and name the index top_scores_index.

As Mattias says, the map function defines which objects in the database are categorized by the index and what information we want to retrieve for those objects. We use the score as the index key (the first argument to emit) and then emit an object containing the score, the name of the player and the date the score was achieved.

Following is the JavaScript implementation of the map function, which we need to add before saving and building the index.
function(doc) {
emit(doc.score, {score : doc.score, name :, date :});

Guess the word 12

The following URL shown below is a REST command that adds an entry to the database, replacing guessthewordgarforth in the URL with the host name you chose for your application:

You should see a success message. Enter the following URL, again replacing guessthewordgarforth with your application host name.

The entry you just added should appear encoded in JSON, for example:

So, the code and the database are working correctly. Now it just remains to play the game. Go to (replacing guessthewordgarforth with your hostname).

This time it will include Bob in the high score table.

Guess the word 13

Click on Play! and begin the game. Select a box and type a letter to start guessing the secret word.

Guess the word 14

I hope this explanation of how to use the Cloudant database service in a Bluemix application has been helpful and interesting to you. We’ve demonstrated that Bluemix allows you to rapidly develop on the cloud for the cloud, with easy binding, setup and single sign-on to a NoSQL database.

Good luck with your application! I’d appreciate suggestions for improvements so please leave comments or questions below or continue the conversation with me on Twitter @@samjgarforth.

More stories

Why we added new map tools to Netcool

I had the opportunity to visit a number of telecommunications clients using IBM Netcool over the last year. We frequently discussed the benefits of have a geographically mapped view of topology. Not just because it was nice “eye candy” in the Network Operations Center (NOC), but because it gives an important geographically-based view of network […]

Continue reading

How to streamline continuous delivery through better auditing

IT managers, does this sound familiar? Just when everything is running smoothly, you encounter the release management process in place for upgrading business applications in the production environment. You get an error notification in one of the workflows running the release management process. It can be especially frustrating when the error is coming from the […]

Continue reading

Want to see the latest from WebSphere Liberty? Join our webcast

We just released the latest release of WebSphere Liberty, It includes many new enhancements to its security, database management and overall performance. Interested in what’s new? Join our webcast on January 11, 2017. Why? Read on. I used to take time to reflect on the year behind me as the calendar year closed out, […]

Continue reading