Building a headless ecommerce platform on Google Cloud

Stay organized with collections Save and categorize content based on your preferences.

This tutorial describes how to create a headless ecommerce site by using commercetools hosted on Google Cloud. The tutorial is for web developers and retail business stakeholders who want to implement an ecommerce site that takes advantage of the benefits of a headless architecture.

To complete this tutorial, you need to be familiar with Google Cloud concepts such as projects, Cloud Shell, and the Google Cloud CLI. You should also be comfortable with basic web development concepts and Linux commands.

Architecture overview of a headless ecommerce solution

In this tutorial, you build a headless ecommerce solution on Google Cloud. This solution loosely couples a backend that is hosted on Google Cloud with a frontend that is also hosted on Google Cloud. Like any headless ecommerce architecture, the frontend processes access the backend processes like products, carts, or orders exclusively through a set of APIs. The APIs define how the backend and frontend interact. By channeling all interaction between the frontend and backend through the APIs protects the frontend from unintended or arbitrary changes made in the backend. This separation between the frontend and backend also lets you update the frontend while limiting changes to the backend. For example, you can adjust the frontend to meet business needs, such as seasonal campaigns, by using only frontend development skills.

The benefits of a headless ecommerce solution include the following abilities:

  • Updating the client-facing site (for example, to handle seasonal campaigns) without needing backend skills and without risking regressions in the backend processing.
  • Maintaining compliance with security and other standards while making nimble updates to the frontend.
  • Maintaining consistent performance for the end-to-end client experience as you apply updates to the frontend.

The following diagram shows the target architecture for the headless ecommerce solution that you build in this tutorial.

The headless ecommerce architecture used in the tutorial.

As shown in the diagram, you use commercetools as the backend for your ecommerce site. For the frontend, you create the following two deployments:

  • A storefront frontend deployment on a virtual machine instance in Cloud Shell. In this tutorial, you create this deployment to validate that the storefront site is served as expected.
  • A storefront frontend deployment directly in Google Cloud. After you validate the frontend deployment in Cloud Shell, you deploy the frontend again, but this time to Google Cloud. The deployment to Google Cloud is how you do a real-world deployment.

For both deployments, you use the credentials that you get from the commercetools Merchant Center to communicate with the commercetools backend.

Alternatives to a headless ecommerce solution

As an alternative to the headless ecommerce solution, you can build one of the following ecommerce solutions on Google Cloud:

  • Build your own ecommerce platform on Google Cloud. This option requires you to assemble your own solution by using the building blocks in Google Cloud, including artificial intelligence (AI) and machine learning (ML) tools and data management tools. This option has the following choices:
    • Migrate your existing solution by using lift and shift where you host your existing solution in Google Cloud instead of running it in your own data center. When you lift and shift your existing solution, you minimize the change required to get to Google Cloud, but you don't get the benefits of a microservices architecture.
    • Migrate and improve your existing solution to a microservices architecture that uses containers and managed services in Google Cloud. This approach requires more changes than the lift-and-shift approach. But after you've migrated the solution, you get the benefits of microservices architecture, including easier maintenance, improved flexibility, and scalability.
  • Use a ready-made software as a service (SaaS) solution on Google Cloud. This option uses an existing solution, such as Shopify or BigCommerce, that is hosted on Google Cloud. This approach works best if you don't need much customization. You can take advantage of the features in Google Cloud, including Analytics 360, to get insights about your customers and analyze the data generated by your solution.

For more information about building an ecommerce platform on Google Cloud, including supporting architectures, watch the following video:

Objectives

  • Create an example of an end-to-end ecommerce solution that incorporates commercetools hosted on Google Cloud as the backend.
  • Demonstrate how a frontend can be deployed in the Cloud Shell virtual machine instance and on Google Cloud while working with the same backend.

Costs

This tutorial uses the following billable components of Google Cloud:

  • Cloud Run

To generate a cost estimate based on your projected usage, use the pricing calculator. New Google Cloud users might be eligible for a free trial.

When you finish this tutorial, you can avoid continued billing by deleting the resources you created. For more information, see Clean up.

Before you begin

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  2. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    A Cloud Shell session starts and displays a command-line prompt.

  3. In the Cloud Shell terminal, set the project that you selected or created in the previous step to be the default project:

    gcloud config set project PROJECT_ID
    

    Replace PROJECT_ID with the project ID for your project. The project ID is a unique string that differentiates your project from all others in Google Cloud. You can find your project ID in the Google Cloud Resource Manager or by running the following command:

    gcloud projects list --filter='name=PROJECT_NAME'
    
  4. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Prepare your environment

You work with the following repositories in this tutorial:

  • The headless commerce repository that contains the code and data that are specific to this tutorial.
  • The commercetools repository that contains the code and data for a general-purpose commercetools demo.

To clone these repositories, do the following:

  1. In the Cloud Shell terminal, clone the headless commerce repository:

    git clone https://github.com/googlecodelabs/headless-commerce-demo.git
    
  2. Change the working directory to the root directory of the headless commerce repository:

    cd ~/headless-commerce-demo
    
  3. In the root directory of the headless commerce repository, clone the commercetools repository:

    git clone https://github.com/commercetools/commercetools-sunrise-data.git
    

Create a commercetools trial account

  1. On the commercetools site, follow the instructions to set up a trial account.

    After you accept the terms and submit your account information, commercetools sends you an email with a link to complete your account creation.

  2. In the email that you received from commercetools, click the link to create a new project.

    Clicking this link opens Merchant Center on the commercetools site.

  3. Confirm that you can see the commercetools Merchant Center.

    The commercetools Merchant Center.

For this tutorial, you use the Developer settings in the commercetools Merchant Center to create two separate API clients. Each API client requires a specific format for the credentials that the frontend uses to interact with the commercetools backend.

Create a commercetools Admin API client and copy credentials

In this tutorial, you use commands that run scripts that import the sample storefront data into the commercetools repository. Those scripts need access to the commercetools backend. To get the credentials that you need for this access, you use the commercetools Merchant Center to create an Admin API client. After you create the client, you copy the client's credentials from the commercetools Merchant Center and paste them into an .env file that you create.

Create the Admin API client and copy credentials

  1. In the project that you just set up in the commercetools Merchant Center, click Settings > Developer Settings > Create new API client.
  2. In the New API client screen that appears, enter a name for your client (for example, Admin Client).
  3. Select the Admin client template.
  4. Click Create API client.
  5. In the screen that appears, select Environment Variables (.env) from the list of credential formats.

    There are two credential formats that have similar names: Environment Variables and Environment Variables (.env). Make sure that you select the Environment Variables (.env) format for the Admin API client.

  6. To copy the credentials, click Copy to clipboard.

    After you close this screen, the credential values are no longer available. If you close the screen before you copy the credential values, then you need to complete the preceding steps again to generate a new Admin API client that has new credentials.

Keep the commercetools Merchant Center open because you need to use this tool again to generate the mobile API client later in this tutorial.

Save the credentials

  1. In Cloud Shell, create a file that is named .env in the ~/headless-commerce-demo/commercetools-sunrise-data repository, and then open the .env file for editing:

    cd ~/headless-commerce-demo/commercetools-sunrise-data
    touch .env
    edit .env
    
  2. Click Open Editor.

  3. In Cloud Shell Editor, open the .env file, paste the Environment Variables (.env) credentials into the file, and then save the file.

  4. To return to the Cloud Shell terminal, click Open Terminal.

  5. In Cloud Shell, confirm the contents of the .env file:

    more .env
    

    If the contents are correct, the output matches the content that you saw in the Cloud Shell editor.

Import sample data

With the credentials file in place, you can now import the sample data that the storefront site uses.

  1. In Cloud Shell, remove the demo data from the commercetools repository and then copy the sample data from the headless commerce repository:

    cd ~/headless-commerce-demo
    rm -rf commercetools-sunrise-data/data
    cp -r import-data commercetools-sunrise-data/data
    
  2. Import the data that you copied in the previous step:

    cd commercetools-sunrise-data
    npm install
    npm run import:data
    

    If the import was successful, the output is similar to the following:

    --Importing all project data--
    Types imported
    Channels imported
    Tax categories imported
    Zones imported
    Project set up
    Types imported
    Shipping methods imported
    Customer groups imported
    Customers imported
    Categories imported
    Product types imported
    Save products      ████████████████████████████████████████ || 100% || 9/9 master variants
    Products imported
    Orders imported
    --All data is imported--
    
  3. If any errors occur when you import the data, use the following commands to clear the data and then rerun the data import step:

    npm run clean:data
    npm run import:data
    

Create commercetools Storefront API client and copy credentials

For the frontend to communicate with the commercetools APIs, you must generate another API client for the storefront application. Like the Admin API client, you store the credentials for this API client in the set_env.sh file that you create.

  1. In the project that you set up in the commercetools Merchant Center, click Settings > Developer Settings > Create new API client.
  2. In the screen that appears, enter a name for your client (for example, Storefront Client).
  3. Select the Mobile & single-page application client template.
  4. Click Create API client.
  5. In the screen that appears, select Environment Variables from the list of credential formats.

    There are two credential formats that have similar names: Environment Variables and Environment Variables (.env). Make sure that you select the Environment Variables format for the mobile API client.

  6. To copy the credentials, click Copy to clipboard.

    After you close this screen, the credential values are no longer available. If you close the screen before you copy the credential values, you need to complete the preceding steps again to generate a new mobile API client that has new credentials.

Save the credentials

  1. In the Cloud Shell terminal, create a file named set_env.sh in the ~/headless-commerce-demo/third_party/storefront/ directory that contains the credentials you copied at the end of the previous procedure:

    cd ~/headless-commerce-demo/third_party/storefront/
    touch set_env.sh
    chmod 755 set_env.sh
    edit set_env.sh
    
  2. Click the Open Editor button.

  3. In Cloud Shell, open the set_env.sh file, paste the Environment Variables credentials that you copied into the file, and then save the file.

  4. To return to the Cloud Shell terminal, click Open Terminal.

Validate deployment in the Cloud Shell virtual machine

At this point, the frontend and backend are set up. You can now display the shopping website. To validate that the website works, you start the development server and then view the storefront by using Web Preview on the Cloud Shell virtual machine instance. The Cloud Shell virtual machine provides a convenient proxy for the final Google Cloud environment.

  1. In Cloud Shell, install the dependencies and then start the development server:

    cd ~/headless-commerce-demo/third_party/storefront
    source set_env.sh
    npm install
    npm run dev
    

    The output is similar to the following:

    No issues found.
    23:47:56
    ℹ Waiting for file changes
    ℹ Memory usage: 514 MB (RSS: 917 MB)
    ℹ Listening on: http://172.17.0.4:41043/
  2. In the last line of the output, determine the port that is being used by the storefront by looking at the number that immediately follows the IP address.

    For example, the following line indicates that the port is 41043:

    Listening on: http://172.17.0.4:41043/

    You need the port number in the following steps.

  3. In Cloud Shell, click Preview.

  4. Click Change port.

  5. In the Port Number field, enter the port number that is being used by the storefront, and then click Change and Preview.

    You now see the storefront in a browser window, as shown in the following screenshot:

    ecommerce storefront deployed in the Cloud Shell
virtual machine instance.

Deploy on Google Cloud

Now that you have validated that the storefront renders in the Cloud Shell virtual machine, you are ready to deploy the application directly on Google Cloud.

In this section, you run commands in Cloud Shell, just like you did when you deployed the application in the Cloud Shell virtual machine.

  1. In Cloud Shell, open a new tab by clicking Open a new tab.

    After the tab opens, you see output that's similar to the following:

    Your Cloud Platform project in this session is set to PROJECT_ID

    PROJECT_ID is the project ID for your project.

  2. If the project ID in this message doesn't match the project ID that you are using in this tutorial, set the project ID:

    gcloud config set project PROJECT_ID
    

    Replace PROJECT_ID with the project ID for the project you have been using in this tutorial.

  3. Set up the Google Cloud environment:

    cd ~/headless-commerce-demo/third_party/storefront
    PROJECT_NUMBER="$(gcloud projects list --filter="$(gcloud config get-value project)" --format="value(PROJECT_NUMBER)")"
    export PROJECT_NUMBER
    CLOUD_RUN_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
    export CLOUD_RUN_SA
    . set_env.sh
    
  4. Enable the required Google Cloud services:

    gcloud services enable cloudbuild.googleapis.com \
      run.googleapis.com \
      secretmanager.googleapis.com \
      artifactregistry.googleapis.com
    

    The output is similar to the following:

    Operation "operations/acf.p2-413343018046-1ba462af-7d75-45dd-aa85-983c25922c10" finished successfully.
  5. Create the secrets, ctp-client-id and ctp-client-secret, with the values of the equivalent environment variables from the set_env.sh file:

    printf ${CTP_CLIENT_ID} | gcloud secrets create ctp-client-id  --data-file=-
    printf ${CTP_CLIENT_SECRET} | gcloud secrets create ctp-client-secret --data-file=-
    
  6. Add Identity and Access Management policy bindings to the IAM policies of the secrets that you created in the previous step:

    gcloud secrets add-iam-policy-binding ctp-client-id \
        --member="serviceAccount:$CLOUD_RUN_SA" \
        --role="roles/secretmanager.secretAccessor"
    
    gcloud secrets add-iam-policy-binding ctp-client-secret \
        --member="serviceAccount:$CLOUD_RUN_SA" \
        --role="roles/secretmanager.secretAccessor"
    

    These commands give IAM permissions to the default service account of Cloud Run. These IAM permissions let Cloud Run access the secrets at runtime.

  7. Deploy the storefront application to Cloud Run to get a service URL. This command might take several minutes to complete.

    gcloud beta run deploy storefront --source=. \
      --set-secrets=CTP_CLIENT_SECRET=ctp-client-secret:latest,CTP_CLIENT_ID=ctp-client-id:latest \
      --set-env-vars=CTP_PROJECT_KEY="$CTP_PROJECT_KEY",CTP_AUTH_URL="$CTP_AUTH_URL",CTP_API_URL="$CTP_API_URL",CTP_SCOPES="$CTP_SCOPES" \
      --region=us-east1 \
      --allow-unauthenticated \
      --platform=managed \
      --port=3000
    

    The parameters for this command specify that unauthenticated users can access the deployed site and that the fully managed version of Cloud Run is used. For more information, see the documentation for gcloud run deploy. If you receive a DEADLINE_EXCEEDED message, rerun this command.

    The output is similar to the following:

    Done.
    Service [storefront] revision [storefront-00001-xeq] has been deployed and is serving 100 percent of traffic.
    Service URL: https://storefront-vbof2pce6q-ue.a.run.app

    Notice that the output returns the service URL on the last line.

  8. In a browser tab, enter the service URL that was returned in the last line of the previous step.

    If the storefront appears at that URL, then the deployment is validated on Google Cloud.

    ecommerce storefront deployed directly in
Google Cloud.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Delete the Cloud project

The easiest way to eliminate billing is to delete the Cloud project you created for the tutorial.

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next