Documentation

Deployment overview

Learn how to build and deploy your website.

If you are using a custom Git repository, you must set up a CI yourself.

commercetools Frontend development follows a trunk-based model, where the master branch serves as the source of truth and is the recommended branch for deploying to staging and production environments.

You can use different branches for each environment. To do so, you must change your Netlify settings so that:

  • The production branch of your staging site is the branch you want to use for staging deployments.
  • The production branch of your production site is the branch you want to use for production deployments.

For example, on Netlify you have the staging.docs.frontend.site staging site and the docs.frontend.site production site. The staging.docs.frontend.site site has the production branch set to staging and the docs.frontend.site has set the production branch set to main.

Branch deployments

When you push a commit to your repository, the commercetools Frontend CI automatically detects the change and creates a new build for this branch. The build of the master branch is deployed to the staging environment. The build of any other branch is deployed automatically when a request comes for the build version. Once deployed, a build remains active for one hour, after which it is removed and can be reactivated with a new request if space is available for a new branch deployment. You can access the previews of your builds from the Frontend preview area in the Studio.

The Studio builds and maintains multiple versions of the backend build so that the extension runner can activate the extensions for any branch deployments based on the incoming frontend request.

Your project can have up to 20 active branch deployments. If you exceed this limit, new branch deployments will be rejected, and requests to the branch deployment from your website will result in a 503 response code.

How backend and frontend builds are connected

When you create a pull request, the commercetools Frontend CI deploys your backend, while Netlify deploys your frontend site. Using this approach, you can preview and test both your backend extensions and frontend code together.

To ensure the frontend deployment on Netlify is connected to the backend extensions from the same build version, the API hub uses the Git commit hash of the build version because this is the same for the backend and frontend build.

By default, you can access deploy previews for pull requests on the master branch directly from the Frontend previews area in the Studio. To see deploy previews for other branches, you must configure your Netlify settings or talk to your Customer Success Manager.

You might get a slow response for the first request to the extensions, and in rare cases, the request could timeout. If this happens, resend the request after one or two minutes.

Test the build

By default, successful master builds are automatically deployed to your staging environment, where you can test your changes before promoting the build to the production environment.

The master build for the frontend is deployed automatically to your staging site on Netlify. You can use the staging site to test changes before promoting them to the production environment.

You can request that successful builds are not automatically deployed. For further information, contact your Customer Success Manager.

Deploy a build

Studio deployment process

You can deploy both the frontend and backend build for your project in the Studio. If you submit multiple deployments, they are added to a queue and deployed asynchronously when they reach the top of the queue. To handle deployments robustly, the Studio follows this process for the next deployment in the queue:

  1. It builds and deploys the backend. If the build fails, the process stops and deployment fails.
  2. It verifies if the backend build is deployed successfully. If not, the process stops and deployment fails.
  3. The Studio initiates the frontend build and deployment. If this fails, the previous frontend production deployment will continue to work correctly because the previous backend extensions are available. For more information, see Branch deployments.

You can deploy a build using the Studio or using the command-line.

Deploy using the Studio

To deploy a build version, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Staging or Production section, click Deploy frontend and backend: the Builds available dialog opens. The dialog displays the builds that you can deploy for that environment based on your Netlify settings. If a build cannot be deployed in production, it appears in the list of the production builds but it is greyed out.
  3. Click the build you want to deploy. When you confirm the deployment, it is added to the queue and the short commit hash and the deployment status are displayed.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

Deploy using the command-line

To deploy using the command-line, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. Click Deploy from command line expandable section.
  3. To copy the command, click the content of the section.
  4. Open a command-line tool on your computer and paste the command.
  5. Replace ####.##.##.##.## with the build version you want to deploy.
  6. To run the command, press Enter.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

View deployment details

To view the details of the latest deployment, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Staging and Production sections, you will find the URL, short commit hash, and date and time of the build release for both frontend and backend builds. For backend builds, up to three short commit hashes are displayed.

You can view the status of deployments initiated by the Studio or the CLI by clicking the Deployments history icon. A successful, failed, or scheduled status is displayed next to each deployment.

The Deployments history does not display automatic deployments triggered by the Frontend development pipeline.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

A version mismatch error message appears next to the Short commit hash field if you trigger a deployment from the Netlify dashboard or if the auto publishing lock on Netlify is not active. You can resolve the problem by creating a new deployment from the Studio.

Roll back deployment

To roll back a deployment, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Staging or Production section, click Deploy frontend and backend: the Builds available dialog opens. The dialog displays the builds that you can deploy for that environment based on your Netlify settings. If a build cannot be deployed in production, it appears in the list of the production builds but it is greyed out.
  3. Click the build you want to roll back to.