Broadleaf Microservices
  • v1.0.0-latest-prod

Getting Started with Broadleaf Microservices

If you haven’t already, we first recommend following the Broadleaf Microservices API Tutorial. This tutorial focuses on working with the out-of-box backend APIs from a consumer/client perspective using your own provisioned demo instance on Broadleaf Cloud (without having to run any backend code locally). When you’re ready to extend the APIs or looking to run the backend APIs on your own machine, follow the steps below to get your local environment setup to run the full suite of commerce microservices.


Broadleaf provides a collection of reference accelerator projects allowing a developer to work with the entire Broadleaf microservice ecosystem on a local machine.

These projects are intended to give you a hands-on look at core framework concepts and key extension patterns. Additionally, these projects provide a good foundational starting point to begin building customizations for your specific commerce implementation.

The framework includes 30+ microservices containing extensible commerce service components built on Java and Spring as well as a centralized metadata-driven back office admin framework built in React.

What Do I Need?


In order to get started running Broadleaf Microservices locally, you will need to obtain a few resources and credentials before working through the installation instructions outlined below.


Contact for information on how to obtain the latest versions of these starter projects and repository credentials.

Broadleaf licensed clients get access to Broadleaf’s Docker Registry, Maven Nexus, and NPM Repository in order to build and run these starter projects. Once you have obtained these credentials, you will need to configure them appropriately (which will be outlined in the relevant sections below). To be eligible for credentials, users must have a Broadleaf Enterprise or Evaluation License.

An Integrated Developer Environment (IDE)

We also recommend that you have an IDE(s) setup that can support Java and Spring development from a backend commerce API perspective and React/Next.js application development from a frontend consumer experience perspective. Popular choices that we recommend include IntelliJ IDEA and Visual Studio Code.


You will need either Java 11 or Java 17 installed on your machine. We recommend Adoptium Eclipse Temurin. See more details about supported Java versions here.


In order to run the supporting services (e.g. Zookeeper, SOLR, Kafka, etc…​) that underpin the Broadleaf ecosystem, you will need to have Docker Engine & Docker Compose installed locally.

Docker Desktop for both Mac and Windows already includes compose along with other docker apps.

Once you have docker installed, you will want to authenticate with Broadleaf’s docker registry enabling you to pull down Broadleaf container images.

docker login

When prompted, type in the username and password you received above.

How Do I Get Started?

The quickest way to get started would be to generate a project using Broadleaf’s Project Intializr:

We recommend reading about some project changes and enhancements that have been introduced with Broadleaf Initialzr (especially if you have experience working with older versions of Broadleaf Microservices).

Generate a Broadleaf Manifest

  1. Go to

  2. Pick the Broadleaf Release Train that you would like your project to target. If you are unsure or this is your fist time evaluating Broadleaf, pick the latest stable version.

  3. Choose a Flex Package Deployment Option. If this is your fist time evaluating Broadleaf, we recommend choosing the Mono (also called the one) Flex Package option.

  4. Configure a Group and Package Name specific to your company or implementation (e.g. com.mycompany.microservices)

  5. Choose dependencies for your specific implementation. We recommend Postgres and Kafka as good default starting points.

  6. If you know what commerce microservices you wish to extend and customize, pick them here. If you are unsure or this is the first time evaluating Broadleaf, we recommend that you just skip this section as you can easily modify your project later.

  7. If you are just evaluating Broadleaf, we recommend checking the box that Enables Demo Data

  8. Click Generate to download a zip file to your local machine.

  9. Unzip the downloaded file and review the file included in the manifest project. Follow the instructions to generate, build, and run the suite of Broadleaf Microservices on your machine.

once you have your choices made on the Initializr, you can also click "Explore" to preview the manifest project output

High Level Topology Diagram

The following diagram illustrates the topology of all the resources and components that make up the full suite of Broadleaf Microservices once everything is deployed and running.

Topology Example Diagram

The overall topology can be broken down into a few functional tiers:

  • Gateways - the reference architecture provides 2 example proxy gateways: one for requests to back-office/internal applications and APIs called the admingateway, and another to route requests to a consumer experience/storefront frontend and related APIs called the commercegateway

  • Frontend Applications - these are reference Node.js/React applications that provide interfaces to interact with the headless commerce APIs. These applications include a backoffice admin console intended for merchandisers, content managers, vendors, CSRs, etc…​ an Open API UI which provides a useful interface for developers to understand how to use and consume the out-of-box commerce APIs, and finally an example storefront accelerator that is used to demonstrate how to create a best-practice consumer-facing storefront application

  • Headless Commerce APIs - these represent the core Broadleaf microservices that provide a lot of commerce functionality across the different services. These core services can be bundled into different Flex Packages based on business needs and overall deployment intentions

  • Supporting Services - Broadleaf is designed to support a variety of different supporting architecture components. The framework is built on top of different abstraction frameworks allowing you to choose things like a relational database as well as a messaging broker. Our recommended defaults include Postgres and Kafka as an example.

Development and Learning Paths

There are multiple ways to experience working with the framework.

  1. General Learning Resources: Resources that outline and describe important Broadleaf Concepts and Features:

  2. From a Frontend Development Perspective: Here are a few resources catered to frontend developers and to those developers looking to create a consumer facing storefront experience

  3. From a Backend API Development Perspective: As a backend developer, here are a few resources catered to debugging and customizing the core Spring/Java commerce APIs:

  4. From an Operational Perspective: Here are resources catered to infrastructure and DevOps: