Tag: Headstart

Setup Sitecore OrderCloud headstart with Angular in Ubuntu system the docker way

Working on Linux system after been worked on Windows for 2 decades is always fun.

This blog post is to setup the Sitecore OrderCloud Headstart on Ubuntu the Docker way. As all the images used for the Headstart is are Linux based, this I didn’t find major difference how this is been setup in Windows system apart from few changes while installing Storage Explorer and few other erros which I have noted in this blog post.

Note – use sudo for each command or “sudo i”to run as root.

Ensure node js is installed

This might be required for your local build.

sudo apt update

sudo apt install nodejs

Ensure npm is installed

sudo apt install npm

Ensure docker and docker -compose is installed

See this blog post Install Docker on Linux

sudo snap install docker

sudo apt install docker-compose

Docker Compose

Lets start composing and solve errros that might come ourr way-

sudo docker-compose up -d

npm needs TLS1.2

npm notice Beginning October 4, 2021, all connections to the npm registry – including for package installation – must use TLS 1.2 or higher. You are currently using plaintext http to connect. Please visit the GitHub blog for more information: https://github.blog/2021-08-23-npm-registry-deprecating-tls-1-0-tls-1-1/
npm WARN @ordercloud/headstart-sdk@0.0.0 No repository field.


npm cache clear --force

npm set registry=https://registry.npmjs.org/

npm install -g https://tls-test.npmjs.com/tls-test-1.0.0.tgz

Install .Net SDK

Middleware runs on .Net. So this neds to be installed.



sudo apt-get update && \
sudo apt-get install -y dotnet-sdk-6.0
sudo apt-get update && \
sudo apt-get install -y aspnetcore-runtime-6.0
sudo apt install dotnet6

I found difficulties installing .Net on Ubuntu. You may have todo few restarts.

 docker compose up -d

This should start all the containers. Note- cosmos container takes time to start till then middleware waits and starts when comos is ready.

Comos should be available now –

Install Azure Storage- Explorer

Install Storage explorer in Ubuntu-

snapd should be already installed if you are using Ubuntu 16.04 LTS or later, you may have to update.

sudo apt update
sudo apt install snapd

Install Storage Explorer

sudo snap install storage-explorer

Open Azure Storage Explorer and follow the steps here –

Execute the command-

snap connect storage-explorer:password-manager-service :password-manager-service

Azure Storage Explorer should be able to open with above command.

Apply the same settings mentioned in this blog

Once you have followed and applied the settings mentioned in the blog, should be able to see the translation files in local storage and able to access the file.

We also have to set CQRS for blob container – lets do this later.

Middleware exited with errors-

Error –

See the resolution to this issue here – section – Unable to start Middleware container due to erros

Error – Connection refused (

System.AggregateException: One or more errors occurred. (Connection refused (
       ---> System.Net.Http.HttpRequestException: Connection refused (

See the resolution to this issue here – section – Connection to Comos DB is failing

Error- Unsupported platform

0 18.52 npm ERR! code EBADPLATFORM
#0 18.53 npm ERR! notsup Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})
#0 18.53 npm ERR! notsup Valid OS:    darwin
#0 18.53 npm ERR! notsup Valid Arch:  any
#0 18.53 npm ERR! notsup Actual OS:   linux
#0 18.53 npm ERR! notsup Actual Arch: x64

Changed the node version- see the blog here

Also changed the nginx version – see Error 4 here

 => ERROR [headstart-seller:local-linux production 4/8] RUN apk add --update nodejs nodejs-npm && npm install -g json                                                                                 1.0s

see Error 4 here

Change from this  -
RUN apk add --update nodejs nodejs-npm && npm install -g json

RUN apk add --update nodejs npm && npm install -g json
#0 51.97 npm ERR! npm ERR! Cannot read properties of null (reading 'pickAlgorithm')

See the resolution to this error here

Now you should have all containers up and running with

sudo docker compose up -d

If you see this error-

Check for Configure CORS to Blob Containers in this blog post

And here I have Seller, buyer and middleware working on Ubuntu system-

This has really opened the horizon to develop, deploy and maintain OrderCloud solution on a technology agnostic platform.


Setup Sitecore OrderCloud Headstart Project – Part 2

This blog will walkthrough step by step to setup OrderCloud Headstart Solution on your development machine.

You may want to first see Part 1 with Azurite or through Azure resources

Headstart project and instructions are here

In this blog we are setting the Sitecore Ordercloud Headstart middleware

Step 1- Create a Sitecore OrderCloud Marketplace

See this blog to setup the OrderCloud Marketplace

Create a new maketplace e.g.- OrderCloudHeadstart in Us-West region

IMP– At the time this blog was written looks like only Us-West region is supported when a seed request is sent. This may change in future but connect to OrderCloud team is you want this to be in region other than Us-West

Note the newly created Marketplace ID – in my case it is – OrderCloudHeadstart

If you havent provided the Marketplace ID whilst creating the OrederCloud will create once for you. You can find the same in the Marketplace.

Navigate to API Console and Get the Admin User, as you see there are no Admin users. You may also check other endpoints.

Step 2 – Setup Middleware

Clone headstart repository – https://github.com/ordercloud-api/headstart.git

Open Headstart.sln in src/Middleware. I am using Visual Studio 2019.

Open Headstart.API project proerties

Create a new Debug Profile for Headstart.Api project. Set this as Start project.

Run the Headstart.Api project and should listen to localhost 5000 and 5001 port

Step 3- Prepare Seed Request

Open postman and create a new Post request to – https://localhost:5001/seed

Use the below request body –

  "Portal": {
    "Username": "username@company.com",
    "Password": "XXXXXXXXXXXXXXXX"
  "Marketplace": {
    "Environment": "sandbox",
    "Region": "Us-West",
    "ID": "your-marketplace-id",
    "Name": "your-marketplace-name",
    "InitialAdmin": {
      "Username": "adminuser",
      "Password": "XXXXXXXXXX"
    "EnableAnonymousShopping": true,
    "MiddlewareBaseUrl": "http://localhost:5000",
    "WebhookHashKey": "hashkey"

PortalUsername – enter the portal username you used to create a marketplace

PortalPassword – enter the portal password you used to create a marketplace

InitialAdminUsername – this request will create a admin user. Enter the admin username you wish to create

InitialAdminPassword – enter the admin password you want to set

MiddlewareBaseUrl – this is not required for local build

MarketplaceID – Enter the Marketplace ID you created in Step 1

Marketplace.Region– enter this to be sandbox in this case. For the other environments you might want to user different values for Staging and Production

WebhookHashKey – Set the webhook haskey to secure your webhook request.

Postman request should look like this –

STEP 4 – Setup a App Configuration using appSettings.json

Use/Download the template here provided by Sitecore to setup the configuration

Create a json file on your local machine by copying the content in the template. In my case I have created OCHeadstartConfig.json. The template looks as below- Highlighted values are the minimum configuration required for Headstart project.

Following configuration(highlighted) needs to be updated minimum to send the seed request working-




 "StorageAccountSettings:ConnectionString": "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=;QueueEndpoint=;",
  "StorageAccountSettings:ContainerNameCache": "cache",
  "StorageAccountSettings:ContainerNameExchangeRates": "",
  "StorageAccountSettings:ContainerNameTranslations": "ngx-translate",
  "StorageAccountSettings:ContainerNameQueue": "queue",
  "StorageAccountSettings:HostUrl": "",
  "StorageAccountSettings:Key": "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="

Get the StorageAccount.Settings.ConnectionString from Storage Explorer-

Create appSettings.json file and copy the above configuration in the file.

appSettings.json file should be in Headstart.API project-

IMP – Check if the middleware applicaiton is running and listening to localhsot 5001 port. If not you should run the Headstart.Api before running UI application.

Step 5 – Send the seed request to Ordercloud Markeplace

Ensure the Headstart Api is running and listening to 5001 port as mentioned in Step 2

Send the seed request

You can see the same in application that is listening to 5001 port the request was sent to-

If you have set the request correctly you should receive the success response-

IMP – Note the below response and the request that was sent specifically Admin Username and Password as this will be required later when configuring the UI application

    "Comments": "Success! Your environment is now seeded. The following clientIDs & secrets should be used to finalize the configuration of your application. The initial admin username and password can be used to sign into your admin application",
    "MarketplaceName": "ocdockertest",
    "MarketplaceID": "ocdockertest",
    "OrderCloudEnvironment": "Sandbox",
    "ApiClients": {
        "Middleware": {
            "ClientID": "1141E496-8517-4953-809B-XXXXXXXXX",
        "Seller": {
            "ClientID": "6E98D7A1-35E9-4156-B60B-XXXXXXXXXX"
        "Buyer": {
            "ClientID": "E1EBE13C-CC74-4021-B4A9-XXXXXXXXXX"
    "Success": true,
    "Exception": null

Comments – seed response comments

MarketplaceName – gets the Marketplace name that was configured in Step 1

MarketplaceID – UniqueId that was sent as part of request and the data seeded in this Marketplace

OrderCloudEnvironment – Environment where the request was sent

ApiClients.Middleware.ClientID – Note down Middleware ClientID

ApiClients.Middleware. ClientSecret – Note down Middleware ClientSecret

ApiClients.Seller.ClientID – Note down the Seller ClientID

ApiClients.Buyer.ClientID – Note down the Buyer ClientID

Step 5- Check the Marketplace for the data been puplated

In Step 1- we saw there was not admin user created. After the seed request you can see the Admin User is created with the name mentioned in request.

Admin User

InitialAdminUser with the username provided in request is created

Also the MiddlewareIntegrationsUser is created

Buyer User

Buyer User is created-

Api Clients

Api clients created and the same was sent as response. This is used so each client have a different Id’s that helps any application to connect.


Ensure the StorageAccountSettings:HostUrl and ConnectionString is configured correctly.

Thats it in this blog. Hope you are enjoying setting your Ordercloud Headstart project.


Setup Sitecore OrderCloud Headstart project using Azure Resources – Part 1

Follow below steps to configure Sitecore Ordercloud Headstart middleware using Azure Resources

Step 1 – Setup a Azure App Configuration

Since we will be now setup a backend application (i.e. admin etc) the Client IDs and Client Secret that was create in Step 5 needs to be secured. This can be condifured in Azure App Configuration. See the link on how to setup this.

Use/Download the template here provided by Sitecore to setup the configuration

Create a json file on your local machine by copying the content in the template. In my case I have created OCHeadstartConfig.json. The template looks as below-

    "ApplicationInsightsSettings:InstrumentationKey": "",
    "AvalaraSettings:AccountID": 0,
    "AvalaraSettings:CompanyCode": "",
    "AvalaraSettings:CompanyID": 0,
    "AvalaraSettings:LicenseKey": "",
    "AvalaraSettings:BaseApiUrl": "https://sandbox-rest.avatax.com/api/v2",
    "StorageAccountSettings:ConnectionString": "",
    "StorageAccountSettings:BlobPrimaryEndpoint": "",
    "StorageAccountSettings:BlobContainerNameQueue": "queue",
    "StorageAccountSettings:BlobContainerNameCache": "cache",
    "StorageAccountSettings:BlobContainerNameExchangeRates": "currency",
    "StorageAccountSettings:BlobContainerNameTranslations": "ngx-translate",
    "CardConnectSettings:Authorization": "",
    "CardConnectSettings:AuthorizationCad": "",
    "CardConnectSettings:BaseUrl": "cardconnect.com",
    "CardConnectSettings:CadMerchantID": "",
    "CardConnectSettings:Site": "fts-uat",
    "CardConnectSettings:UsdMerchantID": "",
    "CosmosSettings:DatabaseName": "",
    "CosmosSettings:EnableTcpConnectionEndpointRediscovery": "false",
    "CosmosSettings:EndpointUri": "",
    "CosmosSettings:PrimaryKey": "",
    "CosmosSettings:RequestTimeoutInSeconds": "15",
    "EasyPostSettings:APIKey": "",
    "EasyPostSettings:FreeShippingTransitDays": "3",
    "EasyPostSettings:NoRatesFallbackCost": "20",
    "EasyPostSettings:NoRatesFallbackTransitDays": "3",
    "EnvironmentSettings:AppTimeoutInSeconds": "30",
    "EnvironmentSettings:MiddlewareBaseUrl": "",
    "EnvironmentSettings:BuildNumber": "",
    "EnvironmentSettings:Commit": "",
    "EnvironmentSettings:Environment": "Test",
    "EnvironmentSettings:TaxProvider": "Avalara",
    "FlurlSettings:TimeoutInSeconds": "40",
    "OrderCloudSettings:ApiUrl": "https://sandboxapi.ordercloud.io",
    "OrderCloudSettings:MiddlewareClientID": "",
    "OrderCloudSettings:MiddlewareClientSecret": "",
    "OrderCloudSettings:IncrementorPrefix": "DB_TEST",
    "OrderCloudSettings:WebhookHashKey": "",
    "OrderCloudSettings:MarketplaceID": "",
    "OrderCloudSettings:MarketplaceName": "",
    "SendGridSettings:ApiKey": "",
    "SendgridSettings:FromEmail": "",
    "SendgridSettings:CriticalSupportEmails": "",
    "SendgridSettings:SupportCaseEmail": "",
    "SendgridSettings:BillingEmail": "",
    "SendgridSettings:OrderSubmitTemplateID": "",
    "SendgridSettings:OrderApprovalTemplateID": "",
    "SendgridSettings:LineItemStatusChangeTemplateID": "",
    "SendgridSettings:QuoteOrderSubmitTemplateID": "",
    "SendgridSettings:NewUserTemplateID": "",
    "SendgridSettings:ProductInformationRequestTemplateID": "",
    "SendgridSettings:PasswordResetTemplateID": "",
    "SendgridSettings:CriticalSupportTemplateID": "",
    "SmartyStreetSettings:AuthID": "",
    "SmartyStreetSettings:AuthToken": "",
    "SmartyStreetSettings:RefererHost": "",
    "SmartyStreetSettings:WebsiteKey": "",
    "UI:BaseAdminUrl": "",
    "ZohoSettings:AccessToken": "",
    "ZohoSettings:ClientId": "",
    "ZohoSettings:ClientSecret": "",
    "ZohoSettings:OrgID": "",
    "ZohoSettings:PerformOrderSubmitTasks": "false"

Select the subscription and Resource group

Provide the Resource name in this case I have used OrderCloudHeadStartConfig

Select Location and Pricing tier.

Once the resource is created in the Import/Export option select –

Source service – Configuration file

For language – Other

File type- Json

Source file – *.json (auto selected)

Select the folder icon in Source file option and click Apply to import the configuration.

After the config file is imported navigate to “Configuration Explorer”. There are 63 config key values are imported but in template there are 64.

“SendgridSettings:OrderApprovalTemplateID”: “”, is not imported for due to some reason. Create a new manually if required. For the Demo this is not required.

Click on the values to see the values of the key that was imported-

Set the following values by Right clicking the keys. Copy this from Step 4 where the response was received from seed request-





Continue updating config in next section for Storage Account.

Step 2- Create a Azure Storage Account (if you already don’t have)

Create a Azure Storage Account

Follow the steps and set the configuration as per your requirements

Copy the storage account name and Storage connection string

Set StorageAccountSettings:BlobPrimaryEndpoint – https://yourstorageaccount.blob.core.windows.net/occontainer

Set StorageAccountSettings:ConnectionString

Thats in in this blog. In next blog will cover setting up the UI project.

Hope you are enjoying setting your Ordercloud Headstart project.