Build and Deploy Your First SAP Commerce Cloud Project
SAP Commerce Cloud provides a lot of self-service features to configure, build and deploy a commerce solution. When you're first getting started it could seem like a lot to take in. In this article we'll take you through step-by-step how to use the self-service features to configure your application, followed by how to build and deploy to your development environment. After following the steps in this article you should be comfortable with adding in any additional customizations and deploying them to your environment of choice. Before going through this article we do recommend you read our article on Getting Started with SAP Commerce Cloud, which covers some of the concepts/terms we'll be referring to in this article. You may also wish to review the Initial Setup and Storefront Validation section of the product documentation, which this article expands upon.
Table of Contents
- Initial Access to SAP Cloud Portal
- Connect an Empty Git Repository
- Set Up Your Git Repository
- Secure Your Solution
- The Initial Build
- The Initial Deploy
- Monitor your Application
- Removing the Accelerator
Initial Access to SAP Cloud Portal
Before you even think of building and deploying a project, you should first take a moment to get acquainted with the Cloud Portal, which is the self-service tool for managing your SAP Commerce Cloud solution. To access Cloud Portal, you'll need to have an SAP User ID (S-user) and have been granted access by someone with a Customer System Admin role. If you're not sure who your super Admin might be, you can navigate to https://launchpad.support.sap.com/#/user/management, select "Important Contacts" and then look for someone with the "Super Administrator" role. They can then grant you access like in the following video:
Assuming you're either a super admin or someone has granted you a role you can go to https://portal.commerce.ondemand.com/. If you have trouble with your password see this page in the product documentation. Make sure you're also using a supported browser.
Once you're logged in, you should make sure you have some environments provisioned. You can do so by clicking on the "Environments" button in the top left of the Cloud Portal. You should have at least 1 development, 1 stage and 1 production environment (if you require more environments, they are available for purchase). If you do not see any environments provisioned then you will need to find your super admin to use the self-service environment provisioning in the SAP Customer Experience Cockpit like in the video below:
Connect an Empty Git Repository
The next step is to connect your empty Git repository you will be using for maintaining the code which will be built and deployed on SAP Commerce Cloud. Each subscription for SAP Commerce Cloud comes with the ability to connect to a single Git-based repository. The git repository needs to be on a public accessible server(not behind a firewall in a corporate environment). Access through SSH and HTTPS methods are both possible. The following video shows how to connect to a Git repository:
Set Up Your Git Repository
Now that your Git repository is connected, this section will help take your through the steps to populate the repository with code. There is an extensive section in the product documentation with various ways you can populate the repository, but if you're looking for a working template to get you started there are various code samples you can download to initially populate your repository. this section will cover how to get started with sample code which contains the structure for a working Spartacus-based storefront as well as a sample accelerator-based storefront.
Get it Working Locally
Given your development team will most likely be developing and testing customizations locally, you should try to structure your repository to allow for building both locally and on your SAP Commerce Cloud environments. To do this, you'll need to keep in mind a few things:
- Ensure you're using your gitignore file to only upload items to your repository that aren't automatically added as part of the SAP Commerce Cloud build automation process. For example, you shouldn't be adding the SAP Commerce "bin" folder as the relevant extensions you declare in your manifest file (see below) will be automatically added as part of the build.
- The sample code assumes you will want to develop with Cloud Hot Folders locally. Even if you're not using the optional Cloud Extension Packs, you need to download the artifact, as you will need the sap-ccv2-hotfolder module that comes with it. If you're using Cloud Extension Packs then you will need all the code. To download search for "CX Comm" in launchpad.support.sap.com and select the "Ext Pack" for your version. See Testing Cloud Hot Folders in a Local Environment in the product documentation for more.
- You'll need a copy of the latest patched version of SAP Commerce core that you'll be using. See this page to find out how to download.
Now that you're ready to get started locally, do the following:
- Clone your empty git repository where you will be storing your code
- (optional) If you want to start off your code review process correctly from the very beginning, you may want to create both a 'develop' and 'feature' branch where you'll be storing your code
- Go to https://github.com/SAP-samples/cloud-commerce-sample-setup/tree/1905-spartacus and download a zip of this code sample. Note: the code sample repository contains multiple branches, each covering a distinct use case (data hub, spartacus, vanilla). You may choose to select a different branch, but for this example we are using the Spartacus branch.
- Unzip the sample code file into where you cloned your git repository
- In a different location unzip a copy of your SAP Commerce core
- Move the following folders from the unzipped SAP Commerce core directory into the core-customize/hybris/bin from step #4
- Unzip the Cloud Extension Pack artifact and copy the contents of "hybris/bin/modules/" into the "hybris/bin/modules-cep" directory from step #4
- Complete the steps for the following sections of the installation steps in the product documentation:
Setting up Apache Ant
Run the following code to ensure your add-ons are loaded correctly:
- Continue with the following sections of the installation steps in the product documentation:
Performing the Build Procedure
Starting the Application Server and Deploying the Application
Initializing SAP Commerce
(Optional) If you want to have a local Blob storage instance for testing out Cloud Hot Folders you can go into hybris/config/local.properties file and un-comment the lines with the following keys:
If you accidentally uncomment these without setting up a local Blob storage your solution will still start, but you'll just see a lot of errors in your logs like "Connection refused (Connection refused): 127.0.0.1:10000"
You should now have your SAP Commerce solution running locally
- Once your SAP Commerce Cloud solution is running locally (e.g. you can get to localhost:9001/hac) it's now time to get your Spartacus storefront built and running locally. To do this navigate to the js-storefront/spartacusstore
Execute the following command, which will build and run your storefront:
- You should now have local instances running of SAP Commerce and the Spartacus storefront. To confirm the Spartacus storefront is working please navigate to http://localhost:4200
Review and Configure Your Build Manifest
The Build Manifests enable you to configure your SAP Commerce Cloud solution to your exact specifications. You can define the build process using a manifest.json file, which is stored in your code repository. A sample manifest.json file has been included as part of the sample code we provided above. For this step you should review the manifest file to ensure you understand what each of the components are for and how the sample is configured. It is recommended that you minimize the changes in the beginning to ensure it works first with the Cloud Automation tooling. Some changes you likely would make in the future include
- commerceSuiteVersion - which version of SAP Commerce Core you're using
- storefrontAddons - if you have any additional add-on extensions you've enabled in your localextensions.xml file you should ensure they are included in your manifest
- aspects - define any properties and webapps for any of the pre-defined aspects
- tests - if you have any tests within your extensions you would like to run as part of the Cloud Automation builds you should include them here
Commit to Your Git Repository
Secure Your Solution
Before you build and deploy your solution you should take a moment to familiarize yourself with the various security configurations in Cloud Portal and ideally actually start configuring them to meet your business needs.
IP Filter Sets
By default, for each of your environments the endpoints are set to "Deny All" access. You can leverage IP Filter sets to determine which IPs should have access to each of your endpoints. The IPs will likely be different for each endpoint. Some recommendations:
- Storefront endpoint will normally be the most open of all your endpoints (you want people to come to your store), so you could create an IP filter set that limits any IPs you do not want to have access to your store (e.g. you may have requirements to restrict access to certain countries) and then you would set your endpoint to "Allow All"
- API endpoint should use the same IP filter as your storefront
- Backoffice endpoint is normally an internal-only endpoint. In this case you would choose to remain with "Deny All" but your IP Filter set would include all IPs of your business (including VPNs)
- BackgroundProcessing endpoint isn't something you'll be accessing often, but should be treated similar to the backoffice endpoint above. You may want to access the endpoint for admin/troubleshooting, so ensure you either use the same IP filter set as backoffice or have one that is even more restrictive
- Solr endpoint is also something typically restricted to admin/troubleshooting, so you should leave the default "Deny All" and use either the same IP Filter as your backoffice and/or backgroundProcessing endpoints.
Although SAP Commerce Cloud provides default SSL certificates for each of its endpoints, it is recommended that you look into using your own. If you already have SSL certificates you should take a moment to add them now and update your endpoint to point to the new certificate. This way you're testing right from the start, with your certificate.
Trusted Certificates / Host Alias
If you're going to be working with external services that require special certificates you can take this opportunity to load the certificates and set up the host alias sets. Given our example doesn't have any third party integrations this configuration is more optional for the moment.
You can use the "Security Files" page in Cloud Portal to safely upload certificates, passwords, salts, tokens, and other security files to your subscription. You can then attach them to your environment so they will be picked up as part of the deployment.
Although the sample code we provided contains environment specific "local.properties" files, there is often the case where you have certain properties that are very sensitive and you don't want to check in to your source control (e.g. passwords). You won't need this for this initial deployment, but it is good to get acquainted with the process for future deployments. One option is to use static files for your sensitive data. The other option is to define the properties as part of each environment's service configuration. The downside for this option is that anyone with customer sys admin role in Cloud Portal will be able to see these properties.
The Initial Build
At this point you've confirmed your code is working locally, it's checked into your Git repository, you've configured your endpoints and managed your security settings. The next step is to build the code. The steps are outlined on this page of the product documentation. If for some reason your build fails you can see the build log, fix any issues and retry the build.
The Initial Deploy
Once your build is successful you should first try deploying it to your development environment. Given it's your first deployment you should set it to "initialize database".
Once the deployment is complete you can open up the JS Storefront endpoint's URL and you should see the Project Spartacus storefront.
If you missed any of the build/deploy steps above, you can also watch the following video, which provides a walkthrough of the process:
Monitor your Application
Each environment comes with an instance of Dynatrace Application Performance Monitoring. You should take a few moments to familiarize yourself with Dynatrace, as it is a very useful tool for monitoring your application as well as troubleshooting when issues arise.
Each SAP Commerce Cloud environment comes with its own logging endpoint. You should take this opportunity to setup your logging solution, as it can also be very helpful for troubleshooting future issues.
Removing the Accelerator
In the sample code we've also included the configurations for an accelerator-based storefront, which you can access by clicking on the Storefront endpoint's URL. If you do not want to have an accelerator storefront:
- In the "aspects" section of the manifest.json file remove the "accstorefront" section
- On each environment's page in Cloud Portal delete the "Storefront" endpoint by clicking on the trash can. In the future if you want to bring it back, you can always add a new endpoint.
See the following video which covers more about managing endpoints:
You should now have a running application in your development environment. At this point the possibilities are endless, but you'll likely want to continue to customize and integrate your SAP Commerce Cloud solution. If you're looking for more expert recommendations feel free to look at all the CX Works articles we have for SAP Commerce Cloud, as well as the best practices outlined in the product documentation.