Serverless Web Applications on the IBM Cloud with Apache OpenWhisk
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
angular
documentation
function-html
function-login
function-protected
scripts
.gitignore
LICENSE
README.md
template.local.env

README.md

Serverless Web Applications on the IBM Cloud

This repo explains how to build and run serverless web applications on the IBM Cloud. Business logic is implemented with IBM Cloud Functions, static web resources are stored in IBM Object Storage, authentication is handled via IBM App ID and data is stored in the managed NoSQL database IBM Cloudant.

The project contains a sample web application built with Angular which requires user authentication to access data in Cloudant. Watch the 10 seconds video for a short demo.

While the Angular application and the protected API are samples, the other components in this repo are generic and can be reused for other web applications, for example the login functionality and the setup of App ID, Cloudant and Object Storage.

This diagram describes the architecture with the main components:

alt text

Check out my blogs and screenshots for more details:

Find out more about the main components:

Outline

Prerequisites

Create an IBM Cloud lite account (free, no credit card required):

Make sure you have the following tools installed:

Local Environment Setup

Invoke the following commands:

$ git clone https://github.com/nheidloff/serverless-web-application-ibm-cloud.git
$ cd serverless-web-application-ibm-cloud
$ ibmcloud login
$ ibmcloud target --cf
$ ibmcloud iam api-key-create serverless-web-application \
  -d "serverless-web-application" \
  --file serverless-web-application.json
$ cat serverless-web-application.json
$ cp template.local.env local.env

In local.env define 'IBMCLOUD_API_KEY', 'IBMCLOUD_ORG', 'IBMCLOUD_SPACE' and 'BLUEMIX_REGION' to match the apikey in serverless-web-application.json and the org, space and region name that you're using (see the outputs in your terminal when following the steps above).

App ID Setup

App ID is used to authenticate users.

Create new App ID service instance:

Run the following command to create these artifacts:

  • App ID service instance 'app-id-serverless'
  • App ID Cloud Foundry alias 'app-id-serverless'
  • App ID credentials
  • App ID test user 'user@demo.email, verysecret'
$ scripts/setup-app-id.sh

Reuse an existing App ID service instance:

The IBM Cloud lite plan only allows one App ID instance in your organization. If you have an App ID instance, you can use it rather than creating a new one.

In this case copy 'APPID_TENANTID', 'APPID_OAUTHURL', 'APPID_CLIENTID' and 'APPID_SECRET' from your service credentials and paste them in local.env.

Cloudant Setup

IBM Cloudant is used to store data used by the web application.

Create new Cloudant service instance:

Run the following command to create these artifacts:

  • Cloudant service instance 'cloudant-serverless'
  • Cloudant database 'serverless'
  • Cloudant documents and an index
$ scripts/setup-cloudant.sh

Reuse an existing Cloudant service instance:

The IBM Cloud lite plan only allows one Cloudant instance in your organization. If you have a Cloudant instance, you can use it rather than creating a new one.

In this case copy 'CLOUDANT_USERNAME' and 'CLOUDANT_PASSWORD' from your service credentials and paste them in local.env.

Additionally run this command to create the sample database and documents:

$ scripts/create-cloudant-db.sh

Cloud Functions Setup for Login

Run the following command to create these artifacts:

  • Cloud Functions sequence 'serverless-web-app-generic/login-and-redirect'
  • Cloud Functions function 'serverless-web-app-generic/login'
  • Cloud Functions function 'serverless-web-app-generic/redirect'
  • Cloud Function API 'login'
  • Redirect URL in App ID
$ scripts/setup-login-function.sh

Cloud Functions Setup for protected API

Run the following command to create these artifacts:

  • Cloud Functions function 'serverless-web-app-sample/function-protected'
  • Cloud Function API 'function-protected'
$ scripts/setup-protected-function.sh

Setup of local Web Application

To run the Angular web application locally, run these commands:

$ scripts/setup-local-webapp.sh
$ ng serve

Open http://localhost:4200 in your browser.

Cloud Object Storage Setup

IBM Cloud Object Storage is used to store the static resources of the web application.

Create new Object Storage service instance:

Run the following command to create these artifacts:

  • Object Storage instance 'object-storage-serverless'
  • Bucket 'serverless-web-[your-app-id-tenant-id]'
  • Built Angular application
  • Angular files stored in Object Storage
$ scripts/setup-object-storage.sh

To try the web application, open the URL that you get in the terminal.

Reuse an existing Object Storage service instance:

The IBM Cloud lite plan only allows one Object Storage instance in your organization. If you have an Object Storage instance, you can use it rather than creating a new one.

Define your service instance name in scripts/upload-files-to-object-storage.sh (line 74) and run this command to create the bucket and to upload the files:

$ scripts/upload-files-to-object-storage.sh

Cloud Functions Setup for HTML Function

Since Object Storage doesn't allow to pass in parameters to requested files (e.g. https://.../index.html?param=value) another function is deployed to host the index.html file of the single page web application. All other resources are stored in Object Storage.

To deploy the OpenWhisk function and the API, invoke the following command:

$ scripts/setup-html-function.sh

Open the web application with the URL that is printed in the output of the command.

Custom Domain Setup

When following the steps above, the sample application can be invoked via URLs like https://s3.us-south.objectstorage.softlayer.net/serverless-web-65819d17-0d02-4219-af3a-9468870673cc/serverless/web. If you want to use your own domain, you need to do some additional setup.

Follow the instruction in the documentation or in this blog to set up custom domains for OpenWhisk functions.

Check out the screenshots in the documentation folder for more details. Make sure to set the TXT and CNAME records in your DNS settings correctly, see this example.

To deploy update the redirect URL, invoke the following command:

$ scripts/setup-domain.sh https://[yourdomain.com]

Open the web application via https://[yourdomain.com]/serverless/web.