Managed Runtime Administration

Managed Runtime makes it easy to manage your organizations, projects, environments, and bundles associated with your PWA Kit storefront. This guide describes the growing list of administration tasks that are possible in the web-based Runtime Admin tool. (All of the administration tasks described in this guide, and many more, can also be done using the Managed Runtime API.)

Before you continue, make sure that you have access to Managed Runtime and Runtime Admin. To provision Managed Runtime, contact your Success Manager. For Runtime Admin, 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.

Projects help you manage multiple environments within an organization. Every PWA Kit project needs a corresponding project within Managed Runtime for deploying and hosting the storefront code on Salesforce’s public cloud infrastructure.

To create a project in Runtime Admin:

  1. Log in to Runtime Admin.
  2. Click New Project.
  3. Enter a name for the project.
  4. Click Create Project.

When you first create a project, your site isn’t accessible on the web until after the necessary cloud infrastructure is deployed. This deployment process can take up to 40 minutes.

The instructions for the rest of the administration tasks in this guide all assume that you’re starting from a project Overview page in Runtime Admin.

To find an existing project and open its Overview page:

  1. Log in to Runtime Admin.
  2. Select an organization from the organization menu (top left), if necessary.
  3. Click the name of the project. (To see the project, you must be assigned one of the project roles described previously.)

Associated screenshot

To quickly switch between projects, use the project menu at the top of the page.

The Project Settings page is where you can do the following tasks:

  • Look up the project ID and ensure that it matches a PWA Kit configuration.
  • Edit the project ID.
  • View and edit the project’s name and URL.
  • Delete the project.
  • Manage deployment notifications. (See next section.)

To access the Project Settings page:

  1. Go to a project’s Overview page.
  2. Click Project Settings from the left navigation.

To edit the settings, click Edit, make your edits, and click Update. To discard your edits, click Cancel.

To delete a project, click Delete, enter the project name to confirm, and click Yes, Delete. To keep the project, click No, Keep.

You can choose to be notified by email whenever any of the following deployment events happen:

  • Start Deployment
  • Successful Deployment
  • Failed Deployment

To add a notification:

  1. Go to a project’s Overview page.
  2. Click Project Settings from the left navigation.
  3. Click Add Notification.
  4. Select one or more environments to be notified about.
  5. Select one or more deployment events.
  6. Enter email addresses for all notification recipients.
  7. Click Add Notification.

Associated screenshot

To edit a notification:

  1. Go to a project’s Overview page.
  2. Click Project Settings from the left navigation.
  3. Click the ... button next to the notification.
  4. Click Edit.
  5. Change any of the notification settings.
  6. Click Update Notification.

Associated screenshot

To remove a notification:

  1. Go to a project’s Overview page.
  2. Click Project Settings from the left navigation.
  3. Click the ... button next to the notification.
  4. Click Remove.
  5. Click Yes, Remove.

Associated screenshot

Environments are used to separate your production storefront from other storefronts that are deployed for other purposes, such as development or testing. To learn more about environments and other related concepts, see the Managed Runtime Overview.

To create an environment in Runtime Admin:

  1. Go to a project’s Overview page.

  2. Click New Environment

  3. Enter a name for the environment.

  4. Select a region for deploying to Salesforce’s public cloud infrastructure.

  5. If the environment is a production environment:

    • Mark it as production. If you have reached your limit of production environments, contact Support. For more information, see Production Environments.
    • Add one or more site IDs to associate with the environment.
  6. Select a Commerce Cloud instance to connect to the environment.

  7. Click Complete Setup.

  • The default region for new environments is US East (N. Virginia) because it’s located closest to on-demand sandboxes, which are commonly associated with development and testing environments.
  • If you previously created an environment, you can Edit Environment Settings to connect it to a Commerce Cloud instance and one or more site IDs.
  • There is no difference in the resources provided to a production or non-production environment. All environments automatically scale to handle traffic in the same way. For details, see Production Environments.

For any site that uses PWA Kit and Managed Runtime, you can only designate one bundle at a time as deployed for each environment.

  1. Go to a project’s Overview page.
  2. Click the name of the environment you want to deploy to. For example: production.
  3. Under the heading Bundles, click the Deploy button next to the bundle you want to deploy.
  4. Click Confirm Deploy.
  5. Wait until the deployment is complete.

When the deployment has successfully completed, the bundle appears underneath the heading Deployed Bundle. (For your first deployment to a new environment, the process can take up to an hour to complete.)

The Environment Settings page is where you can do many administration tasks in one place, including:

  • Rename an environment or environment ID.
  • Change the deployment region.
  • Enable or disable server-side cookies. See Personalize with Cookies.
  • Enable or disable Source Maps.
  • Allow specific IP addresses to access an environment.
  • Configure proxies for an environment. See Proxying Requests for more information.
  • Mark an environment as production.
  • Add, edit, or remove site IDs associated with an environment.
  • Add or edit an environment’s connection to a Commerce Cloud instance.
  • Delete an environment.

To access the Environment Settings page:

  1. Go to a project’s Overview page
  2. Click the name of the environment whose settings you want to edit.
  3. Click Environment Settings from the left navigation.

To make edits, click the Edit button next to either the General settings or the Advanced settings. After making your edits, click Update to save your changes or click Cancel to discard your changes.

Environment variables allow you to add variables into the application process running in an environment, without having to make code changes. Environment variables are stored securely, making them ideal for use cases such as:

  • API keys for third-party integrations
  • Feature flags for application logic
  • Configuration that differs between environments

See Environment Variable Tutorials.

Environment variables are only accessible in the app server. They cannot modify the behaviour of edge services including proxies and edge functions.

Environment variables can be managed using the Managed Runtime API and accessed in Node.js using process.env.

When you introduce a new environment variable, first set it via API. Wait until redeploy completes and then deploy a new bundle that uses it.

To set, update, and unset environment variables use projects_target_env_var_partial_update:

To unset an existing environment variable, set its value to null.

Modifying environment variables redeploys the environment. The updated values are available when the deploy completes.

To get all environment variables set on an environment use projects_target_env_var_list:

  • Choose environment variable names that make sense for your app. Use descriptive names: Choose clear and concise names for your environment variables to make them easily understandable for your team.
  • Avoid hardcoding sensitive information like API keys in your code. Use environment variables to keep them secure.
  • Don't pass environment variables into data that will be serialized to the page. Consider adding a test to make sure you're not leaking environment variable data.
  • Don't put environment variables in your configuration. Don't return environment variables from getProps or react-query hooks.
  • Use environment variables only server-side. By default, environment variables aren’t exposed client-side. You can choose to expose them client-side, but make sure that exposing the values complies with your security practices.
  • Test your environment variables on your local machine, then in a non-production environment before deploying them to production. This helps to ensure that you can quickly resolve issues locally, then simulate site behavior, validate functionality, and do any user acceptance testing before deploying to production.
  • Include error handling in your code that uses environment variables to prevent failures due to undefined environment variables.
  • Control access to the environment variables to prevent unauthorized modifications.
  • Document the purpose and configuration of each environment variable. This helps in onboarding new developers and troubleshooting issues.

The usage of environment variables is subject to the following constraints:

  • Environment variable values must be strings. To store complex values, encode JSON into a string.
  • Each environment has a limit of 100 environment variables.
  • The maximum size of the values of environments variables set for an environment is 32 KB.
  • Environment variable names must be 512 characters or less, and cannot start with reserved prefixes: AWS, MRT, X_MRT, MOBIFY, X_MOBIFY, SSR_PROXY, NODE.
  • Environment variable names cannot use any reserved names: BUNDLE_ID, DEPLOY_ID, DEPLOY_TARGET, EXTERNAL_DOMAIN_NAME, HANDLER, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, NODE_ENV, REDIRECT_BUCKET, REDIRECT_KEY, REDIRECT_UPDATE, REMOTE, X_AMZN_TRACE_ID.

This section provides suggested solutions for common errors that you might encounter while using environment variables. See Environment Variables Tutorials.

Your code throws an Error stating that a variable is missing.

Cause: The environment variable that the code calls isn’t set.

Suggested Solution: Call the projects_target_env_var_partial_update API endpoint to set the applicable environment variable.

Your code logs an error message stating that the environment variable wasn’t found.

Cause: The code couldn’t find the environment variable because there’s a typo in the code or an incorrect environment variable name is used.

Suggested Solution: Confirm that you spelled the environment variable name correctly in your code and you used the desired environment variable name. Check the environment variable name by calling the projects_target_env_var_list API endpoint to see the full list of variables that are set.

Your API call to set an environment variable fails.

Cause: The environment variable name might not comply with the constraints. For example, the size of the value of an environment variable is over 32 KB.

Suggested Solution: Confirm that your environment variable complies with the constraints.

Authentication errors occur when you execute code that involves using an API key.

Cause: The API key that you used when you set the environment variable is not in the expected format or is missing.

Suggested Solution: Confirm that the API key stored by an environment variable is correct. If needed call the projects_target_env_var_partial_update API endpoint to correct the API key.

A fetch request fails with a network error.

Cause: A URL for any API endpoint called in your code might not have been correctly defined or is invalid. For example, the URL for a content management system (CMS) endpoint is incorrect.

Suggested Solution: Confirm that any URLs for API endpoints in your code are correct.

A redirect allows you to forward a request from the requested URL to a different URL. Redirects can help avoid disruptions to the user experience caused by changes to your storefront. For example, consider a seasonal campaign page for spring. When the spring campaign ends and is replaced with a summer campaign, you can redirect from the spring URL to the summer URL.

Redirects is a powerful feature that can have significant security consequences on your storefront, including redirecting to malicious URLs or assets. Please be careful when assigning roles to your users that give them Redirect access.

Before creating a redirect in a production environment, we recommend that you create it in a staging environment first.

To create a redirect:

  1. Go to a project’s Overview page.
  2. Click the name of the environment where you want to create the redirect.
  3. Click URL Redirects from the left navigation.
  4. Click Create Redirect.
  5. In the Redirect From field, enter a relative URL path. For example, to redirect visitors from the URL www.example.com/winter, enter /winter.
  6. In the Redirect To field, enter a relative URL path.
  7. If needed, enable forwarding of query parameters and the wildcard path. (More information on forwarding settings in a moment.)
  8. From the Redirect Type dropdown menu, select a redirect type based on the HTTP status code. (More information on status codes in a moment.)
  9. Click Create Redirect.

Let’s look at the options for creating a redirect in more detail.

The value that you enter in the Redirect From field must always be a relative path. The Redirect To field can be either a relative path or a full URL. For example, imagine that we want to redirect visitors from www.example.com/spring to www.example.com/summer. The Redirect From field must be /spring. The Redirect To field can be either /summer or www.example.com/summer.

You can add an asterisk character (*) to the end of the Redirect From URL to indicate a wildcard. A wildcard matches any (0 or more) characters in the URL. For example, a redirect from /a/* would match /a/, /a/b, and /a/b/c.

A wildcard character can only be used at the end of the Redirect From URL.

Standard redirects are processed first by Managed Runtime, followed by redirects with wildcards.

Most redirects use the Permanent 301 status code, but you can also select Temporary 302. If you’re unsure which HTTP status code to use, consult this status code explainer from MOZ.com.

Some requests contain query string parameters that you also want to include in the redirected request. For example, the relative path /spring-landing-page can be appended with a query string for analytics tracking, such as /spring-landing-page?gclid=123.

To enable query parameter forwarding, go to the Forward section of the form and select Query Parameters. Otherwise, query string parameters from the source URL aren’t included in the redirect URL.

What happens when both the Redirect From and Redirect To URLs both have query strings and forwarding is enabled? In this case, the redirect URL includes a combination of the two query strings. The query parameters from the Redirect To URL are appended to the query string in the request. For example, imagine your application receives a request for the relative path /spring?year=2019. If you’ve chosen to redirect /spring to /summer?year=2020, the redirect URL is /summer?year=2019&year=2020 when forwarding is enabled.

You can automatically include any path that comes after the wildcard portion of the Redirect From URL in the Redirect To URL. For example: if /a/* matches /a/b/c in the Redirect From URL, and the Redirect To URL is /z/, the redirect URL is /z/b/c.

To enable wildcard path forwarding, go to the Forward section of the form and select Wildcard Path.

We recommend that you always create redirects in a staging environment and clone them into production after testing them.

You can copy all the redirects from one environment to another using the clone redirects feature.

To clone redirects:

  1. Go to a project’s Overview page.
  2. Click the name of the environment that contains the redirects that you want to clone.
  3. Click URL Redirects from the left navigation.
  4. Click Clone Redirects. The Clone Redirects form appears. The current environment is listed under From Environment (the source).
  5. Under To Environment, select the environment that you want to clone the redirects into (the destination).
  6. Click Clone n Redirects. (Where n is the number of redirects to be cloned.)

When you clone redirects, you’re replacing all the redirects in the destination environment with all the redirects from the source environment.

To edit the settings for an existing redirect:

  1. Go to a project’s Overview page.
  2. Click the name of the environment that contains the redirect that you want to edit.
  3. Click URL Redirects from the left navigation.
  4. Click the ellipsis button (...) next to the redirect.
  5. Click Edit.
  6. Update the settings.
  7. Click Update Redirect.

To delete a redirect:

  1. Go to a project’s Overview page.
  2. Click the name of the environment that contains the redirect that you want to delete.
  3. Click URL Redirects from the left navigation.
  4. Click the ellipsis button (...) next to the redirect.
  5. Click Delete.
  6. Click Yes, Delete Redirect.

If a redirect isn’t working as expected, try these troubleshooting steps:

  • Clear your browser cache because redirects are cached.
  • Verify that you’re viewing the settings for the correct environment.
  • Edit the redirect and verify that the correct values are entered in the Redirect From and Redirect To fields.

Redirects have the following technical limitations:

  • Each environment can have a maximum of 10,000 redirects.
  • Each environment has its own set of redirects. It is your responsibility to keep them in sync using cloning.
  • The redirects feature supports simple redirects from one path to another. For complex redirects with conditionals use Express.js' redirects support in ssr.js.
  • Redirects created with the Runtime Admin tool or the Managed Runtime API are not run on local development environments.
  • Redirects are not triggered by page transitions in the PWA Kit application; they can only be triggered by an HTTP request.

Here’s how to manage your users.

To add a user to a project:

  1. Go to a project’s Overview page.
  2. Click Users & Permissions from the left navigation.
  3. Click New User.
  4. Enter the user’s email address. (Make sure that the user is part of your organization and has either one of the following roles in Account Manager: Managed Runtime User or Managed Runtime Admin.)
  5. Select a role.
  6. Click Add User.

Associated screenshot

To change a user’s role:

  1. Go to a project’s Overview page.
  2. Click Users & Permissions from the left navigation.
  3. Click the ... button next to the user’s name.
  4. Click Edit.
  5. Select a role.
  6. Click the popup menu that appears.
  7. Select a new role.
  8. Click Save.

Associated screenshot

For a list of user abilities associated with each role, see the Managed Runtime Overview.

To remove a user from a project:

  1. Go to a project’s Overview page.
  2. Click Users & Permissions from the left navigation.
  3. Click the ... button next to the user’s name.
  4. Click Remove.
  5. Click Yes, Remove User.

Associated screenshot