How I setup OpenWhisk to use a local CouchDB

Datetime:2016-08-23 00:54:05          Topic: CouchDB           Share

OpenWhisk is a cloud-first distributed event-based programming service that lets you to execute code in response to events. You can try OpenWhisk on Bluemix and also build and deploy OpenWhisk on your own machines. When I went to set up OpenWhisk and run it locally, I was presented with several choices for a backend data store. Couch DB sounded like a good choice locally because I could use it using both HTTP and HTTPS protocols.

CouchDB is an open source JSON database management system released under the Apache 2 license and distributed with Ubuntu. So, installing CouchDB on an Ubuntu system is straight forward. Using a locally installed CouchDB instance is better than using one installed in a container because you won’t have to wrestle with container limitations. Your data will be persisted in a local database instance, so you won’t need to run the creation scripts and initialize the data store multiple times.

The directions in the project README seemed a bit much, so I wanted to share the steps I used to set up my CouchDB. Follow along for step-by-step instructions on how to install and configure a self-managed CouchDB instance on your local machines.

Installing CouchDB

CouchDB can be installed on Windows, Mac OS X, and Ubuntu systems. In this tutorial, I use Ubuntu 14.04 running on a VirutualBox VM. Install CouchDB with the following command:

sudo apt-get install -V couchdb

Verify that the installation is successful with the following command:

curl –k

You get a response similar to this:

Configuring CouchDB

Although CouchDB is installed and its corresponding service is started, you need to complete the following steps to integrate it with OpenWhisk.

  1. Set the database administrator user name and password:
  2. CouchDB stores user names and passwords in a file called local.ini. Only system administrators should have the permissions to access this file. Administrators can be added directly to the [admins] section.

    Edit /etc/couchdb/local.ini , and add the user name and password to the [admins] section. You may need to sudo to edit the file.

    For example, if you want to add a database user root with the password wskdbpass , add the line in bold typeface to the [admins] section, as shown below:

    root = wskdbpass

    When CouchDB is restarted, the password will be encrypted.

  3. Configure the IP address
  4. By default, CouchDB is configured to use localhost ( . The content of /etc/couchdb/default.ini where the default IP address is stored is :

    bind_address =

    If you don’t change the value of setting bind_address, your CouchDB instance will not be reachable from external hosts. Change it to the actual IP address you want to use or you set it to to make CouchDB listen to any available IP address. In my case, I set it to because my CouchDB instance is running in a VirutualBox image whose IP address changes every time I reboot.

    So, edit /etc/couchdb/default.ini . Go to [httpd] section and update the bind_address setting to the actual IP address. For example:

    bind_address =

    Restart CouchDB with this command:

    sudo restart couchdb

    Verify that CouchDB is listening to the new IP address (or whatever IP is assigned to your system via DHCP; use ifconfig to find out the IP address if using DHCP):

    curl –k 
    (if using DHCP your IP address will be different)

    Installing OpenWhisk

    Although CouchDB is configured and running on a local machine, it does not have to run on the same machine where OpenWhisk is installed. You will now configure OpenWhisk on a different VM to use the CouchDB instance you just configured. Follow the instructions in the OpenWhisk to build and deploy OpenWhisk. To install OpenWhisk, I am using a Vagrant machine on a MacBook.

    1. Download and install Vagrant from
    2. Fetch the Vagrantfile used to configure the Vagrant VM.
    3. wget
    4. Start the VM.
    5. vagrant up
    6. Log in to the VM.
    7. vagrant ssh
    8. Download the OpenWhisk source code from the github repo.
    9. git clone
    10. In the OpenWhisk subdirectory where the source is downloaded, copy the file template-couchdb-local.env to couchdb-local.env and change the appropriate settings. Please pay attention here. You can NOT set “localhost” or “” to OPEN_WHISK_DB_HOST, because CouchDB should be accessible not only in the host server but also in Docker containers. Your host server may be able to access CouchDB with the address “localhost” and “”, but Docker containers cannot. So you must use the actual IP address, or else you will be caught by failures when deploying OpenWhisk. That’s why we configured the bind_address of CouchDB before.
    11. For example:

    12. In order to create a test account for your OpenWhisk setup, you need to run tools/db/ . It will configure the database and create a guest subject for testing purposes.
    13. Build and deploy OpenWhisk on the VM.
    14. ant clean build deploy

      The build may take 25 minutes to an hour or more depending on your network speed. Then OpenWhisk will be installed on your local machine with a local CouchDB as database server on another VM.

      Invoke your first action

      Now you have the OpenWhisk installed. You may want to try a simple action to make sure your OpenWhisk setup is properly configured. The simple way to invoke OpenWhisk action is to use OpenWhisk CLI. Before using the OpenWhisk CLI, there are still 2 additional steps. You need to add OpenWhisk CLI command to your path and you need to set the authorization key. Then you can try to invoke your first action.

      1. Add OpenWhisk CLI command to your path with below command:
      2. export PATH=$HOME/openwhisk/bin:$PATH
      3. Set the authorization key used by CLI. Here I use the guest authorization key:
      4. wsk property set --auth $(cat config/keys/auth.guest)
      5. Then you are ready to invoke actions now. Let’s try the simple “echo” built-in action:
      6. wsk action invoke /whisk.system/samples/echo -p message hello --blocking --result

        It should respond with the following

             "message": "hello"

        If you get the above message, then you have a working OpenWhisk setup.

        As you can see, it’s rather simple to configure OpenWhisk with a local instance of CouchDB. You are welcome to experiment with other actions in order to experience the power of this innovative platform. For more information, see the references below to interact with all the components that make OpenWhisk work.


About List