News: PWA Kit 3.0.0 is out now with Node 18 support. Upgrade your projects and environments to maintain functionality. You will not be able to deploy your site using older versions.

Managed Runtime Overview

Managed Runtime provides the infrastructure to deploy, host, and monitor your PWA Kit storefront.

Managed Runtime only supports applications created from a PWA Kit template. The source code for the available templates can be found in the template-* folders in the PWA Kit repository on GitHub.

This guide covers the main parts of Managed Runtime and how to access it.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

An environment is the term used to describe all of the cloud infrastructure and configuration values for a particular storefront hosted by Managed Runtime. Environments are used to separate your production storefront from other storefronts that are deployed for other purposes, such as development or testing.

In the Managed Runtime API, environments are called “targets,” but both terms refer to the same thing.

Because environments run on highly efficient microservices that automatically scale up and down, you can create as many environments as you need at no additional cost. For example, you could create a short-lived environment dedicated to a single agile development sprint or for a single user story within that sprint. When you no longer need an environment, we encourage you to delete them.

Environments marked as production are prioritized for monitoring by Salesforce’s Support team. For production environments, you can also Debug Using Log Center. To mark an environment as a production, you have two choices:

  1. Use the Runtime Admin tool. Step-by-step instructions for creating an environment or editing an existing environment are found in the Environments section of the Administration guide.
  2. Use the Managed Runtime API. The projects_target_create and projects_target_partial_update endpoints both feature the is_production parameter. To mark an environment as production with these endpoints, set is_production to true.

By default, you can mark up to 10 environments as production. To increase your limit, contact Support.

The storefront code that runs on an environment is called a bundle. Use the developer tools included in PWA Kit to generate a bundle and push it to Managed Runtime.

A bundle is a snapshot of your code at a specific point in time. It’s immutable: After a bundle has been created, it can’t be changed. Having this complete and accurate history of bundles makes troubleshooting deployments easier.

After pushing the bundle, you can use the Runtime Admin or Managed Runtime API to designate that bundle as “deployed.” Each project can have multiple bundles, but each environment can have only one bundle that's designated as deployed. You can change which bundle is designated as deployed at any time. For more information, see Push and Deploy Bundles.

To help you manage multiple environments, each environment also belongs to a project and each project belongs to an organization. An organization can contain multiple projects for multiple storefronts and each project can contain multiple environments. A Managed Runtime user can belong to multiple organizations to separate different work streams.

Each organization can have a maximum of 100 total environments and a maximum of 10 production environments. If you need to raise these limits, contact your Salesforce Support representative.

Organizations and user organization membership is determined by settings in Account Manager. A user can belong to an organization as either a member or an admin. Members can only interact with the projects in Managed Runtime that they’ve been assigned a project role to. Admins can interact with all the projects within an organization.

To assign a user the admin organization membership, contact Salesforce Support.

A user can have the following abilities for a Managed Runtime project:

  • Browse: View the project in Runtime Admin.
  • Manage Redirects: Manage redirects for the project. Please review the Redirects documentation to learn more.
  • Deploy: Deploy new bundles or revert the deployment to an older bundle.
  • Manage Team: View, add, invite, remove, and edit the roles of team members for the project.
  • Access Logs: Tail logs across all environments.

Each user is assigned a project role that determines which abilities they have. (A user can only have one role.) Project roles can be assigned to any user within an organization.

The following table shows which abilities are associated with each role:

RoleBrowseManage RedirectsDeployManage TeamAccess Logs
AdminYesYesYesYesYes
DeveloperYesYesYesNoYes
MarketerYesYesNoNoNo
Read OnlyYesNoNoNoNo

Within each Managed Runtime environment, the React app in the published bundle runs inside a Node.js environment. To respond to page requests and render the results, we use the Express web framework with the help of PWA Kit’s rendering and routing systems. We call this combination of React, Node, and Express the App Server. (Although, technically speaking, the App Server runs on “serverless” technology.) The App Server is optimized to run on cloud infrastructure that offers low computing costs, high availability, fast rendering, and massive scaling capacity.

Because PWA Kit’s rendering and routing system handles the differences between local development environments and Managed Runtime environments, your code runs in a predictable way when you deploy it. This predictability unlocks your development team’s productivity by encouraging them to deploy bundles more frequently.

Currently, the App Server supports Transport Layer Security (TLS) versions 1.2 and greater.

Code running on the App Server has access to the following environment variables:

  • DEPLOY_TARGET: ID of the environment.
  • EXTERNAL_DOMAIN_NAME: The domain name set on the environment.
  • MOBIFY_PROPERTY_ID: ID of the project that the environment belongs to.

Supporting the app server are several edge services, including:

  • A web application firewall (WAF) to protect your environments from attackers
  • A proxy server to speed up API requests
  • A content delivery network (CDN) to cache requests and speed up page loading
  • Edge functions that process requests and handle redirects

The proxy server and CDN are covered in detail in our guide to Proxying Requests. The edge function called the request processor is covered in our guide to Maximizing Your Cache Hit Ratio.

Managed Runtime’s edge services are strategically distributed throughout our public cloud infrastructure. Each service is located as close to the user as possible for faster performance.

To manage the settings for your organizations, projects, environments, and bundles, we offer two different tools:

  1. The Managed Runtime Admin, a web-based UI.
  2. The Managed Runtime API, a REST API that offers the same functionality as the web-based tool and some additional capabilities.

Use the Runtime Admin tool for routine tasks, such as deploying a new code bundle to an environment. Use the API whenever you need programmatic control, such as automatically creating an environment as part of a continuous integration script.

The admin tools give you a self-serve way to configure many settings, including:

  • Allowed IP addresses
  • Allowed access control headers
  • Currently deployed bundle
  • Deployment region
  • Proxies
  • Redirects
  • User permissions
  • Production environment flag

Access to the admin tools is controlled with Account Manager roles and an API key. For continuous integration (CI) and continuous delivery (CD) processes, dedicated bot users with their own API keys are typically provisioned by your organization.

Fun fact: Like your storefront, the Runtime Admin tool is a headless React app that is deployed to Managed Runtime.

While building your storefront, keep the following constraints of Managed Runtime environments in mind:

  • Environments only respond to requests whose HTTP Host header matches their External Hostname set in Runtime Admin.
  • The path / only accepts HTTP GET requests.
  • Request and response size can’t exceed 6 MB.
  • The maximum size of the HTTP request line and headers is 10240 bytes. Requests exceeding this size return an HTTP 413 Content Too Large.
  • Cookies, including the HTTP request Cookie and HTTP response Set-Cookie header aren't supported by default. They can be enabled by setting the allow_cookies attribute on an environment with the projects_target_partial_update endpoint. You can also enable cookies in the Environment Settings in Runtime Admin. Cookies are supported in PWA Kit version 3.1.0 or greater. See Personalize with Cookies.
  • Requests with headers that start with _ are not supported. These requests will be dropped.
  • HTTP requests originating from Managed Runtime environments don't use fixed IP addresses. To allow list requests from the App Server use the AWS IP Range for EC2. To allow list requests from Proxies, use CLOUDFRONT_ORIGIN_FACING.
  • The path prefix /mobify is reserved for managed endpoints. These endpoints include:
    • /mobify/ping: Returns an HTTP 200 response code when the environment is operating correctly.
    • /mobify/redirect/$path: Returns a similar response as projects_target_redirect_retrieve.
    • /mobify/proxy/$name: Returns a response from a proxy.
  • You can bypass the CDN cache using the HTTP request header: x-mobify-cachebreaker: 1
  • Environment IP Allowlists support up to 250 IP addresses. This limit can't be raised.
  • Environment access control headers support up to 2 headers. Each header:
    • Can contain up to 128 characters.
    • Can be a combination of alphanumeric characters and - and _ characters
    • See Access Control Headers.
  • The execution time for App Server requests is limited to 20 seconds.
  • Unhandled promise rejections break app rendering.
  • The maximum size for bundles is 400 MB and the maximum size of all ssr_only and ssr_shared files within the bundle is 249 MB.
  • Static assets that can be uploaded and served are limited to the following content types: application/javascript, application/json, image/png ,image/gif, image/jpeg, image/svg+xml, image/webp, text/css, text/plain and fonts (ttf, woff, woff2, otf, etc). All other content types need to be served by external system.

Managed Runtime Proxies have different constraints.

You can subscribe to updates regarding the availability of Managed Runtime services on Salesforce Status.

Now that you have an overview of the main parts of Managed Runtime, it’s time to get hands-on! A good place to start is the Push and Deploy Bundles guide.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.