Securely Connect to Cloudant Service From Node.JS With IBM Bluemix

DZone 's Guide to

Securely Connect to Cloudant Service From Node.JS With IBM Bluemix

In this article, we'll discuss how to securely connect to your Cloudant DB using Node.JS with IBM Bluemix. Read on for more details.

· Cloud Zone ·
Free Resource

IBM Cloudant is a NoSQL JSON document store that’s optimized for handling heavy workloads of concurrent reads and writes in the cloud—a workload that is typical of large, fast-growing web and mobile apps. You can use Cloudant as a fully-managed DBaaS running on public cloud platforms like IBM SoftLayer or via an on-premise version called Cloudant Local, that you can run yourself on any private, public, or hybrid cloud platform you choose.

Securely connecting to your Cloudant DB is the first and most important thing for any CRUD (Create, Read, Update, Delete) operation to take place. Securely?! Yes, there's always a chance that one of us may store our DB credentials in a file like .env and push it to a public repo. To avoid this credential exposure which may cause unwanted consequences, VCAP_SERVICES environment variable, a JSON Object is introduced to safeguard the information which includes service instance name, credential, and connection URL to the service instance.

Node.JS + Cloudant Boilerplate App

Let's create a Node.js boilerplate application which talks to Cloudant DB for data. If you don't own a Bluemix account yet, Create one at https://bluemix.net

  • Click on CATALOG from the top bar (Classic Experience)

Bluemix topbar

  • Navigate to "Boilerplates" under Starters on the left pane.
  • Select "Node.JS Cloudant DB Web starter".

Now, you should see a page with an option on the right pane to enter a name for your application.NodeJS Cloudant Webstarter kit

  • Enter a name of your choice and click create.

Congratulations! You have successfully created a Node.JS application with Cloudant service running at: HTTP://<name of the App>.bluemix.net

Starter Code

On the success page, scroll down a bit  and click on the "DOWNLOAD STARTER CODE" button to download your starter code.

  • Open the code in any IDE of your choice. I will be using brackets as an IDE here.
  • Navigate to the heart of the application which is app.js file and as you walk through the code you should see this:

BracketsThe starter code provides you a sample Favorites Organizer application with Cloudant CRUD code snippets.

To see the VCAP_SERVICES Cloudant JSON, navigate to your application under DASHBOARD and click on Environment Variables on the left pane. You should see the below JSON with your credentials and URL,

   "cloudantNoSQLDB": [
         "name": "CloudantNodeJSApp-cloudantNoSQLDB",
         "label": "cloudantNoSQLDB",
         "plan": "Shared",
         "credentials": {
            "username": "",
            "password": "",
            "host": "",
            "port": 443,
            "url": ""

Quick video showing you what we've achieved so far:

Connect to your Cloudant service from NodeJS. Securely on IBM Bluemix from Vidyasagar MSC on Vimeo.

Using Node.JS Runtime

If you don't want to use a boilerplate starter code and are looking to start from scratch, you can achieve the above scenario using Node.JS runtime.

  • Navigate to CATALOG and on the left pane click on Runtimes under Compute.
  • Select "SDK for Node.JS" and give it a name.
  • Once the runtime is successfully created, click on Overview in the left pane and you should see an option to add a new service or bind an existing service.
  • Click on "Add a new service or API" and select Cloudant service under Data & Analytics on the left pane.

Quick video showing you how to create a Node.JS runtime with Cloudant service:

Node.JS Runtime with Cloudant Service on IBM Bluemix from Vidyasagar MSC on Vimeo.

If you observe, you won't find VCAP_Services in the app.js file. Add the below code snippet just before the last closing brace of app.js.

if (process.env.VCAP_SERVICES) {
        // Running on Bluemix. Parse the port and host that we've been assigned.
        var env = JSON.parse(process.env.VCAP_SERVICES);
        var host = process.env.VCAP_APP_HOST;
        var port = process.env.VCAP_APP_PORT;
        // Also parse Cloudant settings.
        var credentials = env['cloudantNoSQLDB'][0]['credentials'];
        username = credentials.username;
        password = credentials.password;


There are two key things to be aware of  while using VCAP_SERVICES at this point...

When running or testing locally, VCAP_SERVICES won't be available so your Node.JS app will return an error. One way to resolve this is to push your code to GIT and deploy the code as and when there are critical updates or changes to the code.


The value of the VCAP_SERVICES environment variable is available only when you bind a service instance to your application.

This means that it's not available when you create a Cloudant service alone. It should be bound to an application.

My next blog post will be on how to run your Node.JS Cloudant app locally for testing. Stay Tuned!

Related Refcard:

bluemix, cloud, cloudant, ibm bluemix, node js, node.js, nosql, tutorial

Published at DZone with permission of Vidyasagar Machupalli , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}