- v1.0.0-latest-prod
The following guide is applicable to initializr/manifest-based projects (Release Train 1.8.4+) and requires credentials to access various Broadleaf resources referenced in Getting Started Locally. Please read this section and have the appropriate local environment setup configured before proceeding.
When working with microservices, integration with a CI/CD workflow is an integral step in ensuring a smooth SDLC process for both your developers and SRE teams.
For those that would like support with DevOps and operational concerns related to working with a Broadleaf implementation, Broadleaf provides a fully managed cloud offering called Broadleaf Cloud as well as DevOps Managed Support Services. These offerings provide many benefits including a fully managed pipeline catered to building out a Broadleaf ecosystem. More details on other capabilities that we can provide in this area can be found here.
For those that have a mature DevOps practice and have the capabilities to set up, manage, and operate a Broadleaf Microservices internally with their own teams, we provide general guidance on some common considerations needed to integrate the Broadleaf ecosystem into your organization’s workflow.
At a minimum, we assume that implementations have these tools to successfully work with and build a Broadleaf Project
Version and Source Control (i.e. GitHub, BitBucket, GitLab, etc…)
Build Tool (e.g. Jenkins, Cloud Native Pipelines)
with ability to handle multiple types of artifacts and builds
Access to Broadleaf’s Container Registry (i.e. docker login repository.broadleafcommerce.com:5001)
Access to Broadleaf’s Nexus Repository (i.e. repository.broadleafcommerce.com)
Your own Artifact Registry (e.g. Sonatype Nexus, Artifactory, Google Artifact Registry, Azure Artifacts, AWS CodeArtifacts, etc…)
Your own Container Registry (e.g. Sonatype Nexus, Artifactory, Google Container Registry, Azure Container Registry, Amazon ECR, etc…)
The following guide describes the anatomy of a Broadleaf Microservices project and how we would recommend structuring and incorporating your own build and integration tools into the project.
Because we recommend that most enterprises start by deploying the Balanced Flex Package, this guide and most of the examples you will see on this developer portal will be catered to deploying the Balanced Flex Package composition by default.
If you’re unfamiliar with the topology of the BalancedFlex Package, we recommend reviewing this High Level Architecture Overview describing the specifics of aBalancedcomposition.
Your build tool and pipelines should be configured to support producing multiple types of artifacts and deployable(s). In general, here are the main types:
Manifest Component (Java/Spring Boot-based) - The Broadleaf manifest component is a simple Spring-based project that contains 2 primary configurations: a pom.xml defining some Broadleaf Dependencies as well as a manifest.yml file containing holistic system configuration that tells the Broadleaf ecosystem how each of the microservices should work with each other. The primary expected artifact produced by this component is a *.jar file (typically built using Maven) which will be referenced by the other component types described below. More details around the Broadleaf Manifest can be found here.
Library Component (Java/Spring Boot-based) - a library component represents an extension to one of Broadleaf’s microservice libraries. An implementation would include a reference to a Broadleaf service JAR in their own pom.xml to extend, override, or implement any specific customization which you can then build your own version of that service library. The primary expected artifact produced by this component is a *.jar file (typically built using Maven) which can then be referenced in other Flex Components. This diagram represents the typical project pipeline workflow for a library component:
Flex Component (Java/Spring Boot-based) - a flex component represents a deployable and runnable set of one or more Microservice library components. An implementation would include a reference to a Broadleaf service JAR OR an extended library component (if your implementation contains any customizations). There are 2 primary expected artifacts produced by this component type (typically built using Maven): First is a *.jar file which can be referenced by the Data Component and secondly, an actual Container Image that represents the runnable application in your containerized environment. This diagram represents the typical project pipeline workflow for a flex component:
Data Component (Java/Spring Boot-based) - the Data module is a simple CommandLineRunner Spring Boot application that is intended to run liquibase changelogs and changesets associated with versioned Flex and Library Components. This module supports parallelization and can update multiple schemas and datasources at the same time. The primary expected artifact of this component is a Container Image file (typically built using Maven and containerized using Docker). This component has a dependency on the flex component library JARs produced above. More details on the Data module can be found here.
Frontend Application (Node/React) - these represent our accelerator applications (e.g. the backend admin or the example customer storefront). The primary expected artifact of this type of component is a Container Image file (typically built using yarn and containerized using Docker)
Supporting Component - these represent optional components of the ecosystem that you may or may not need to customize based on your specific implementation. Broadleaf provides production-ready container images that implementations can use out-of-box if there is no need to do any customizations.
The reference diagram below showcases a typical Balanced Flex Package project structure (created from start.broadleafcommerce.com), how we recommend structuring corresponding git repositories, and how those repos are hooked into a build pipeline to produce the expected artifacts and resources.
auth (Flex Component) - a Java/Spring Boot project emitted with the Balanced configuration. Build pipeline expected to produce both a .jar and a container image
browse (Flex Component) - a Java/Spring Boot project emitted with the Balanced configuration. Build pipeline expected to produce both a .jar and a container image
cart (Flex Component) - a Java/Spring Boot project emitted with the Balanced configuration. Build pipeline expected to produce both a .jar and a container image
data (Data Component) - a Java/Spring Boot project. Build pipeline expected to produce a container image. This component depends on .jar files produced by the Flex Components
manifest (Manifest Component) - a Java/Spring Boot project. Build pipeline expected to produce a .jar file
processing (Flex Component) - a Java/Spring Boot project emitted with the Balanced configuration. Build pipeline expected to produce both a .jar and a container image
supporting (Flex Component) - a Java/Spring Boot project emitted with the Balanced configuration. Build pipeline expected to produce both a .jar and a container image
[service]Component (Library Component) - a Java/Spring Boot project that represents a customization to a core Broadleaf Microservice (e.g. Catalog, Cart, Offers, etc…). The build pipeline is expected to produce a .jar file which can be referenced and pulled in by one or more Flex Components
adminweb (Frontend Application) - a Node/React application that works in conjunction with Broadleaf’s headless microservice APIs. The build pipeline is expected to produce a containerized image
commerce-nextjs-starter (Frontend Application) - a Node/React application that works in conjunction with Broadleaf’s headless microservice APIs. The build pipeline is expected to produce a containerized image
gateways (Supporting Component) - a Java/Spring project that provides a simple gateway layer (i.e. commercegateway and admingateway) built using Spring Cloud Gateway. If you need to customize the routes or enhance the proxy gateway logic by adding additional filters, you can extend Broadleaf’s implementation and build your own. If enabled, the build pipeline is expected to produce a containerized image
solr (Supporting Component) - this is a "Broadleaf-flavored" version of Solr that adds additional schema, configuration files, and installation scripts that are specific to enable a Broadleaf implementation using Solr as the backing search engine. It is not very common that implementations would need to customize this, however if you do, you can build on top of this project to produce your own containerized image instead
configserver-[ENV]-[secure/insecure] (Supporting Component) - these are just Git Repositories that back Spring managed property files (e.g. .yaml and .properties) for use as a backend storage for the Config Server. See Enhanced Environment Configuration for more details
In general, you will want to first identify and parameterize these common resources (as well as any appropriate credentials to connect to each):
Your own Container Registry
Your own Artifact Repository
Broadleaf’s Container Registry (i.e. docker login repository.broadleafcommerce.com:5001)
Broadleaf’s Nexus Repository (i.e. repository.broadleafcommerce.com)
Source Control (i.e. GitHub, BitBucket, GitLab, etc…)
As you may have noticed, certain "build types" depend on artifacts that are produced by other builds. In this case, we recommend setting up "dependent build triggers". There are multiple ways to accomplish this based on the capabilities of your build tool and is outside the scope of this guide. In general, here is the order of precedence as it relates to the different build types in the ecosystem:
manifest - the Manifest Component drives a lot of holistic configuration and is a dependency to many other components. Any changes to this component should trigger downstream builds
library component - the Library Component encompasses changes to only the "service bounded context" in which it operates, however this library component may be referenced or shared in different flex components. A change here should trigger downstream builds for any flex component that has a dependency on a specific library component
flex component - a Flex Component represents a deployable group of one or more library components. The build pipeline also produces a .jar which is used in the data component. Any changes here should trigger a downstream build for the data component.
data component - The data component is the last in the line of dependencies and may encompass changes and updates from all the above
Summary: manifest → library component → flex component → data component
frontendandsupporting components- these are typically independent and do not rely on any dependency build chain. These can be built by themselves
Authenticate with Broadleaf Microservices Nexus
Authenticate with your artifact registry
Login to Broadleaf’s Container Registry (if a Flex Component)
Login to your Container Registry (if a Flex Component)
Perform Maven Build (e.g. mvn deploy -DskipTests=true)
Push Jar Artifacts to your Registry
Logout of Broadleaf Repository
Logout of your Artifact Repository
Build Docker image (e.g. docker build --build-arg… or mvn clean package -Pdocker…) (if a Flex Component)
Push Docker image to your Container Registry (if a Flex Component)
Logout of Broadleaf Registry
Logout of your artifact registry
everything above except we typically recommend using the mvn release plugin to tag versions and commit to source control
Authenticate with Broadleaf Microservices NPM Repository
Install Node or use appropriate pipeline task equivalent
Install Yarn (e.g. yarn install --frozen-lockfile)
Build App (e.g. yarn build)
Test Coverage (e.g. yarn test:coverage)
Login to your container registry
Build Docker image (e.g. docker build)
Push Docker image to your container registry
Logout of your container registry