This blog post guides users on quickly setting up and configuring their commercetools projects in a reproducible way.
As a Solutions Engineer, my job within commercetools is to talk to clients and prospects, and align their requirements with what we provide in our product portfolio. This includes demonstrating and explaining our business user tool, the commercetools Merchant Center, and APIs. Our clients range from B2C to B2B, automotive to telecommunications (telco), fashion, online retail and any other channel you can imagine.
When I joined the company in 2022, commercetools was in a significant growth period, scaling to over 40 Solutions Engineers, each bringing their own pool of dedicated technical knowledge. Some had worked extensively in telco, while others had done considerable work in the fashion industry. We all brought our prior knowledge and invaluable customer use cases to provide the best possible demo environments across the board.
However, despite the plethora of technical knowledge across the teams, our varied expertise did not translate well to a knowledge-sharing standpoint and left questions regarding demo organization and usage. Because of these concerns, we began consolidating our demos by using the data and features in fewer reusable environments, resulting in a less complicated, more robust set of demo resources for our teams.
In the following sections, we share our tried and tested approaches and best practices for kickstarting your commercetools projects and ensuring continued success in the eCommerce landscape.
Aligning the commercetools project setup
We typically approach project setups in one of two ways: Standard or tailored demos.
Sometimes, clients want to see a tailored demo that features their products. These demos are specifically designed to showcase how a client's products or services would work within the project framework. It involves customizing the demo to highlight features most relevant to the client's business model, industry or specific challenges.
In other cases, clients want to witness the full power of the platform, inspiring them to see what their future commercetools-powered site could look like. In this demo approach, the emphasis is on exemplifying the full range of capabilities of the project setup, which includes all available features, tools and integrations with no client-specific customizations.
The ideal demo process for us combines the best aspects of both approaches. We begin by choosing from our various standardized product data, such as “Fashion,” “Home Decor,” “Pharmacy” or “Telco.” We have a selection of readily available demos that include our standardized product data, and we can also rapidly create new, tailored versions almost instantly if customization is needed. This combined, customized approach will be the focus of this blog post.
Using the commercetools APIs
commercetools consistently adheres to an API-first strategy, using APIs to develop projects efficiently. We provide two distinct API endpoints for this:
Our HTTP API gives you direct feedback and a nuanced granular approach to every item within commercetools. commercetools provides JavaScript Composable Commerce Developer Training to assist you in learning everything you need to know about our APIs.
Our Import API offers a "fire and forget" feature for bulk data imports, designed to efficiently handle the upload of millions of items in a single action.
Moreover, our partner, Lab Digital, has developed a commercetools Terraform provider that works with our APIs. This addition streamlines the process of executing consistent actions across various environments. We make extensive use of these essential tools. The following section of this article demonstrates these features to give you a better understanding of their functionalities. You can also find the pertinent code on GitHub for further insight.
commercetools Project build configuration
To ensure that Terraform and the commercetools APIs correctly connect to the intended project, setting up an API client first is necessary. You can follow the instructions in the provided documentation to do this.
Export the configuration in the .env format.
Insert these values into the .env file in your workspace at ./b2c/typescript/.env.
It should look something like this:
This example utilizes the API endpoints located in Europe. It's important to note that the IMPORT_API_URL has a different endpoint than CTP_API_URL. You can find more information about this in the commercetools documentation for hosts and authorization. Additionally, we use the TypeScript SDK from commercetools for interacting with commercetools Composable Commerce.
Because of this, the code needs to be transpiled first. To do this, run the following commands:
The following section provides detailed instructions for setting up your workspace correctly and best practices for using Terraform to import standard data configurations.
Bootstrapping the project using Terraform
Initially, our goal is to import all the standard configurations typically used, such as Languages, Countries, Currencies, Shipping Methods, Product Types and more. While this can be accomplished using our HTTP API, we prefer utilizing Terraform for this task because it offers an easy rollback option. However, before importing data, we should first set up the workspace properly.
Run cd ./b2c/terraform to enter the terraform directory and terraform init and terraform plant to get everything ready. Last, run terraform apply and confirm with yes to kickstart your project.
The repository approach is to share as many configuration files as possible. Therefore, most terraform configuration is loaded using modules from the shared-code/terraform folder, as shown below:
Here, you can adapt any configuration. We found having the same shipping methods or tax categories available per default is most beneficial.
Importing the data
The demo data is available in CSV files ready for import. The provided code will process these files, converting the data into commercetools objects, and then send them to the import API. Because you have previously configured the endpoint, everything is ready for the import step.
To proceed with the data import:
Execute the command cd ./b2c/typescript followed by yarn run bootstrap.
Select Import Data > Categories (or the appropriate menu choice for your data import).
3. Run the category/data import
Below, we've provided an example of what the import process looks like in real time:
Once the data import is completed, the commercetools Merchant Center provides the details of the import, as shown below:
Once all the data is imported, you'll have a fully functional and configured project set up in a reproducible manner in just a few minutes — possibly even seconds, depending on your typing speed. From here, you can begin accessing or testing it through Business User tooling or APIs.
This project incorporates all the best practices for using the import API. However, remember that the provided code represents a specific approach, and we might have yet to consider some aspects. Because of this, we welcome your contributions to this project to enhance its breadth and effectiveness.
Tips and tricks
In this section, we offer practical advice and efficient strategies for optimizing the use of commercetools APIs and Terraform in project setups to enhance user experience and streamline project implementation.
The import process includes a feature for translations using Google Translate. To utilize this, you should:
Log in to Google using the google-cli.
Set the TRANSLATION_ENABLED="true" parameter in your .env file.
Keep in mind that this feature can incur a cost. The translations from Google are saved in a JSON file, serving as a basic translation memory system.
For development purposes, you might not always want to execute a real data import. In such cases, enable the DRY_RUN=true flag in your .env file. Most operations occur within the ./shared-folder directory, so you can use yarn run watch or yarn run test to build or test your changes continuously.
Additionally, this workspace allows for exporting data to CSV files and provides on-the-fly translation capabilities for a project.
Final thoughts
This blog post details the most efficient setup and configuration for your commercetools projects, emphasizing the importance of a reproducible and streamlined process. From the diverse experiences of our Solutions Engineering team to the practicalities of using our APIs and Terraform, we've covered key aspects that ensure a successful project launch.
We aim to provide a flexible yet robust framework for successfully setting up your commercetools projects, accommodating everything from client-specific customizations to comprehensive demonstrations of our platform's capabilities. As commercetools continues to evolve and share our internal knowledge, we look forward to any of your contributions or insights that will enhance the commercetools experience for all users.
Stay tuned for more insights and tips for successfully kickstarting your commercetools projects in our upcoming Technology blog posts.
Phillip Hoffman has more than 15 years of experience in consulting and solution design. He has worked across the globe with large brands, retailers and telcos, helping them with major business initiatives around digital content, as well as to design solutions that intelligently blend content and commerce.