---
name: solution-tutorials-serverless-webapp
title: Serverless web application and API with Code Engine
description: 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.
last-updated: 2025-10-08
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/solution-tutorials?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Serverless web application and API with Code Engine
{: #serverless-webapp}
{: toc-content-type="tutorial"}
{: toc-services="codeengine, Cloudant, cloud-object-storage"}
{: toc-completion-time="1h"}
{: toc-use-case="ApplicationModernization"}

This tutorial may incur costs. Use the [Cost Estimator](https://cloud.ibm.com/estimator){: external} to generate a cost estimate based on your projected usage.
{: tip}


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](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant&format=markdown) as JSON document database.
{: shortdesc}

Static websites are great for performance and security. Their architectural model is sometimes referred to as [Jamstack](https://jamstack.org/){: external} 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](https://cloud.ibm.com/docs/codeengine?topic=codeengine-getting-started&format=markdown). The backend only runs when required and thereby occurs charges when in use.


## Objectives
{: #serverless-webapp-0}

* 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](./images/solution64-serverless-webapp/architecture-serverless-api-webapp.svg){: caption="Architecture diagram of the tutorial" caption-side="bottom"}
{: style="text-align: center;"}


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.
5. The backend uses IBM Cloudant to store and retrieve guestbook entries.

## Create the Guestbook database
{: #serverless-webapp-2}
{: step}

Let's start by creating a [IBM Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant&format=markdown) service instance. IBM Cloudant is a fully managed JSON document database. It is built upon and compatible with Apache CouchDB.

1. In the [Catalog](https://cloud.ibm.com/catalog?category=databases#services){: external}, under **Category**, go to the **Databases** category. Click on the **IBM Cloudant** tile. In the new dialog:
   1. Under **Multitenant** select a region.
   1. Under **Configure Cloudant instance** pick a **unique** name for the service, such as `<yourinitials>-guestbook-db`.
   1. Select a resource group.

   1. Select **IAM** as authentication method.
   1. Select the **Lite** plan. If you already have a Lite plan in your account, select another service plan.
   1. Click **Create**.
2. Back in the [IBM Cloud Resource List](https://cloud.ibm.com/resources/){: external}, under **Databases**, 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
{: #serverless-webapp-3}
{: step}

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
{: #serverless-webapp-4}

1. Navigate to [IBM Cloud Code Engine Overview](https://cloud.ibm.com/containers/serverless/overview){: external} page.
2. On the left pane, click on **Serverless 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
{: #serverless-webapp-5}
{: step}

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 access** 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](https://cloud.ibm.com/docs/codeengine?topic=codeengine-plan-build&format=markdown). If not using the pre-built container image and if [using a private container registry additional steps might be needed](https://cloud.ibm.com/docs/codeengine?topic=codeengine-deploy-app-private&format=markdown). You can find the source at https://github.com/IBM-Cloud/serverless-guestbook/tree/ce
{: tip}

## Deploy the web app
{: #serverless-webapp-6}
{: step}

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](https://cloud.ibm.com/objectstorage/create){: external} from the catalog.
1. Select **IBM Cloud** for the Infrastructure and **Standard** for the plan.
1. Enter a **unique** service name for the instance, such as `<yourinitials>-guestbook-cos`.
1. Select a resource group.
1. Click **Create**

Create a bucket configured for static website hosting:
1. Click **Create a bucket**.
1. Click **Customize your bucket**.
1. Enter a bucket name that is unique across all IBM accounts. Try `<yourinitials>-guestbook`.
1. Select resiliency as **Regional**.
1. Select a **Location** consistent with the IBM Cloudant instance.
1. Keep the **Storage class** default
1. Scroll down to the **Static website hosting** and click **Add+**.
1. Keep the Routing rules (individual) selected and add the Index document **index.html**.
1. Click Public access to **On**
1. Click **Save**
1. 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.
1. Download a zip file by clicking **Code** then **Download ZIP**.
1. Unzip the file and navigate to the `docs` directory of the unzipped file.
1. 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.
   {: note}

1. Open the bucket **Objects** view and drag and drop the **guestbook.js** and **index.html** files to the COS bucket.
1. 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.
1. You should see the guestbook page.
1. Add new entries to the guestbook.

![Guestbook Screenshot](images/solution64-serverless-webapp/Guestbook.png){: caption="Guestbook Screenshot" caption-side="bottom"}
{: style="text-align: center;"}


## Remove resources
{: #serverless-webapp-cleanup}
{: step}

To delete the created bucket and Object Storage service:
1. Navigate to the Object Storage bucket objects
1. Check the box in the title row to select all objects in the bucket
1. Click **Delete objects**
1. In the upper right of the bucket object page **Actions** menu select **Delete bucket**
1. 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](https://cloud.ibm.com/resources){: external}
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](https://cloud.ibm.com/containers/serverless/overview) 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](https://cloud.ibm.com/docs/account?topic=account-resource-reclamation&format=markdown).
{: tip}

## Related content
{: #serverless-webapp-8}

* [Serverless Computing](https://www.ibm.com/think/topics/serverless){: external}
* [Serverless Deployment Model](https://developer.ibm.com/depmodels/serverless/){: external}
* [Getting started with IBM Cloud Code Engine](https://cloud.ibm.com/docs/codeengine?topic=codeengine-getting-started&format=markdown)