Overview

This document describes how to deploy an OpenWhisk standalone server on a cloud server (e.g. AWS EC2, Jetstream2) with Ubuntu 22.04 from scratch. This setup is the simplest possible OpenWhisk standalone deployment - with one node (m3.quad, or larger) hosting the entire cluster. To consider a multi-node deployment, Kubernetes can be used - though this is not covered in this document.

This document is based on the following documentation:

• https://github.com/apache/openwhisk/blob/master/core/standalone/README.md
• https://docs.docker.com/engine/install/ubuntu/
• https://github.com/apache/openwhisk/blob/master/docs/actions.md
• https://github.com/apache/openwhisk-cli/releases

The server is setup as follows:

• Ubuntu 22.04 instance
• 30GB or more of disk storage
• a public IP address
• TCP ports 22 (ssh) and 31002 (OpenWhisk API) should be open

Deploy instance

To avoid repeating documentation, we assume here have deployed an Ubuntu 22.04 instance as per above and are able to ssh into it

Install Docker

If Docker is not already installed in your server, install it as follows:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker ${USER}

Then, exit the shell and ssh back into the server

Install prerequisites to build

sudo apt update
sudo apt-get install -y python3-pip
sudo pip3 install -y ansible==4.1.0 
sudo pip3 install -y jinja2==3.0.1 
sudo apt install -y default-jre
sudo apt install -y nodejs
sudo apt install -y npm

Build the OpenWhisk standalone jar

git clone https://github.com/openwhisk/openwhisk.git
cd openwhisk
./gradlew :core:standalone:build

Install the OpenWhisk client CLI (wsk)

wget https://github.com/apache/openwhisk-cli/releases/download/1.2.0/OpenWhisk_CLI-1.2.0-linux-amd64.tgz
tar -xzf OpenWhisk_CLI-1.2.0-linux-amd64.tgz
sudo cp wsk /usr/local/bin/

Run the standalone server

First, create a file custom.conf - replacing the maximum memory and runtime as per your configuration needs:

include classpath("standalone.conf")

whisk {

  memory {
    min = "256m"
    max = "10240m"
    std = "1024m"
  }
  time-limit {
    min = "100ms"
    max = "120m"
    std = "1m"
  }

  container-pool {
    user-memory = “16384m"
  }

}

Then, run the server:

java -jar ./bin/openwhisk-standalone.jar -c custom.conf

Test the server

Configure the wsk CLI with: 1) the default credentials that are built-in with the standalone server, and 2) the endpoint of the server (by default, http://172.17.0.1:3233 - the IP address may vary in your system depending on Docker configuration)

wsk property set   --apihost 'http://172.17.0.1:3233' --auth '23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP'

wsk -i action list

Create a SSL nginx proxy for public IP

The setup so far has the server listening on http on a Docker endpoint; let's expose it with https via a public endpoint using nginx.

First, generate self-signed x509 certificate:

sudo apt install -y openssl
sudo mkdir -p /etc/nginx/ssl
sudo openssl req -newkey rsa:2048 -nodes -keyout /etc/nginx/ssl/nginx.key -x509 -days 3650 -out /etc/nginx/ssl/nginx.crt

Now install nginx:

sudo apt install -y nginx

Edit the nginx configuration to replace the default server entry with the following (note: replace your IP address or DNS name below):

sudo vi /etc/nginx/sites-available/default

server {
	listen 31002 ssl;
	server_name REPLACE_WITH_YOUR_SERVER_NAME;

	ssl_certificate /etc/nginx/ssl/nginx.crt;
        ssl_certificate_key /etc/nginx/ssl/nginx.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256';

	location / {
		proxy_pass http://172.17.0.1:3233;  # Forward to your intranet HTTP server
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
		# First attempt to serve request as file, then
		# as directory, then fall back to displaying a 404.
		# try_files $uri $uri/ =404;
	}
}

Reconfigure wsk to use the new ssl endpoint

wsk property set   --apihost 'https://REPLACE_WITH_YOUR_SERVER_NAME:31002' --auth '23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP'

wsk -i action list

Run a simple test Javascript action

Create a file greeting.js as follows:

/**
 * @params is a JSON object with optional fields "name" and "place".
 * @return a JSON object containing the message in a field called "msg".
 */
function main(params) {
  // log the parameters to stdout
  console.log('params:', params);

  // if a value for name is provided, use it else use a default
  var name = params.name || 'stranger';

  // if a value for place is provided, use it else use a default
  var place = params.place || 'somewhere';

  // construct the message using the values for name and place
  return {msg:  'Hello, ' + name + ' from ' + place + '!'};
}

Create this action in OpenWhisk using the wsk CLI:

wsk -i action create greeting greeting.js

Then invoke it:

./wsk -i action invoke greeting -b

Using for FaaSr tests

Once the server is up and running on a public SSL port, it can be used for tests with FaaSr; example configurations would be as follows.

Snippet from FaaSr JSON (note that SSL==False is set such that the SSL handshake will accept a self-signed certificate):

    "ComputeServers": {
        "My_OW_Account": {
            "FaaSType": "OpenWhisk",
            "Namespace": "guest",
            "SSL": "False",
            "Endpoint": "REPLACE_WITH_YOUR_SERVER_NAME:31002"
        }
    },

Snippet from faasr_env:

"My_OW_Account_API_KEY"="23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP"

Changing default API key + secret

The documentation above uses the default credentials "baked" in the OpenWhisk repo, which are public. This is ok for a first test, but in general you should create your own credentials so not to open your test server to external users. To do so:

Edit the configuration file openwhisk/core/standalone/src/main/resources/standalone.conf and set up the credentials for whisk-system and guest to be those of your choosing. The defaults are shown below; the value before the : is akin to a username, the value after is akin to a password; replace with your own generated values and save the file.

Original:

  users {
    whisk-system = "789c46b1-71f6-4ed5-8c54-816aa4f8c502:abczO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP"
    guest = "23bc46b1-71f6-4ed5-8c54-816aa4f8c502:123zO3xZCLrMN6v2BKK1dXYFpXlPkccOFqm12CdAsMgRU4VrNZ9lyGVCGuMDGIwP"
  }

Modified:

  users {
    whisk-system = "Your_New_UUID_here_system_user:Your_New_Key_here_system_user"
    guest = "Your_New_UUID_here_guest_user:Your_New_Key_here_guest_user"
  }

Then, rebuild the openwhisk jar:

./gradlew :core:standalone:build

Make sure you reconfigure wsk to use the new credential you set up:

wsk property set   --apihost 'https://REPLACE_WITH_YOUR_SERVER_NAME:31002' --auth 'Your_New_UUID_here_guest_user:Your_New_Key_here_guest_user'