Broadleaf Microservices

IntelliJ Setup

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.

Prerequisites

  • IntelliJ 11 or above or IntelliJ Ultimate Edition (recommended) for enhanced Spring and database support (this guide was written against version 2019.3)

System Configuration

Important
The following assumes you have obtained credentials outlined in the guide: Getting Started Locally.

Java

You will need Java 8 or 11 installed on your machine.

e.g. MacOS QuickStart using Homebrew

brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk11

Docker

You 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:5001

When 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.

Maven

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.

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:

  1. Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory

  2. 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

Maven Installed Locally

If you already have Maven installed locally, you can create a settings.xml file in the .m2 subdirectory of your a user’s home directory.

  • Create a folder called .m2 in your home directory and (i.e. ~/.m2/settings.xml) move the settings.xml file into that directory

Tip

More info about authenticating with private repositories can be found here and here

Host File

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 localsolr

Project Structure Overview

This 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
    └── ...

flexpackages/

  • 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.

services/

  • 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.

Important Pieces

For each of the Flex Package examples, there are some key components to take note of:

  1. 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

  2. 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)

  3. 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)

Setting Up The Project

Click Import Project on the IntelliJ welcome window.

IntelliJ Import Project Window

Select the pom.xml in the root of the Flex Package API starter project (e.g. MicroservicesDemo) that you received.

IntelliJ choose pom.xml

At this point, IntelliJ should have detected the Spring Boot project and should have a structure loaded resembling the following :

IntelliJ Project Structure

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.

IntelliJ Spring Boot Run Configuration List
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:

  1. Prefix MicroservicesDemoApplication with Min -

  2. Prefix IndexerServicesApplication with Min -

  3. Prefix MicroservicesSupportingApplication with Balanced -

  4. Prefix MicroservicesBrowseApplication with Balanced -

  5. Prefix MicroservicesCartApplication with Balanced -

  6. 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:

IntelliJ Spring Boot Run Configuration Tips
Important
If running the Min Flex Package composition, you will also want to set the Spring Active Profiles localdev,min on the Min - IndexerServicesApplication
IntelliJ IndexerServicesApplication Min Config Active Profile

Building

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

IntelliJ mvn 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 (balanced, min, and granular)

Running

Note

For the sake of simplicity, the following instructions will walk through starting the min flex package

Starting up Supporting Utility Services

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
IntelliJ Terminal - docker-compose up
Note

The above command starts the creation process of all the supporting services using docker-compose. We’ve also included a script to "tail" all the relevant containers and verify successful startup.

./check-services-status.sh

This shell script will wait (for a period of time) to verify that all supporting services have started up before exiting

IntelliJ Terminal - docker-compose started

Starting up Spring Boot Flex Packages

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

IntelliJ Min Started
IntelliJ Indexer Started

Done

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 localhost or set up /etc/hosts with the heatclinic and aaahotsauces subdomains.

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

Note

Remember to shutdown your docker services when finished in order to free up resources i.e. docker-compose down

Debugging

Downloading Sources & Adding Breakpoints

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:

IntelliJ Adding a Breakpoint

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

IntelliJ Debugging

Visiting this endpoint should cause IntelliJ to invoke the breakpoint where you can now step through the code and inspect the variables as necessary

Connecting to the Postgres DB

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.

IntelliJ Add Postres DB

In IntelliJ, add a new PostgreSQL datasource with the following configuration:

IntelliJ Docker Postgres Connection
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

IntelliJ Docker Postgres Show All Schemas

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.

IntelliJ Docker Postgres Connected Successfully

Viewing Log Output of the Supporting Docker Services

IntelliJ also has built-in docker support. By clicking on the services window, you can right click on the docker service, connect, and view all running containers.

e.g. you can view the log output of the Auth docker service like so:

IntelliJ Connect to Docker Service