IBM Cloud Docs
Serverless web application and API with Code Engine

Serverless web application and API with Code Engine

This tutorial may incur costs. Use the Cost Estimator to generate a cost estimate based on your projected usage.

In this tutorial, you will create a serverless web application using a bucket in Object Storage and implementing the application backend using IBM Cloud Code Engine and IBM Cloudant as JSON document database.

Static websites are great for performance and security. Their architectural model is sometimes referred to as Jamstack in reference to JavaScript, API, and Markup. In this tutorial, you will create a static website hosted on Object Storage. The website has a guestbook which uses JavaScript to access an API for retrieving entries or to add a new entry. The API for interaction with the backing database is implemented using a serverless approach. It is deployed as backend app or microservice to IBM Cloud Code Engine. The backend only runs when required and thereby occurs charges when in use.

Objectives

  • Deploy a serverless backend and a database
  • Expose a REST API as serverless app
  • Host a static website

The application shown in this tutorial is a simple guestbook website where users can post messages.

Architecture
Architecture diagram of the tutorial

  1. The user accesses the application hosted on the bucket in Object Storage
  2. The web application calls a backend API.
  3. The app with the backend API is deployed to Code Engine.
  4. The backend uses IBM Cloudant to store and retrieve guestbook entries.

Create the Guestbook database

Let's start by creating a IBM Cloudant service instance. IBM Cloudant is a fully managed JSON document database. It is built upon and compatible with Apache CouchDB.

  1. In the Catalog, under Services, go to the Databases category. Click on the IBM Cloudant tile. In the new dialog:

    1. Under Multitenant select a region.

    2. Under Configure Cloudant instance pick a unique name for the service, such as <yourinitials>-guestbook-db.

    3. Select a resource group.

    4. Select IAM as authentication method.

    5. Select the Lite plan. If you already have a Lite plan in your account, select another service plan.

    6. Click Create.

  2. Back in the IBM Cloud Resource List, under Services, click on the IBM Cloudant instance you created to open the instance full details page. Note: You may be required to wait until the status of the service changes to Active.
  3. Click on Launch Dashboard to open the dashboard in a new browser tab.
  4. In the upper right, click on Create Database. Enter guestbook as name and select Non-Partioned under Partitioning. Click Create to create the database.

Create serverless backend

In this section, you will create the serverless backend app with Code Engine. Serverless apps only incur charges for the execution time which is ideal for infrequently accessed solutions like a guestbook.

Create a Code Engine project

  1. Navigate to IBM Cloud Code Engine Overview page.
  2. On the left pane, click on Projects and then click Create,
    • Select a location.
    • Use <yourinitials>-guestbook as project name and select the same resource group as before.
    • Click on Create.
    • Wait until the project status changes to Active.
  3. Click on the project name to enter the project dashboard.

Create and deploy backend app

  1. Within the project dashboard, click on Applications, then Create.
  2. In the new dialog, enter guestbook-backend as name.
  3. Leave Container image selected and use icr.io/solution-tutorials/tutorial-serverless-api-webapp:latest as Image reference. It uses an already existing container image.
  4. Under Instance resources, select 0.25 vCPU / 0.5 GB for CPU and memory. Not much of resources is needed for this type of app.
  5. Increase the Min number of instances to 1 and reduce Max number of instances to 2. The minimum of one makes the app more responsive during the initial tests. You could reduce it later to zero again.
  6. Click Create to deploy the new backend app for the guestbook. Note that without the next step of creating a service binding the deployment will fail with a code error.
  7. Create a service binding to the database.
    1. Click Service bindings tab.
    2. Click Create.
    3. Click IBM Cloud service instance and choose your database from the dropdown.
    4. Leave Role as Writer.
    5. Click Add.
  8. Wait for the provisioning to report as green and ready. Click on Test application, then on Application URL. The backend app should load and return a page saying healthy. Remember or copy the application URL because it is needed for the next part.

Instead of using the pre-built container image, you could build the image on your own. This can be done either outside of or with the help of Code Engine. If not using the pre-built container image and if using a private container registry additional steps might be needed. You can find the source at https://github.com/IBM-Cloud/serverless-guestbook/tree/ce

Deploy the web app

Create a Object Storage bucket configured with static website hosting containing the files for the guestbook JavaScript application that uses the IBM Cloudant database.

Create a Object Storage instance:

  1. Select Object Storage from the catalog.
  2. Select IBM Cloud for the Infrastructure and Standard for the plan.
  3. Enter a unique service name for the instance, such as <yourinitials>-guestbook-cos.
  4. Select a resource group.
  5. Click Create

Create a bucket configured for static website hosting:

  1. Click Create a bucket.
  2. Click Customize your bucket.
  3. Enter a bucket name that is unique across all IBM accounts. Try <yourinitials>-guestbook.
  4. Select resiliency as Regional.
  5. Select a Location consistent with the IBM Cloudant instance.
  6. Keep the Storage class default
  7. Scroll down to the Static website hosting and click Add+.
  8. Keep the Routing rules (individual) selected and add the Index document index.html.
  9. Click Public access to On
  10. Click Save
  11. Scroll to the bottom and click Create bucket

Copy the files in the docs directory of https://github.com/IBM-Cloud/serverless-guestbook/tree/ce into the bucket:

  1. Open https://github.com/IBM-Cloud/serverless-guestbook/tree/ce in a new tab.

  2. Download a zip file by clicking Code then Download ZIP.

  3. Unzip the file and navigate to the docs directory of the unzipped file.

  4. Edit guestbook.js - replace the value of apiUrl with the application URL from the previous section.

    Make sure that the URI does not end on a slash (/). Else the app will not work.

  5. Open the bucket Objects view and drag and drop the guestbook.js and index.html files to the COS bucket.

  6. Navigate to the Configuration tab for the bucket. In the Endpoints section locate the Static website hosting endpoints section. Copy the Public endpoint into a browser tab.

  7. You should see the guestbook page.

  8. Add new entries to the guestbook.

Guestbook Screenshot
Guestbook Screenshot

Remove resources

To delete the created bucket and Object Storage service:

  1. Navigate to the Object Storage bucket objects
  2. Check the box in the title row to select all objects in the bucket
  3. Click Delete objects
  4. In the upper right of the bucket object page Actions menu select Delete bucket
  5. In the upper right of the Object Storage instance Actions menu select Delete Instance

To delete the created IBM Cloudant service,

  1. Navigate to the resource list
  2. Under Databases, click on the action menu next to <yourinitials>-guestbook-db service
  3. Click Delete

To delete the application and project Code Engine,

  1. Navigate to the Code Engine landing page.
  2. On the left pane, click on Projects.
  3. In the list of projects, check the guestbook project, then click Delete.

Depending on the resource it might not be deleted immediately, but retained (by default for 7 days). You can reclaim the resource by deleting it permanently or restore it within the retention period. See this document on how to use resource reclamation.

Related content