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 Cloud 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. The Angular application and protected APIs are custom examples, whilst other components in this repo are generic and can be reused for other web applications, e.g. login functionality and the setup of App ID, Cloudant and Object Storage.
- Prerequisites
- Local Environment Setup
- App ID Setup
- Cloudant Setup
- Cloud Functions Setup for Login
- Cloud Functions Setup for protected API
- Setup of local Web Application
- Cloud Object Storage Setup
- Cloud Functions Setup for HTML Function
- Custom Domain Setup (optional)
Create an IBM Cloud lite account (free, no credit card required):
Make sure you have the following tools installed:
- git
- ibmcloud CLI
- node
- curl
- ng (only needed for the Angular sample application)
Invoke the following commands:
$ git clone https://github.com/IBM/ibm-cloud-functions-refarch-web-application.git
$ cd ibm-cloud-functions-refarch-web-application
$ 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, and IBMCLOUD_SPACE to match the apikey in serverless-web-application.json and the organization and space names you are using (see the outputs in your terminal when following the steps above). If you picked a region other than us-south when logging in, you will need to update BLUEMIX_REGION as well.
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.
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
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
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
To run the Angular web application locally, run these commands:
$ scripts/setup-local-webapp.sh
$ ng serve
Open http://localhost:4200 in your browser.
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
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.
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.
- Developing Serverless Web Applications on the IBM Cloud
- Hosting Resources for Web Applications on the IBM Cloud
- Authentication of Users in Serverless Applications
- User Authorization in Serverless Web Applications
- Screenshots
- Short video of the Angular application
Find out more about the main components:
- IBM Cloud Functions powered by Apache OpenWhisk
- IBM Cloud Functions API Management
- IBM Cloud Object Storage
- IBM App ID
- IBM Cloudant
This code pattern is licensed under the Apache License, Version 2. Separate third-party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 and the Apache License, Version 2.