Pushing and Deploying Bundles

To run your commerce app on the 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 the Managed Runtime.
  • Use the Runtime Admin web application to deploy a bundle to the production environment.

Access to Runtime Admin

Before you can push and deploy code bundles to the Managed Runtime, you must request access to the Runtime Admin web application. Contact your Commerce Cloud administrator and ask them to add either one of the following roles to your account using Account Manager: Commerce Runtime Manager User or Commerce Runtime Manager Admin.

Saving Your Credentials

If you already have a .mobify file in your home directory, you can skip this section.

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 your username (top right) and click Account Settings.
  3. Copy the email address that appears in the Profile section.
  4. Scroll down to the section called Security and look for Personal API Key.
  • If you are an existing user, click the Reset link and click Reset my API Key when asked for confirmation.
  • If you are a new user, click the Generate link.
  1. Copy the API key.

(For security, the next time you come back to the Account Settings page, the API key will not be 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 following command:

In the previous example, replace <EMAIL> and <API_KEY> with the email address and API key that you copied from the Account Settings page. Keep the double quotes on both sides of each argument.

Verify that a file called .mobify has been created in your home directory. (Show “invisible” files to see it, if necessary.)

Run the save-credentials script again on any other computers that you want to use for pushing bundles.

Pushing a Bundle

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

Verifying Project Configuration

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, projectSlug, and aJSSlug fields in package.json.

Verifying Proxy Configuration

Verify that the following fields are set correctly for each item in the mobify.ssrParameters.proxyConfigs array within package.json:

  1. protocol: depending on your configuration, set this to either http or https.
  2. host: set this to the hostname of your server.
  3. path: set this to the base path of your server.

That’s it! Now you’re ready to start pushing bundles!

Running the Push Script

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.

Troubleshooting Bundle Push Errors

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.

HTTP 404 Error

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.

HTTP 401 Error

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.

HTTP 413 Error

An HTTP 413 error is returned in the terminal when your bundle is too large. The maximum size for bundles is 37 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.

Deploying a Bundle

Once 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. (For your first deployment to a new environment, the process can take up to an hour to complete.)