Get Started With Cloudant in IBM Cloud

Watch this short video to see how to provision IBM Cloudant on IBM Cloud, create a database, load some data, and see a quick tour of the Cloudant dashboard.

Get Started With the Cloudant Dashboard

This video provides an overview of each panel in the Cloudant dashboard.

Create a Cloudant account

You can create a Cloudant account and connect your IBM Cloud app to a Cloudant database in one of the following ways:

After you connect, understand how the connection works and where to find details.

Add Cloudant Service through the IBM Cloud dashboard

If you’re working in IBM Cloud, add a new Cloudant data service in just a few clicks:

  1. Visit your IBM Cloud dashboard.
  2. Click Catalog.
  3. Check the Dataases category.
  4. Select Cloudant.
  5. Enter a descriptive name in the Service name field.
  6. Select a region, resource group, and authentication methdod. If you need help deciding on which authentication method to use, see IBM Cloud Identity and Access Management in the Cloudant documentation.
  7. Select a pricing plan that fits your needs. You can always start with the free plan and upgrade later through the Cloudant dashboard.
  8. Click Create.
  9. From your dashboard, open the Cloudant service instance.
  10. On the Connections tab, select create a connection to the app you want to access Cloudant.
  11. Locate your database details under the Service Credentials tab.
  12. Back on the Manage tab, click Launch to open the Cloudant dashboard.

Deploy and connect manually

If you prefer to work locally, you can deploy an app to IBM Cloud and add Cloudant service from a command line interface by using the CloudFoundry cf tool.

  1. Install the Cloud Foundry command line interface and connect to IBM Cloud .
  2. Create a Cloudant service within IBM Cloud:
    $ cf create-service cloudantNoSQLDB Shared <cloudant_service_name> 
  3. Bind the service to your app:
    $ cf bind-service <bluemix-app-name> <cloudant-service-name>

Connect an existing Cloudant database to your IBM Cloud app

So you created a Cloudant database on and now you’ve got a nifty IBM Cloud app. How do you connect them together?

The answer is: Don’t add Cloudant Service via IBM Cloud. Instead, within your app’s code, call your existing Cloudant database through the HTTP API as you normally would. More on using the API.

Why bypass IBM Cloud’s Cloudant Service? When you add the Cloudant Service to your IBM Cloud app, IBM Cloud creates a new mulit-tenant instance of Cloudant, and you can’t edit the connection to point to your existing database. So don’t add the Cloudant service, but go ahead and take advantage of other IBM Cloud services and features.

Can I replicate instead?

If your database is on a dedicated cluster, you must connect only through your app’s code. But, if you’re using a multi-tenant instance of Cloudant, and you don’t mind moving your data, you could create a new Cloudant service on IBM Cloud and replicate your existing data into that new IBM Cloud database service. To do so:

  1. In IBM Cloud, add a Cloudant service instance.
  2. Get the database details from the Service Credentials.
  3. Set up a replication job to copy data from your existing database to the new IBM Cloud Cloudant service database.

How the connection works

Once you connect your IBM Cloud app to Cloudant, you’ll find the following connection details service credentials.

  "cloudantNoSQLDB": {
    "name": "appname-cloudant-service",  
    "label": "cloudantNoSQLDB",   
    "plan": "shared",
    "credentials": {
      "username": "randomlyassignedusername",  //IBM Cloud-generated random string 
      "password": "secret",   //IBM Cloud-generated random string
      "host": "", //yourhost is a IBM Cloud-generated random string
      "port": 443,
      "url": "" //url of your app's Cloudant instance

Access service credentials in one of two ways:

Access Cloudant through the dashboard

Once you’ve added Cloudant service, you can access your app’s Cloudant dashboard through IBM Cloud:

  1. In IBM Cloud, open the app using the Cloudant service.
  2. Navigate to the Connections tab.
  3. Click the Cloudant service.
  4. On the Cloudant service launch page, click Launch.

    Your app’s instance of Cloudant opens to the dashboard screen.

4 comments on"Get started"

  1. Diego Daniel Martínez August 28, 2018

    The tutorials that I see always says that generates in Api Key a password now with the IAM does not generate the password.

  2. ClaudiuGonciulea August 11, 2019

    Retrieve your VCAP_SERVICES JSON object via Terminal or command line interface URL redirect to a not found page.

Join The Discussion

Your email address will not be published. Required fields are marked *