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

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 the 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 

  • Click on CATALOG from the topbar (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 name of 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>

Starter Code

On the success page, scroll down a bit  and click on “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


The 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,

Quick video showing you what we achieved till now

Using Node.JS runtime

If you don’t want to use a boiler plate starter code and 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 on the left pane and you should 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 your how to create a Node.JS runtime with Cloudant service

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.

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.

Means it’s not available when your 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!!

Happy coding!!!

Polyglot & Pragmatic Programmer • Developer Advocate, IBM Cloud • Intel software Innovator • DZone MVB
(Visited 38 times, 1 visits today)

You may also like...

Show Buttons
Hide Buttons