Push and Deploy Bundles

To run your commerce application on Managed Runtime, you must first push a code bundle and deploy it to a target environment.

This guide shows you how to:

• Set up your API key.
• Use a command-line script to push a bundle to Managed Runtime.
• Use the Runtime Admin web application to deploy a bundle to the production environment.

Before you can push a bundle, you must first authorize your computer.

Start the authorization process by looking up your personal API key:

1. Log in to Runtime Admin.
2. Click the user profile icon (top right) and click Account Settings.
3. Scroll down to the section called API Key and look for Personal API Key.
   • If you haven't yet created an API key, click the Generate link.
   • If you already have an API key, click the Reset link and click Reset my API Key when asked for confirmation.
4. Copy the command to use your API key.

For security, when you return to the Account Settings page, the API key isn’t displayed in full, so you must reset it to copy the full text of the API key again.

From the command line, go to your PWA Kit project directory and run the command that you copied.

Run the command again on any other computers that you want to use for pushing bundles.

Pushing a bundle involves running a script that packages up your code into a Webpack bundle and uploads it to the Runtime Manager.

Before pushing your first bundle, verify that the package.json file in your PWA Kit project directory is configured correctly:

1. Log in to Runtime Admin.
2. Click the name of your project.
3. From the left navigation, click Project Settings.
4. Copy the Project ID string. Example: my-project.
5. Paste it into the name field in package.json.

To ensure that your bundle works correctly when deployed, you must set your proxies on your environment in Runtime Admin.

If you are using a SLAS private client, you must set the client secret via an environment variable.

To push a bundle, go to the command line and run the following command from your project directory:

For a list of other options you can supply to the push script, run npm run push -- --help.

When a bundle is successfully pushed, the message Beginning upload… appears in the terminal followed by the message Bundle Uploaded!.

If something went wrong, look for one three possible error messages (based on HTTP response status codes) in your terminal after the Beginning upload… message.

Here’s how to troubleshoot each error message.

An HTTP 404 error is returned in the terminal when a project does not exist with the name specified in package.json or when you are not authorized to change the project.

To fix the error:

1. Repeat the steps to push a bundle and make sure that the email address and API key settings you pass to the push script match the settings in Runtime Admin.
2. Verify that your project appears on the Runtime Admin home page under Projects.
   • If your project does not appear, contact support to make sure that the project has been created and that you have been granted access to it as a team member
3. Open the project on Runtime Admin.
4. From the left navigation, click Project Settings.
5. Copy the Project ID string. Example: my-project.
6. Open the package.json inside your project directory.
7. Verify that the values for name and projectSlug both match the project ID string that you copied.

An HTTP 401 error is returned in the terminal when you do not have permission to push bundles. To fix this error, contact your Commerce Cloud Account Manager administrator and ask to have your permission elevated to include pushing bundles.

An HTTP 413 error is returned in the terminal when your bundle is too large. 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. To fix this error, check the size of your bundle by inspecting the build folder within your project. If your project is nearing the maximum size or has already exceeded it, here’s what you can do to reduce it:

• Remove unused assets
• Remove unnecessary assets
• Scale down images

After reducing the size of your project files, try pushing the bundle again.

HTTPS errors can occur when your local computer or network proxies like a corporate VPN or firewall have not been configured to communicate with Managed Runtime's API, hosted at cloud.mobify.com.

These errors may include messages like unable to get local issuer certificate or self signed certificate in certificate chain.

To resolve these errors, work with your corporate IT team to configure your Node.js installation for your corporate network environment.

After you’ve successfully pushed a bundle, you can deploy it to a target environment.

For any site that uses PWA Kit and Managed Runtime, you can only designate one bundle at a time as deployed for each environment. By default, every project comes with a single environment, called production. You can create more environments using Runtime Admin or the Managed Runtime API.

To deploy a bundle:

1. Log in to Runtime Admin.
2. Click the name of your project.
3. Under Environments, click the name of the environment that you want to deploy to (example: Production).
4. Under Bundles, click the Deploy button next to the bundle.
5. Click Confirm Deploy.
6. Wait until the deployment is complete.

When deployment has successfully completed, the bundle appears underneath the heading Deployed Bundle.