Using OpenWhisk Outside IBM Bluemix

OpenWhisk is a fantastic addition to the IBM Bluemix ecosystem and to the constellation of cloud-ready, open-source software. At a recent meetup that the IBM Bluemix group organized in Austin, TX, I gave a lightning talk on OpenWhisk, explaining its general concepts and how to install it wherever you want without signing up for Bluemix. If you want to know more about OpenWhisk and its inner workings, you can readthis and this posts that go a long way to explain what OpenWhisk is and how it works.

In this post, we will explore how to install, deploy, and run OpenWhisk in a local environment.

Preparing your environment

A very good way to test and try new software is using a virtual machine, and Vagrant is absolutely awesome at providing the virtual machine we need. I have prepared a Vagrantfile ready for you to use, so let’s grab it:

mkdir openwhisk && cd openwhisk
wget https://raw.githubusercontent.com/eljuanchosf/openwhisk-setup/master/Vagrantfile

Now you are ready to power on your virtual machine with the well-known vagrant up command. When it is up and running, use the vagrant ssh command to get inside. Once inside the server, you will need to install Git and then clone the OpenWhisk repository:

sudo apt-get install git -y
git clone https://github.com/openwhisk/openwhisk.git
cd openwhisk Setting up the persistence layer

OpenWhisk requires a database to persist the actions, rules, dictionaries, etc. If you are in Bluemix, it is logical to use Cloudant; however, if you are in your local machine or working with a custom deployment, CouchDB is a very good option.

Since the OpenWhisk installation script and the Ant build are customized for Ubuntu (or any Debian-based distro, in fact), the first step is to add the repository for CouchDB and install it:

sudo add-apt-repository ppa:couchdb/stable -y
sudo apt-get update
sudo apt-get install couchdb -y

Now, we are going to define a couple of environment variables that will make our life so much easier later on:

export DB_USER=iamkyloren
export DB_PASSWORD=ILoveYouGrandPa
export DB_HOST=$(ip route get 8.8.8.8 | awk '{print $NF; exit}')
export DB_PORT=5984 CouchDB for everybody

OpenWhisk is shipped with a script that starts a Dockerized CouchDB instance, but because it is a container, it will be gone when you reboot your VM. Setting up an external database server is easy, but this small security step is often overlooked and can result in a very frustrating exercise. What you need to do is to configure CouchDB to bind to the right IP address so that OpenWhisk will be able to connect from its container to the database.

CouchDB has a config file that specifies the configuration values for a local instance. In a standard Ubuntu setup, you can find it at /etc/couchdb/local.ini . Inside this file, there is a line containing the ;bind_address = 127.0.0.1 text. Uncomment that line (remove the semicolon) and then change 127.0.0.1 (listen on the localhost only) to the public IP address of the server that is running CouchDB. In this case, and because we started up the Vagrant image with default values, it is going to be 192.168.33.13 , which we have already defined in the DB_HOST environment variable.

In one line (all right, all right, two lines), you can do it as:

sudo sed -i -- "s/;bind_address = 127.0.0.1/bind_address = $DB_HOST/g" /etc/couchdb/local.ini
sudo service couchdb restart The basics

Now, it is time to set up the basic structure for the database. CouchDB uses an HTTP API to manage all of its structure and data. First, create an admin user:

curl -X PUT http://$DB_HOST:$DB_PORT/_config/admins/$DB_USER -d '"'"$DB_PASSWORD"'"'
curl -X GET http://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/_config

The second command will get the information about the CouchDB configuration. If the user creation is successful, you’ll see a JSON object with CouchDB settings.

Next, we should tell OpenWhisk how to connect to our database server. For this purpose, the couchdb-local.env file must be created, and OpenWhisk comes with a template that is easy to edit:

cp template-couchdb-local.env couchdb-local.env

Now, replace the variables in couchdb-local.env :

sed -i -- "s/OPEN_WHISK_DB_PROTOCOL=/OPEN_WHISK_DB_PROTOCOL=http/g" couchdb-local.env
sed -i -- "s/OPEN_WHISK_DB_HOST=/OPEN_WHISK_DB_HOST=$DB_HOST/g" couchdb-local.env
sed -i -- "s/OPEN_WHISK_DB_PORT=/OPEN_WHISK_DB_PORT=$DB_PORT/g" couchdb-local.env
sed -i -- "s/OPEN_WHISK_DB_USERNAME=/OPEN_WHISK_DB_USERNAME=$DB_USER/g" couchdb-local.env
sed -i -- "s/OPEN_WHISK_DB_PASSWORD=/OPEN_WHISK_DB_PASSWORD=$DB_PASSWORD/g" couchdb-local.env

It is all about the structure

OpenWhisk requires creating a basic table structure, and the guys who developed it are kind enough to provide a script that does exactly that:

tools/db/createImmortalDBs.sh

The script will create a couple of tables and insert data, and prepare your database for OpenWhisk. Remember that it will ask you to enter the DROPIT word for confirming that you want to set up the database structure from scratch.

Installation time!

Installing OpenWhisk is easy due to the provided script. But first, and just to be sure, download and add Docker’s new GPG:

curl -fsSL https://get.docker.com/gpg | sudo apt-key add -

And now, let the magic happen:

(cd tools/ubuntu-setup && source all.sh)

Yeah. That’s all.

Build

After OpenWhisk has been installed, we have to build, deploy, and run it. First, exit your Vagrant SSH session. Then, run the vagrant reload command (this ensures that the operating system has all the latest values that came from the installation up and running) and SSH back in using the vagrant ssh command.

Now, we need to build. OpenWhisk is developed in Scala , which runs on the JVM, and the build tool of choice is Ant :

cd openwhisk && ant build clean deploy run

After some time (the build process is quite long) and after the required tests pass, you will have a working OpenWhisk server!

OpenWhisk is not difficult to set up, but it has its nuances. You can easily deploy it on any IaaS of your choice following this guide.

For more on using OpenWhisk on IBM Bluemix, you may also check out these how-tos: “ Developing a Microservice with OpenWhisk ” and “ Creating Docker Actions .”

Also, you might want to check this repo for an easy way of deploying OpenWhisk.