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:
Check out my blogs and screenshots for more details:
- 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
Outline
- 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)
Prerequisites
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)
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 '[email protected], 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
