brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk11
- v1.0.0-latest-prod
The Intellij IDE is a great tool for developing on top of Broadleaf Commerce (the majority of our team uses it to develop the Broadleaf framework itself) and highly recommend it as the primary IDE for backend API development. This guide will take you through the steps to setup the Broadleaf Flex Package starter project in IntelliJ so that you can modify, build and run it.
IntelliJ 11 or above or IntelliJ Ultimate Edition (recommended) for enhanced Spring and database support (this guide was written against version 2019.3)
|
Important
|
The following assumes you have obtained credentials outlined in the guide: Getting Started Locally. |
You will need Java 11 installed on your machine.
e.g. MacOS QuickStart using Homebrew
brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk11You will need to have Docker Engine & Docker Compose installed locally
|
Tip
|
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.
Type the following into your CLI:
docker login repository.broadleafcommerce.com:5001When prompted, type in the username and password you were given.
|
Important
|
You’ll also want to configure Docker settings to use appropriate resources. A good rule of thumb is to allow Docker to consume around 3/4 of your system resources as necessary. At a minimum, you will want to allocate at least 2 CPUs and 4-6 GB Memory Ideally for a developer machine, you will want to allocate something like: 6 CPUs, 8 GB Memory, 4 GB Swap. |
You’ll need to either have
Maven 3.5 or later installed locally, utilize the ./mvnw wrapper included with the starter project, or leverage the maven facilities that come with your IDE.
Regardless of how you invoke Maven, you’ll need to configure authentication to Broadleaf’s Nexus repository in order to build the project and pull down Broadleaf artifacts. You can specify these credentials in a
file called settings.xml.
Create a file called settings.xml with the following contents making sure to
replace the credentials with the specific Nexus credentials you were given.
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<servers>
<server>
<id>broadleaf-microservices</id>
<username>username_here</username>
<password>password_here</password>
</server>
</servers>
</settings>If you’re using Maven via your IDE, you should make sure your User Settings File is pointing to the correct settings.xml file which contains the Broadleaf nexus credentials. For example:
Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory
In IntelliJ: verify that Preferences > Build, Execution, Deployment > Build Tools > Maven > User Settings File is pointed to the correct settings.xml file
If you are using the ./mvnw wrapper, you’re going to need to inform the executable of Broadleaf’s nexus credentials.
Either:
Move the settings.xml file created above into the wrapper folder (there will be a .mvn/wrapper direcory in the root of the starter project)
Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory
Certain Flex Package local configurations require an update to your /etc/hosts file. For example, with the Min Flex Package composition, the indexer service will be deployed as a separate Docker image from the search service that is running outside a docker container. In this case, it is required that you add an entry to your hosts file, e.g. /etc/hosts, with a mapping between 127.0.0.1 and localsolr:
127.0.0.1 localsolrThis Spring Boot starter project is structured in a manner that is meant to demonstrate various Flex Package compositions of the framework.
|
Note
|
A FlexPackage is a configuration and packaging concept for Broadleaf allowing multiple microservices to exist in a single JVM runtime under a single Spring instance. This means that beans are for the most part shared, allowing increased economy in resource outlay. The FlexPackage performs smart routing of data and persistence to the correct, separate backing datastore for each contained microservice. |
You’ll notice this high level folder structure:
Starter/
├── flexpackages/
│ ├── balanced
| | ├── browse
| | ├── cart
| | ├── processing
| | ├── supporting
| | └── docker
│ ├── common
| | └── docker
│ ├── granular
| | └── docker
│ └── min
| └── docker
└── services/
├── adminnav
├── adminuser
├── asset
├── campaign
├── cart
└── ...min emits a single FlexPackage consisting of almost all the core commerce services bundled together as part of the maven lifecycle. This would represent the most minimal deployment footprint. Note that with min , the indexer is deployed as a separate service.
balanced consists of 4 FlexPackages (browse, cart, processing, and supporting).
granular doesn’t emit a java artifact itself - rather - it is a holding area for the granular docker builds that refer to the individual services defined in the project services directory. This configuration would represent deploying each service individually.
|
Tip
|
The min Flex Package Composition is recommended as a good default starting point for most local development use cases, whereas the balanced Flex Package Composition is recommended for production environments.
|
They reflect the broadleaf services
Each leverages a BLC dependency as a starting point
This is where customizations & new code should be added
Customizations should be mindful of the type of service (resource vs orchestration) & the bounded context
We recommend that these projects reflect the same package structure as the BLC dependency
See flex package poms to understand how these services are organized within each application
Each of the maven subprojects here is meant to reflect the Broadleaf services that you intend to include in your project. Each of these projects depends on a specific Broadleaf service, providing a starting point for your version of that service. For example, the cart service depends on com.broadleafcommerce.microservices:broadleaf-cart-services.
From there, the cart subproject is where you’ll want to provide any customizations (extensions/overrides or new code) for your cart representations. As you make customizations, there are a few things to keep in mind:
Be mindful of the type of service that you’re customizing.
If you’re customizing an orchestration service like CartOperationServices, then you likely should not introduce a persistence component. Instead, you should pass off to a resource-tier service for persistence. A good example of this is the interaction between CartOperationServices and CartServices, where CartOperationServices coordinates actions against the cart, but it passes off to CartServices for querying/persisting the cart.
If you’re customizing a resource-tier service, then you likely should not introduce a component that directly communicates with another resource-tier service or add another resource-tier service as a dependency. While this technically can be done, we recommend maintaining the bounded contexts of the resource-tier services so that they remain decoupled. This will help to enable you to reorganize your flex packages in the future if needed.
Each of these service subprojects produce a single .jar during the maven lifecycle, which is then pulled into the various Flex Package compositions, adding that service to a specific Spring Boot application.
For each of the Flex Package examples, there are some key components to take note of:
docker-compose.yml - this is the main entrypoint for initializing one of the Flex Package compositions.
This defines some supporting services that are required to run the full scope of these examples.
See this FAQ: "[faq-supporting-services]" to get a description about each of these images
pom.xml - (except for granular) this defines which microservice dependencies that will be utilized
for that Flex Package (e.g. catalog, catalog browse, pricing, offers, etc… for the browse Flex Package)
src/main/resources/application-default.yml - this file configures a few default
properties needed for that particular Flex Package composition (including database configuration and initialization parameters)
Click Import Project on the IntelliJ welcome window.
Select the pom.xml in the root of the Flex Package API starter project (e.g. MicroservicesDemo) that you received.
At this point, IntelliJ should have detected the Spring Boot project and should have a structure loaded resembling the following :
In addition, IntelliJ should have detected multiple Spring Boot Run Configurations and will give you a list of all mounted Spring Boot main classes under the Run Configurations dropdown.
|
Note
|
the Flex Package Starter Project demonstrates multiple ways to run the backend microservices which is why there are so many runnable configurations. See the Deployment Flexibility article for more details around Broadleaf’s Flex Package technology
|
To make things more streamlined, we recommend re-ordering and re-naming some of the mounted spring boot configurations so that we have the most commonly used ones listed up top and more easily accessible. (The rest of this guide will follow this convention)
We recommend renaming and re-ordering the following configs accordingly:
Prefix MicroservicesDemoApplication with Min -
Prefix IndexerServicesApplication with Min -
Prefix MicroservicesSupportingApplication with Balanced -
Prefix MicroservicesBrowseApplication with Balanced -
Prefix MicroservicesCartApplication with Balanced -
Prefix MicroservicesProcessingApplication with Balanced -
|
Tip
|
use the arrows up top to move certain frequently used configurations to the top |
In the end, your configuration list may look something like this:
|
Important
|
If running the Min Flex Package composition, you will also want to set the Spring Active Profiles localdev,min on the Min - IndexerServicesApplication
|
Now that we have our workspace setup, we can go ahead and build the project. Right click the main project, and click Run Maven > clean install
|
Note
|
It may take some time during the initial installation as the process needs to download all required dependencies. All subsequent builds should go much faster. Also note that running a build at the root of this project will build ALL Flex Package examples ( |
|
Note
|
For the sake of simplicity, the following instructions will walk through starting the |
Before you start up all the APIs, you’ll need to first start up a few supporting services that are required for this starter. These services are provided via docker images and can be run and started from IntelliJ’s Terminal by navigating to the root of this project and running:
cd flexpackages/min/docker
docker-compose up -d && ./check-services-status.sh
|
Note
|
The above command starts the creation process of all the supporting services using This shell script will wait (for a period of time) to verify that all supporting services have started up before exiting |
Once the supporting docker images have started up, you can launch the spring boot flex packages via the IDE using the mounted Spring Boot Configurations. Click the Run/Debug button for the following:
Min - MicroservicesDemoApplication
Min - IndexerServicesApplication
That’s it! Once you’ve verified that the supporting services and backend APIs are running, you can visit the administration console and the consumer storefronts from a browser:
|
Important
|
If you are having issues visiting the storefront links, you will either need to set up DNSMasq
in order to map URLs to We recommend using Chrome since the above should be handled automatically. You’ll also want to enable insecure localhost by visiting: chrome://flags/#allow-insecure-localhost |
Admin Console: https://localhost:8446
Username: master@test.com
Password: Pass1word!
Storefront 1: https://heatclinic.localhost:8456
Storefront 2: https://aaahotsauces.localhost:8456
|
Note
|
Remember to shutdown your docker services when finished in order to free up resources i.e. |
One of the main workflows that encompass working with the Broadleaf Framework is being able to view and debug sources. In this example we’ll show you how to add a breakpoint to a framework controller endpoint.
First, you’ll want to search for the class CatalogBrowseEndpoint. You can use IntelliJ’s Edit > Find > Find in Path support to search for this class. This class is actually an OOB Framework Controller that is located in the broadleaf catalog-browse services jar.
Once you’ve found that class, IntelliJ will prompt you to download sources. From here, you can add a breakpoint to the class like so:
Once you have this breakpoint set, you can visit the following customer storefront URL to invoke this endpoint: https://heatclinic.localhost:8456/details/hot-sauces/green-ghost
Visiting this endpoint should cause IntelliJ to invoke the breakpoint where you can now step through the code and inspect the variables as necessary
IntelliJ has a built-in database explorer and can be used to navigate and view the postgres DB that is launched with the rest of the supporting utility services in the starter.
In IntelliJ, add a new PostgreSQL datasource with the following configuration:
|
Note
|
the default password for the starter postgres instance is demo
|
You’ll also want to make sure that you enable the See All Schemas option for this datasource as well
Once you have the configuration, you should be able to connect to the running postgres service and browse the default schemas and tables that have been created.
