Welcome! The purpose of this project is to give you and your business a "headstart" to building an e-commerce solution on OrderCloud. This is a complete and opinionated solution but is only meant to be a starting point to your complete solution, it is expected that you will need to make customizations to this project, after which the code is yours to own and maintain. This solution is composed of three main parts:
Want to check out the features included in headstart without having to build and deploy your own instance? We have a hosted instances that you are free to log in and check out.
URL | https://headstartdemo-buyer-ui-test.azurewebsites.net |
---|---|
Username | testbuyer |
Password | Summer2021! |
URL | https://headstartdemo-admin-ui-test.azurewebsites.net |
---|---|
Username | testadmin |
Password | Summer2021! |
There are some tasks that must be completed before you can get an instance of Headstart running. This section will walk you through each of them.
App Service - you'll need at least one app service to host the middleware API. For simplicity, we also set up one for each Buyer & Seller application though since they are static sites you have a variety of options at your disposal for how to host those.
Azure Cosmos Database - While we use the OrderCloud API to host all e-commerce data this is a complete solution that requires handling data that doesn't natively exist as part of OrderCloud API. Some examples are report templates. To that end, we are using Cosmos as our DB of choice (Core SQL). You will need one database per environment (we recommend three environments: Test, UAT, and Production).
Application Insights - This is an optional but highly recommended addition and will actually show up as an option when adding an app service. There is some additional configuration if you want to track the frontend. Look at the frontend app configs to provide your appInsightsInstrumentationKey
Storage Account - Provides all of azure data storage objects. Used to store currency conversions and translation tables. You will need a storage account for each environment (we recommend three environments: Test, UAT, and Production).
Azure App Configuration - Used to store sensitive app settings that are consumed by the backend middleware application. Checkout our guide here for configuring azure app configuration with the necessary settings. You will need an azure app configuration for each environment (we recommend three environments: Test, UAT, and Production)
This solution depends on a lot of data to be initialized in a particular way. To make it easy when starting a new project we've created an endpoint that does this for you. Just call it with some information, wait a few seconds, and presto: You'll have a marketplace that is seeded with all the right data to get you started immediately.
Detailed Steps:
/seed
endpoint with this template body. For a description of the properties please refer to the definition.OrderCloudSettings:MiddlewareClientID
OrderCloudSettings:MiddlewareClientSecret
OrderCloudSettings:ClientIDsWithAPIAccess
- ClientIDs of both the buyers and seller as a comma separated stringOrderCloudSettings:WebhookHashKey
- part of the seed requestYour backend middleware is configured and all your resources have been provisioned and your data is seeded. Now we'll need to configure your buyer and seller applications. You can have any number of configurations each representing a deployment. By default, we've created three such deployments one for each environment.
Once your frontends are up and running, consider going through the "Validating headstart setup" guide to ensure everything is configured correctly.
In order to build a complete solution Headstart is integrated with various third-party services in many categories that we are defining as "Service Providers". By default, all of these service providers are turned off and set to an empty string which indicates to the middleware to use a mocked service instead. This reduces friction when getting started however a production ready build will require some of these service providers to be enabled and credentials/configurations added to app settings, therefore we recommend getting those credentials and enabling these service providers early in the development process.
Provider | App Setting Key | App Setting Values | Required for production |
---|---|---|---|
Address Validation | EnvironmentSettings:AddressValidationProvider | Smarty | No |
CMS | EnvironmentSettings:CMSProvider | Azure | Yes |
Currency Conversion | EnvironmentSettings:CurrencyConversionProvider | ExchangeRates | No |
EnvironmentSettings:EmailServiceProvider | SendGrid | No, but highly recommended | |
Order Management System | EnvironmentSettings:OMSProvider | Zoho | No |
Payment | EnvironmentSettings:PaymentProvider | CardConnect | Yes |
Shipping | EnvironmentSettings:ShippingProvider | EasyPost | No |
Tax | EnvironmentSettings:TaxProvider | Avalara, TaxJar, Vertex | No, but highly recommended |
Sitecore Send is a platform for sending automated email campaigns. It is integrated into the storefront in order to capture events like view product, add to cart and purchase. This data can provide intelligence for abandoned cart emails, user segmentation for personalized marketing and user-history-based product recommendations.
Usage is optional and controlled with the buyer setting useSitecoreSend
. To connect Sitecore Send get a website ID and add it to buyer settings.
Sitecore Send and Ordercloud are both owned by Sitecore. You can expect the two products to be more integrated over time. SendGrid will be replaced by Sitecore Send once transactional email features are ready.
We recommend using Azure Pipelines for building and releasing your code.
We've included a YAML build configuration file that tells Azure how to:
The only small change you will need to make is to update the "Get Build Number" step and update the URL to point to your app's middleware. Information on how to use the YAML file can be found here
This project follows the build once, deploy many pattern to increase consistency for releases across environments. It accomplishes this by injecting the app configuration for the desired environment during the release phase as you'll see in the following steps. The example here is to deploy the test environment but the same process can be modified slightly for the other environments
node inject-css defaultbuyer-test && node inject-appconfig defaultbuyer-test
. This will inject both the css and the app settings for defaultbuyer-test environmentnode inject-appconfig defaultadmin-test
. This will inject the app settings for defaultadmin-test.APP_CONFIG_CONNECTION
is set on your app service and points to the connection string to your azure app configurationYou can run the project using Docker, sample docker-compose.yml file includes Buyer/Seller/Middleware as well as emulated Azure Storage via Azurite, and Cosmos DB via the Cosmos DB Emulator.
Make sure to switch daemon to Linux containers
Copy .env.template
file to .env
Add the following records to your Hosts file
From the project directory, start up your application by running docker-compose up -d
Middleware
container may take longer to start as it depends on the Cosmos emulator being healthy.docker-compose build --no-cache
Follow the steps to seed the initial data values listed in the Seeding OrderCloud Data section above.
Open .env
file and populate the rest of the variables in the REQUIRED ENVIRONMENT VARIABLES
section:
/seed
command response executed in previous step
MarketplaceID
)Restart your docker containers to make use of the new env vars by running docker-compose down
followed by docker-compose up -d
.
docker-compose restart
here as if the containers are already running then the Middleware app will restart before Cosmos is healthy.Follow the steps in the Validating Setup section above to walk through generating some sample data and testing each of the application. Access your applications from: