Running OrderCloud Headstart on Docker

What is Headstart?

Headstart is an example solution, showing you an opinionated method for building out a B2B shopping experience targeting your web channel, powered by Sitecore OrderCloud. You don’t have to follow Headstart when building your experiences using Sitecore OrderCloud, but it is meant show some example patterns that can be used to help you develop the functionality you need. Headstart is available as Open Source Software, you can find it hosted here: https://github.com/ordercloud-api/headstart

Headstart itself consists of three applications and a couple of data storage elements. The applications are the Buyer & Seller portals, alongside a Middleware application designed to implement functionality not natively provided through the OrderCloud API’s. The data storage elements are an Azure Cosmos Database and Azure Storage account, both are used to store data used to enrich the data persisted in OrderCloud.

How can you run Headstart?

There are currently two ways to run the different elements required by Headstart. Historically if you wanted to run an instance of Headstart you would have to provision the Azure resources for it. Well now that isn’t required, you can run all the different Headstart elements in Containers on your local machine.

When running locally in Docker you will have containers for all of the applications instances, as well as locally emulated Azure Storage using Azurite, and locally emulated Cosmos Database using the Azure Cosmos DB Emulator. Being able to run all the elements locally in containers makes for a much simpler way for developers to try out Headstart without having to incur the cost associated with running the different azure resources that was required previously.

Running Headstart in Docker

If you clone the Headstart repository to your local developer machine, then you will find all the source required to run Headstart in Docker. Included is a sample docker-compose.yml file defining how to run the Buyer/Seller/Middleware as well as emulated Azure Storage and Cosmos DB containers.

The containers are all configured to run from Linux base images, so you’ll need to ensure that you’ve set your docker instance to run in ‘Linux container mode’, you can read about how to do that here.

If look in the root of the repository then you will see there is a .env.template. The first thing we need to do is to duplicate this file and name it .env. This new file will be used to store all the environment variables that are required for Headstart to run.

Earlier I mentioned that there are three different applications that are included as part of Headstart. For you to be able to access these, you will need to update your host file to include the URL’s that they will be accessible on:

• 127.0.0.1 buyer.headstart.localhost
• 127.0.0.1 seller.headstart.localhost
• 127.0.0.1 api.headstart.localhost

We’re now at the point we need to seed our initial data into our OrderCloud instance. Luckily the Middleware application is configurated to do all the seeding for us, so what we need to do now is to start the application instances. You can do that by running the following command

docker-compose up -d

This will first build the images and then run all of them, note that the Middleware container may take longer to start than the others as it depends on the Cosmos emulator being healthy and ready to serve data.

Once the containers have all started and are reporting a healthy state then its time to seed our OrderCloud instance with the required data to run the Headstart applications. You can achieve this by following the Seeding OrderCloud Data section of the readme. This will talk you through using Postman to send the initial seed request to the middleware application.

This seed request will provision all the initial data items in OrderCloud like the Marketplaces, Security Profiles, & API Clients amongst other things. When the request completes it will return a series of values back that we’re going to use to update the .env file we created earlier.

• SELLER_CLIENT_ID
• BUYER_CLIENT_ID
• OrderCloudSettings_MiddlewareClientID
• OrderCloudSettings_MiddlewareClientSecret
• SELLER_ID (This should be set to the MarketplaceID returned)

The final setup piece we need to do is to create accounts with EasyPost & SmartyStreets. Once you have accounts with each of those you can populate the final few required values in the .env file

• EasyPostSettings_APIKey
• SmartyStreetSettings_AuthID
• SmartyStreetSettings_AuthToken

Now we have finished populating our .env file we need to restart your docker containers to make use of the new env vars, we do this by running

docker-compose down 
docker-compose up -d.

Note you can't run a docker-compose restart here as the containers are already running and the Middleware app will restart before Cosmos is healthy which will cause issues.

Once all of the containers have started again, we can following the steps in the Validating Setup section of the repo to walk through generating some sample data and testing each of the application instances. Then you’re finished, you now have a functioning B2B marketplace ready for you test out Sitecore OrderCloud.

How to use Headstart

I wanted to finish up by talking about the intended use cases for Headstart. As I mentioned at the start of this article Headstart is an example solution, showing you an opinionated method for building out a B2B shopping experience targeting your web channel, powered by Sitecore OrderCloud. It’s an example of one type of eCommerce site you can build using OrderCloud but it’s not the only type, OrderCloud also supports B2C, Marketplace and many other eCommerce scenarios.

So how can you leverage Headstart for your build? Well that depends on your scenario, if you’re building a B2B store focusing on the web channel then it may be a close enough fit that you can clone the Headstart repository and use that a base, removing any integrations/features you don’t need then adding any new ones that you do.

There will however be a lot of builds that aren’t an exact fit for the scenario that Headstart is built for, so how can you still leverage it in that case? Well, then the best way I see is to use this repository as a collection of example code. Once you start your implementation, you’re no doubt going to have to integrate a list of different 3rd parties for a variety of different reasons. Things like Payments, Tax, Shipping, etc are generally managed by either 3rd party systems or internal systems that you will need to integrate with. If you look through the Headstart repository you will see sample integrations with systems for features such as

• Tax
• Payments
• Shipping
• Address Validation
• Transactional Emails
• Customer Tracking
• ERP Integration

The chances are you will be using different 3rd parties to the examples you can see in Headstart, so you won’t be able to copy the code as is, however you can use the examples as a guide. They will show you key things like which API calls need to be made and at which part of the process, where in the data model the returned information should be stored, which API calls can be made to retrieve the data needed to send to the 3rd party etc.

So just to reiterate, you may be able to use Headstart as a starter kit in some specific scenarios where you can base your solution off it. However, even if your scenario is very different it can still be a valuable collection of examples to guide you in the best way to build out your implementation.