Launch Your Storefront

This guide describes how to launch a new PWA Kit storefront and make it accessible from its official, public web address. You have two options to launch and route traffic to your PWA Kit storefront:

1. Use a third-party CDN like CloudFlare or Akamai.
2. Use the CDN provided by Managed Runtime.

Throughout this guide we use an example storefront with the following attributes:

• Production URL: https://www.example.com
• Project ID: example
• Environment IDs: staging and production

Using a third-party CDN in front of Managed Runtime is optional. Customers can choose to use a third-party CDN based on:

• A pre-existing relationship with their CDN vendor of choice, where internal teams are skilled in configuring and managing a CDN.
• A need for additional control of CDN features above and beyond what Managed Runtime provides, such as custom WAF rules, additional performance headers, and additional third-party integrations.

Customers who desire low cost to serve, quick time to market, and have limited CDN requirements can use the built-in Managed Runtime CDN.

This guide assumes that you have access to the Runtime Admin web application and the Managed Runtime API to perform administrative tasks. To get access to these tools, contact your Commerce Cloud administrator and ask them to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

To make requests to the Managed Runtime API, you must include an API key in the HTTP request Authorization header with the value, Bearer {{api_key}}. For all the sample requests provided, don’t forget to replace {{api_key}} with your actual API key.

To find your API key, log in to Runtime Admin and go to the Account Settings page.

Important: Treat your API key like a password because it allows scripts to perform operations on your behalf.

You need access to your DNS provider to create and update CNAME records, as well as access to your third-party CDN provider (as applicable).

What Is Mobify?

In this guide, the word “Mobify” appears in a few places. Mobify is the name of the company that originally developed the technology that became PWA Kit and Managed Runtime. In 2020, Salesforce acquired Mobify along with all of its technology.

The process of rebranding from Mobify to Salesforce is still ongoing. The Mobify brand name still appears in the mobify-storefront.com domain used to host your storefront and the cloud.mobify.com domain used by the Managed Runtime API. Expect new Salesforce domains to eventually take the place of Mobify domains and expect support for Mobify domains to continue indefinitely.

Use a Custom Domain for Local Development

If you need to add conditional logic that alters the behavior of your site depending on the domain used, it’s easier to test this logic when your local development server can use a custom domain. Why would you need to add this kind of logic? Consider, for example, the need to look up a different SLAS Client ID depending on the domain.

To run your local development server using a custom domain:

1. Modify your local computer's DNS to resolve your custom domain to 127.0.0.1 (localhost).
2. Edit ssr.js.
3. In the options passed to runtime.createHandler, set the port to 80.
4. Run EXTERNAL_DOMAIN_NAME=www.example.com npm start, replacing the value of example.com with your custom domain. Running the server on port 80 can sometimes require administrative privileges.

Requests from your browser to the custom domain are now resolved and routed to your local development server!

The process for launching an environment is the same for staging and production, with the only difference being the domain name and the Managed Runtime environment used.

For the instructions provided, imagine you’re launching a storefront at staging.example.com, your project ID in Managed Runtime is example, and your bundle is deployed to an environment called staging.

You can complete these steps at any time, but we recommend that you start them as soon as you start using PWA Kit.

Use the Managed Runtime API or the Runtime Admin web application to create an environment (also known as a target) called staging to practice launching the storefront.

Here's a sample request that uses the target endpoint of Managed Runtime API to create an environment. Replace example in the request with your actual project ID string and replace {{api_key}} with your actual API key.

For instructions on creating an environment with Runtime Admin, see our guide to Managed Runtime Administration.

If the current site you are replacing at launch currently provides API access, you will need to ensure API access remains in place after the launch. For example, if your current site serves API traffic via example.com/apis/, you need to make the API accessible over api.example.com to ensure continuity after example.com is cutover to the new Managed Runtime site. You can update your environment’s proxy settings to use the new API location. For more information, see our guide to Proxying Requests.

If you are not using a third-party CDN, the Managed Runtime issues and manages TLS certificates for your domain.

To allow Salesforce to issue a TLS certificate for your domain, you must create a CNAME record. Contact Salesforce Customer Support and ask them to provide you with the necessary details for creating a CNAME record for your storefront.

You must create the provided CNAME record within 24 hours of receiving the details. A CNAME record looks like this:

Reduce the time to live (TTL) for staging.example.com to one minute. Reducing the TTL speeds up the DNS cutover process, and if something goes wrong, allows you to roll back quickly.

You can verify the TTL using the dig command:

Configure the environment to receive traffic from the host staging.example.com.

Update the environment’s ssr_external_domain and ssr_external_hostname settings using the Managed Runtime API:

Verify that the new settings are in effect using a cURL command that makes a request with DNS spoofing:

The cutover process is different when using a third-party CDN and the Managed Runtime CDN.

Option 1: Use a Third-Party CDN

For this option, you must configure your CDN to point to the Managed Runtime origin instead of the existing CDN origin. Refer to your CDN provider documentation for detailed guidance.

Add the external hostname ({{project}}-{{environment}}.mobify-storefront.com) as the origin in your third-party CDN. Make sure the CDN is configured to:

• set the Host header to match the origin {{project}}-{{environment}}.mobify-storefront.com
• forward the request method
• forward the path (including query string)
• forward the headers
• forward the body
• obey HTTP caching headers.

Consider adding a handler to reflect HTTP requests to verify the CDN is configured correctly:

Also consider adding a proxy with httpbin.org/anything to verify headers passed to proxies are sent correctly.

Option 2: Use the Managed Runtime CDN

For this option, you must perform a DNS cutover to point your domain from the old origin to the Managed Runtime CDN.

Salesforce Support provides you with a stable domain following the convention {{project}}-{{environment}}-cdn.mobify-storefront.com where {{project}} is your project ID, and {{environment}} is your environment ID.

Update the DNS CNAME record for staging.example.com to example-staging-cdn.mobify-storefront.com.

Open your web browser and navigate to staging.example.com.

Congrats, you’ve completed your launch! 🥳

After completing these instructions for a staging site, you can repeat the same process with the production domain and production environment.

From here, the Customer Success Group assists you in monitoring the site’s traffic to make sure that the launch has succeeded. The goal is to ensure that everything happens as expected during launch!

After launch, customers with a Signature Success Plan receive proactive site monitoring. To take advantage of this increased monitoring service, you must mark your environment as production. For more information, see the section on environments in the Managed Runtime Overview.

• The ssr_external_hostname target setting controls which host the environment receives traffic from. If the HTTP Host header of a request doesn’t match this value, the request fails with a 403 error.
• Currently, Salesforce doesn’t support storefront URLs with a bare domain like example.com (with no www subdomain). To use a bare domain, you must set up a server to redirect requests from the bare domain to your CNAME.