This README walks you through how to build, customise and test Apache OpenWhisk Node.js runtime images.
Choose a NodeJS version. All build files reside inside core/nodejsActionBase. If you take a look into core/nodejsActionBase/Dockerfile you’ll see a line that looks like:
FROM node:lts-stretch
This will use the latest NodeJS version. But we want to be more specific. Now if you look into each of the Dockerfile within core/nodejs14Action, core/nodejs16Action, core/nodejs18Action, you’ll notice different NodeJS versions. Let’s go ahead with the 18 version, we are going to use this throughout this README. For the other versions, you merely have to modify the version number.
Gradle will a create build folder that will contain all the necessary files to build our NodeJS container. Next, it will copy the NodeJS application ( server used to implement the action interface ) as well as the target Dockerfile with the NodeJS version 18.
What Gradle does is equivalent to running these commands
mkdir build
cp -r core/nodejsActionBase/* build
cp core/nodejs18Action/Dockerfile build
Now, run the distDocker command to generate a local Docker image for the chosen runtime version. (Make sure docker daemon is running)
./gradlew core:nodejs18Action:distDocker
This will return the following runtime image with the name action-nodejs-v18. Since a docker image is created, you can check the IMAGE ID for nodejs-action-v18
docker images
For the testing purpose, we are going to start the container locally that has Node.js app server inside. The Apache OpenWhisk platform uses this server to inject action code into the runtime and fire invocation requests. In order to access this service within the container from the outside, as we are about to do using curl, port mapping needs to be done next. As a result, we can now access the web service inside docker by first reaching an IP port on localhost, which subsequently forwards the request to the docker container's designated port.
In our example, the Action container exposes port 8080 (see the Dockerfile for the associated Docker image), thus we publish the container's port 8080 to the localhost (here, port 3008 on localhost is chosen arbitrarily, as long as the port is not already used for something else):
docker run --publish 3008:8080 --name=bloom_whisker -i -t action-nodejs-v18:latest
A simpler way is to map port 80 on localhost to the container's port 8080. The port number assigned to the HTTP protocol is 80. Since we will be sending actions against the runtime using HTTP, using this number will allow us to omit the port in the request later. Oftentimes, port 80 could already be occupied by another process. Without loss of generality, the following examples will use the arbitrarily chosen port 3008.
Lists all running containers
docker ps
or
docker ps -a
You should see a container named bloom_whisker being run.
A container can only hold one function. This first example prepared a js-init.json file which contains the function.
{
"value": {
"name" : "nodejs-helloworld",
"main" : "main",
"binary": false,
"code" : "function main() {return {payload: 'Hello World!'};}"
}
}The json file contains a simple JavaScript (the target runtime language) function, which is the actual payload.
Before issuing the action against the runtime, we first initialize the function with by invoking the /init endpoint with the js-init.json payload.
curl -H "Content-Type:application/json" -X POST --data '@/docs/users/standalone/helloworld/js-init.json' http://localhost:3008/init
the expected response being
{"ok":true}
As mentioned above, if port 80 on localhost was used, the command could simply be
curl -H "Content-Type:application/json" -X POST --data '@/docs/users/standalone/helloworld/js-init.json' http://localhost/init
Invoke the function using the /run endpoint.
curl -H ""Content-Type:application/json" -X POST --data '@//docs/users/standalone/helloworld/js-init.json' http://localhost:3008/run
The JavaScript function in this example is one without arguments (nullary function). Using the same json file as during initialization won't be a problem. Ideally, we should have provided another file js-params.json with the arguments to trigger the function.
{
"value": {}
}In this case the command to trigger the function should be
curl -H ""Content-Type:application/json" -X POST --data '@/docs/users/standalone/helloworld/js-params.json' http://localhost:3008/run
The expected response should be
{"payload":"Hello World!"}
Also the running container will print the following message in the terminal
XXX_THE_END_OF_A_WHISK_ACTIVATION_XXX
If your container still running from the previous example you must stop it before proceeding. Because each NodeJS runtime can only hold one function which cannot be overridden.
Create a file called js-init-params.json that contains the function to be initialized
{
"value": {
"name": "js-helloworld-with-params",
"main" : "main",
"binary" : false,
"code" : "function main(params) { return {payload: 'Hello ' + params.name + ' from ' + params.place + '!!!'} }"
}
}Also, create a file called js-run-params.json which contains the parameters for triggering the function.
{
"value": {
"name": "Visitor",
"place": "Earth"
}
}These files shall be sent via the init API and via the run API respectively.
To initialize the function, please make sure your NodeJS runtime container is running.
First, issue a POST request against the init API using curl:
curl -H "Content-Type:application/json" -X POST --data '@/docs/users/standalone/helloworldwithparams/js-init-params.json' http://localhost:3008/init
Next, trigger the function by issuing this request against the run API using curl:
curl -H ""Content-Type:application/json" -X POST --data '@/docs/users/standalone/helloworldwithparams/js-run-params.json' http://localhost:3008/run
You should expect the following client response:
{"payload": "Hello Visitor from Earth!!!"}
And this response from the container:
XXX_THE_END_OF_A_WHISK_ACTIVATION_XXX