shell-local-plugin

An IBM Cloud Functions Shell plugin that lets users run and debug actions in a local docker container. It requires Docker to be pre-installed to your machine.

Install

First, make sure you have the latest Shell and Docker.

$ npm update -g @ibm-functions/shell 

$ docker 

Usage:	docker COMMAND

.......

Install the plugin using Shell's plugin install command (if you are in the Shell app, remove fsh).

[fsh] plugin install shell-local-plugin

After installing the plugin, enter

[fsh] local

to see usage.

The plugin might need to download the Docker image for your action runtime for the first time you use it. This takes about 20 seconds but is a one-time thing.

The plugin will start a container when it is first called, and close that container when you close Shell.

This means that if you are using fsh local play/debug from the terminal (headless mode), the container will be created when the Shell app window appears and removed when the Shell app window is closed. Starting a container takes time. You can avoid this by calling fsh local play/debug from the terminal for the first time and keep that Shell app window opened and enter more local commands in there.

Commands

local debug (currently nodejs only)

Run an action or activation in a local docker container, and open Chrome DevTool in the sidecar for live debugging. Provide input with -p. Return the output data.

[fsh] local debug action_name_or_activation_id [-p name value]

local play

Run an action or activation in a local docker container. Provide input with -p. Return the output data and execution time. This feature is useful to test how long your action runs in a docker container vs. openwhisk.

[fsh] local play action_name_or_activation_id [-p name value]

Troubleshooting

If you see an error like

Error: (HTTP code 500) server error - driver failed programming external connectivity on endpoint shell-local (21466e1d857f1d1132266a786a1498c0a5cab73a6843f7578faeb9a336451d2b): Bind for 0.0.0.0:8080 failed: port is already allocated 

This is becuase some other programs occupy the ports that Shell's docker container is trying to use (port 8080 for sending docker API, and port 5858 for connecting to the debugger). To solve this, first try

docker ps -a 

from the terminal. If you see a container that is using port 0.0.0.0:8080 and/or port 0.0.0.0:5858, close that container using docker kill containerName and docker rm containerName. Then restart Shell and run local debug or local play again.

If the error still exists, use

lsof -i -P -n | grep LISTEN 

to see who are using the ports, and close them.

Current limitations

local debug only works for nodejs actions.

The plugin cannot debug/play a sequence; you can select child action activations and debug/play them one by one.

The port numbers our Shell docker container uses are fixed (8080 and 5858). I might extend the plugin to allow specifying custom ports.