Skip to content

Latest commit

 

History

History
205 lines (138 loc) · 7.72 KB

README.md

File metadata and controls

205 lines (138 loc) · 7.72 KB
Raw

How to setup OpenWhisk with Docker Compose

Build Status

An easy way to try OpenWhisk locally is to use Docker Compose.

Prerequisites

The following are required to build and deploy OpenWhisk with Docker Compose:

These ports must be available:

  • 80 and 443 for the API Gateway
  • 2181 for Zookeeper
  • 5984 for CouchDB
  • 8085 for OpenWhisk's Invoker
  • 8888 for OpenWhisk's Controller
  • 9092 for Kafka
  • 8001 for Kafka Topics UI

Quick Start

make quick-start

This command downloads the master branch from the OpenWhisk repo, it builds OpenWhisk, the docker containers, it starts the system and it executes a simple hello-world function. At the end of the execution it prints the output of the function:

{
    "payload": "Hello, World!"
}

If OPENWHISK_PROJECT_HOME variable is set ( i.e. OPENWHISK_PROJECT_HOME=/path/to/openwhisk make quick-start) then the command skips downloading the master branch and uses instead the source code found in the PROJECT_HOME folder. This is useful for working with a local clone, making changes to the code, and run it with docker-compose.

This is the set of environment variables that can be set:

  • OPENWHISK_PROJECT_HOME - a checkout of openwhisk
  • OPENWHISK_CATALOG_HOME - a checkout of openwhisk-catalog
  • WSK_CLI - the directory where the wsk command line tool can be found
  • DOCKER_IMAGE_PREFIX - the prefix of the docker images used for actions. If you are building and testing checkouts of runtimes locally, then consider setting this to whisk.

Note that these are all optional and only need to be set if you have a local checkout that you want to use.

Updating OpenWhisk Invoker or Controller

To update the OpenWhisk Invoker or Controller without restarting everything, run:

make restart-invoker

This command destroys the running Invoker instance, waits for the controller to figure out the invoker is down, then it starts a new Invoker, also waiting until it's marked as up.

To do the same with the controller run:

make restart-controller

Troubleshooting

  • error: Authenticated user does not have namespace 'guest'; set command failed: Get https://localhost:443/api/v1/namespaces: dial tcp [::1]:443: getsockopt: connection refused

    Make sure nothing runs on the above listed ports. Port 80 might be commonly in use by a local httpd for example. On a Mac, use sudo lsof -i -P to find out what process runs on a port. You can turn off Internet Sharing under System Settings > Sharing, or try sudo /usr/sbin/apachectl stop to stop httpd.

  • error: Unable to invoke action 'hello': There was an internal server error. (code 5)

    Look at the logs in ~/tmp/openwhisk especially ~/tmp/openwhisk/controller/logs/controller-local_logs.log that might give more information. This can be an indication that the docker environment doesn't work properly (and on Mac you might need to switch to use Docker for Mac.

  • Check the issue tracker for more.

Build

make docker

This command builds the docker containers for local testing and development.

NOTE: The build may skip some components such as Swift actions in order to finish the build faster.

Start

make run

This command starts OpenWhisk by calling docker-compose up, it initializes the database and the CLI.

Stop

The following command stops the docker-compose:

make stop

To remove the stopped containers, clean the database files and the temporary files use:

make destroy

Running a hello-world function

Once OpenWhisk is up and running you can execute a hello-world function:

make hello-world

This command creates a new JS action, it invokes it, and then it deletes it. The javascript action is:

function main(params) {
    var name = params.name || "World";
    return {payload: "Hello, " + name + "!"};
}

The result of the invokation should be printed on the terminal:

{
    "payload": "Hello, World!"
}

Here is a tutorial on getting started with actions.

Install Catalog Packages

OpenWhisk has numerous extra packages that are often installed into the /whisk.system namespace.

These are not included by default with the devtools make quick-start command.

If you want to install these packages, run the following make command.

make add-catalog

Once the installation process has completed, you can check the whisk.system namespace to verify it those packages are now available.

wsk package list /whisk.system

Updating Containers

If you want to pull new containers you can use make pull to update all the containers used in the docker-compose file.

Install Feed Providers

OpenWhisk supports feed providers for invoking triggers from external event sources.

Feed provider packages are not included by default with the devtools make quick-start command.

Providers for the alarms, kafka and cloudant feeds can be installed individually using the make command.

make create-provider-alarms
make create-provider-kafka
make create-provider-cloudant

Once the installation process has completed, you can check the whisk.system namespace to verify it the feed packages are now available.

wsk package list /whisk.system

Logs

  • OpenWhisk Controller - ~/tmp/openwhisk/controller/logs/
  • OpenWhisk Invoker - ~/tmp/openwhisk/invoker/logs/
  • docker-compose logs - ~/tmp/openwhisk/docker-compose.log
  • docker-compose feed provider logs - ~/tmp/openwhisk/docker-provider-compose.log
  • Feed provider instance logs - ~/tmp/openwhisk/<feed_name>provider
  • Action output such as stdout or console.log(): wsk -i activation logs <activationId>

Custom Docker containers for actions

To start docker-compose with custom images used for running actions use the following 2 variables:

  • DOCKER_REGISTRY - specify a custom docker registry. I.e DOCKER_REGISTRY=registry.example.com make quick-start
  • DOCKER_IMAGE_PREFIX - specify a custom image prefix. I.e. DOCKER_IMAGE_PREFIX=my-prefix make quick-start

These 2 variable allow you to execute a JS action using the container registry.example.com/my-prefix/nodejs6action.

Local Docker containers for controllers and invokers

By default this setup uses published images for controller and invokers from openwhisk namespace i.e. openwhisk/controller and openwhisk/invoker. To make use of locally build images you can use DOCKER_OW_IMAGE_PREFIX variable i.e. DOCKER_OW_IMAGE_PREFIX=whisk make quick-start