OpenWhisk is a cloud-first, distributed event-based programming service. It provides a programming model to upload event handlers to a cloud service and register the handlers to respond to various events. The following diagram shows the OpenWhisk model. Triggers come from cloud sources to the Whisk server. The events are processed based on rules that are enforced by the Whisk runtime, which invokes the appropriate service to respond and send back the results to the caller.

OpenWhisk architecture diagram

In this post, I’ll show you how to get Whisk installed and we’ll take a look at a few samples that come with it. I’ll also provide some tips to run Whisk on Windows using a Vagrant virtual machine backed by the VirtualBox hypervisor. OpenWhisk has been fully tested on Ubuntu Linux and on Mac OS/X. It’s not currently supported to run natively on Windows, but you can run it in a virtualized environment on top of Windows. Regardless of the operating system, OpenWhisk must be built and then deployed on the target environment.

Installing OpenWhisk

If you are running outside of Ubuntu, and VirtualBox and Vagrant are not installed on your system, install them now. After installing Virtualbox and Vagrant, complete the following steps: Note: If you are already running on Ubuntu then skip to step 2.

1. Setup the VM

The OpenWhisk team has provided instructions on how to install a Vagrant VM on top of VirtualBox. You download VagrantFile from the OpenWhisk repository and use it to configure the VM, run the build, and deploy an Ant script to install and configure OpenWhisk.
md ow
cd ow
Download file VagrantFile using either wget, or Windows' powershell command Invoke-WebRequest (alias iwr) If you are using powershell’s iwr command then at the powershell command line, issue the following:
iwr -OutFile VagrantFile
If using wget, simply issue the following command:
Now that you have downloaded VagrantFile, you are ready to provision the VM. Issue the following command:
vagrant up
It should take a few minutes to pull the disk file that contains the VM code from the network (the size is approximately 256MB) and process all the commands in file VagrantFile. Information messages will display on your screen while vagrant provisions the virtual machine. You can use either Putty on Windows or SSH on Linux and Mac, or use the terminal created by VirtualBox to access the VM. The default IP address for the VM is The user/password is vagrant/vagrant.

2. Configure your system to build OpenWhisk

Note: Whether you are running on native Ubuntu or on the Vagrant VM, log onto your machine. For the Vagrant VM, the home directory is /home/vagrant; for the Ubuntu machine it will be your default home directory. Whenever these instructions refer to /home/vagrant, replace it with $HOME or your home directory.

If git is not already installed, install it now with the following command:

sudo apt-get install git

3. Set up a Cloudant datastore

Use Cloudant on Bluemix. Note that you will need a Bluemix ID. You will use the Cloud Foundry command line tool cf to send the appropriate commands to Bluemix to create the Cloudant backing store. If cf is not installed, use the following commands to install it:
cd /usr/bin

sudo wget -O cf.tgz 

sudo tar xvzf cf.tgz
Now use cf to create a Cloudant service that you will use to create the datastore:

 # Create a Cloudant service
 cf create-service cloudantNoSQLDB Shared cloudant-for-whisk

 # Create Cloudant service keys
 cf create-service-key cloudant-for-whisk whisk

 # Get Cloudant service keys
 cf service-key cloudant-for-whisk whisk 
The last command will display the credentials for your Cloudant service. You will use these credentials later to create and populate the tables that OpenWhisk needs. Note: If you don’t have a Bluemix account you can get a Cloudant account directly.

Preparing to build OpenWhisk

3. Clone the code from GitHub


git clone
This command pulls the OpenWhisk code to your local machine. Next, you’ll create one environment file with the Cloudant credentials.

4. Create file cloudant-local.env

cd openwhisk
Save the Cloudant credentials in the environment. Cut and paste the following commands into your command line:
export cloudant_user=`cf service-key cloudant-for-whisk whisk | grep username | awk -F : '{print $2}' | sed 's/[\"\, \t]//g'` && export cloudant_pwd=`cf service-key cloudant-for-whisk whisk | grep password | awk -F : '{print $2}' | sed 's/[\"\, \t]//g'`
Create the file cloudant-local.env by cutting and pasting the commands below into you command line:
echo "OPEN_WHISK_DB_USERNAME=$cloudant_user">cloudant-local.env && echo "OPEN_WHISK_DB_PASSWORD=$cloudant_pwd">>cloudant-local.env

5. Create the Cloudant datastore

tools/cloudant/ $cloudant_user $cloudant_pwd
You will receive a confirmation that you want to create the datastore. Type the following:
You will see text informing you that the operation is underway. An excerpt:
Create immortal key for guest ...
Create immortal key for whisk.system ...
Now configure the VM to build and deploy OpenWhisk.
cd /home/vagrant/openwhisk/tools/ubuntu-setup && source
echo 'export PATH=$HOME/openwhisk/bin:$PATH' > /home/vagrant/.bash_profile
echo 'eval \"$(register-python-argcomplete wsk)\"' >> /home/vagrant/.bash_profile
Reboot your machine or reboot the VM. For the VM, issue the following command:
vagrant reload
Important note: vagrant reload is the prescribed way to reboot the system; otherwise you could lose important data.

6. Build and deploy OpenWhisk on the Vagrant VM

Log in to the VM or your Ubuntu machine once it is rebooted.
cd openwhisk
ant clean build deploy
Note: The first build will take some time as it fetches numerous dependencies from the internet. The duration of this step will depend on your network speed. Once deployed, several Docker containers will be running in your virtual machine. Since the first build takes so long, it’s not uncommon for some steps to fail if there’s a network hiccup or other interruption. If that happens, you might see a Build FAILED message that suggests a Docker operation timed out. You can simply try to build again and for the most part it will pick up where it left off. This should only be an issue the first time you build Whisk — subsequent builds have far less network activity due to Docker caching. Note: When building or deploying, ensure that you issue your commands from the $HOME/openwhisk directory.

Testing your OpenWhisk setup

7. Try your first HelloWorld OpenWhisk program

#do this once. Set the authorization so you don't have to do it each time you issue a wsk command
wsk property set --auth $(cat $HOME/openwhisk/config/keys/auth.guest)

#run your helloworld application
wsk action invoke /whisk.system/samples/echo -p message hello --blocking --result
The system should respond with:
   "message": "hello"

Learn more

This has been a quick preview to get you up and running with OpenWhisk, but of course you’re just getting started. There’s a wealth of information available to help you really dig into OpenWhisk development. For more information on getting started, and to run more samples, see the OpenWhisk Getting Started documentation. For conceptual information, architecture, blogs, and other resources, see the IBM Bluemix OpenWhisk Developer Center. And if you have any questions about what I’ve shown you here, drop me a line or leave a comment below. I’d love to hear about your experiences with OpenWhisk.

2 comments on"OpenWhisk: A quick tech preview"

  1. Hi Marc

    When I am trying to execute the ‘tools/db/’ command, I run into this error.

    tools/db/ line 28: /home/i844441/openwhisk/tools/db/../../config/ No such file or directory
    Unrecognized OPEN_WHISK_DB_PROVIDER: ”

    I don’t see a file anywhere in the repo.

    Any Ideas?
    Appreciate your time.


  2. Marc-Arthur_Pierre-Louis November 15, 2016

    Hi PJ. There is a more streamlined version on Github. Use it there @
    I will update these instructions to reflect that.

Join The Discussion

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